Modern Python Template

📘 Documentation | 🐛 Report Bug | ✨ Request Feature | 🤖 Claude Code Setup

🚀 Features

• 🎯 Modern Python: Built for Python 3.12+ with latest language features
• 📦 uv Package Manager: Lightning-fast dependency management
• 🔧 Developer Tools: Pre-configured with Ruff, Pyright, and pre-commit
• 🤖 AI-First Development: Optimized for Claude Code workflows
• ✅ Comprehensive Testing: Pytest with coverage, parallel execution, and benchmarking
• 🔒 Security First: Integrated security scanning with Trivy and Bandit
• 🔄 CI/CD Pipeline: Advanced GitHub Actions with reusable workflows
• 📝 Type Safety: Full type annotations with strict checking
• 🎨 Code Quality: 15+ pre-commit hooks for consistent code
• 🔄 Auto Updates: Renovate bot for dependency management

📋 Table of Contents

• Quick Start
• Installation
• Usage
• Development
• Project Structure
• Contributing
• License

🏃 Quick Start

# Clone the repository
git clone https://github.com/okotaku/template.git
cd template

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync --all-extras

# Run the CLI
uv run template --name "Your Name"

# Run tests
uv run pytest

🛠️ Installation

Prerequisites

• Python 3.12 or higher
• uv package manager (recommended) or pip

Installing uv

macOS and Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Using pip

pip install uv

Setting up the project

1. Clone the repository

   git clone https://github.com/okotaku/template.git
   cd template

2. Install dependencies

   uv sync --all-extras

3. Install pre-commit hooks

   uv run pre-commit install

4. Verify installation

   uv run template --version

📖 Usage

Command Line Interface

The template provides a simple CLI for demonstration:

# Show help
uv run template --help

# Basic greeting
uv run template

# Personalized greeting
uv run template --name Alice

# Verbose output
uv run template --verbose

As a Python Package

import modules

# Get version
print(modules.__version__)

# Use functions
print(modules.hello())
print(modules.greet("World"))

🔧 Development

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov

# Run in parallel
uv run pytest -n auto

# Run specific test file
uv run pytest tests/test_basic.py

# Run with verbose output
uv run pytest -v

Code Quality

# Run all pre-commit hooks
uv run pre-commit run --all-files

# Run specific hooks
uv run ruff check . --fix
uv run ruff format .
uv run pyright modules

# Check types
uv run pyright modules tests

Additional Resources

# View changelog
cat CHANGELOG.md

# View comprehensive development guide
cat CLAUDE.md

# View project structure
ls -la

📁 Project Structure

template/
├── modules/                # Source code
│   ├── __init__.py        # Package exports
│   ├── cli.py             # CLI implementation
│   ├── version.py         # Version management
│   └── py.typed           # Type marker file
├── tests/                 # Test suite
│   ├── test_basic.py      # Basic tests
│   └── test_cli.py        # CLI tests
├── .github/               # GitHub configuration
│   ├── workflows/         # CI/CD pipelines
│   ├── actions/           # Reusable actions
│   └── *.yml             # Various configs
├── pyproject.toml         # Project metadata
├── uv.lock               # Locked dependencies
├── .pre-commit-config.yaml # Pre-commit hooks
├── CLAUDE.md             # Claude Code config
└── README.md             # This file

🤝 Contributing

This project uses an AI-first development approach. Claude Code handles primary development while humans provide guidance and review. See CLAUDE.md for comprehensive development guidelines and AI-assisted workflows.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Make your changes
4. Run tests and linting (uv run pre-commit run --all-files)
5. Commit your changes (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feat/amazing-feature)
7. Open a Pull Request

Commit Convention

We use Conventional Commits:

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• test: Test additions or modifications
• chore: Maintenance tasks

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with uv for fast package management
• Linted with Ruff for lightning-fast code quality
• Type-checked with Pyright for robust type safety
• Tested with Pytest for comprehensive test coverage
• Automated with GitHub Actions for CI/CD
• Optimized for Claude Code development

📊 Stats

---

Made with ❤️ by okotaku

⬆ Back to top