Modern Python Project Template

A comprehensive Copier template for creating modern Python CLI applications with best practices, featuring uv, pytest, click, rich, and mkdocs.

Features

🚀 Modern Python Stack

• Python 3.9+ support with type hints
• uv for lightning-fast dependency management
• Typer for beautiful CLI interfaces
• Rich for gorgeous terminal output

🧪 Testing & Quality

• pytest with coverage reporting
• Ruff for fast linting and formatting
• mypy for type checking
• pre-commit hooks for automated quality checks

📚 Documentation

• MkDocs with Material theme
• API documentation with mkdocstrings
• Comprehensive guides and examples
• GitHub Pages deployment ready

🔄 CI/CD & Automation

• GitHub Actions workflows
• Automated testing on multiple Python versions
• Code quality checks
• Documentation deployment
• PyPI publishing workflow

Quick Start

Prerequisites

• Python 3.9 or higher
• Copier (pip install copier)
• uv (recommended)

Create a New Project

# Install copier if you haven't already
pip install copier

# Create a new project from this template
copier copy gh:your-username/python-project-template my-awesome-project

# Navigate to your new project
cd my-awesome-project

# Set up the development environment
uv sync --all-extras

# Install pre-commit hooks
uv run pre-commit install

# Run tests to verify everything works
uv run pytest

# Try the CLI
uv run my-awesome-project hello --name "World"

Template Configuration

The template will prompt you for the following information:

Variable	Description	Default	Example
project_name	Display name of your project	"My Awesome Project"	"Weather CLI"
package_name	Python package name (snake_case)	"my_awesome_project"	"weather_cli"
project_description	Brief project description	"A modern Python CLI application"	"A CLI tool for weather forecasts"
author_name	Your full name	"John Doe"	"Jane Smith"
author_email	Your email address	"[email protected]"	"[email protected]"
python_version	Minimum Python version	"3.9"	"3.11"
use_github_actions	Set up GitHub Actions	true	false
license	License type	"MIT"	"Apache-2.0"

Generated Project Structure

my-awesome-project/
├── src/my_awesome_project/      # Main package
│   ├── __init__.py             # Package metadata
│   ├── main.py                 # CLI entry point
│   └── cli.py                  # Additional commands
├── tests/                      # Test suite
│   ├── conftest.py            # Pytest configuration
│   └── test_main.py           # Main tests
├── docs/                       # Documentation
│   ├── index.md               # Homepage
│   ├── installation.md        # Installation guide
│   ├── usage.md               # Usage guide
│   └── reference/             # API documentation
├── .github/workflows/          # GitHub Actions
│   └── ci.yml                 # CI/CD pipeline
├── scripts/                    # Utility scripts
│   └── setup.sh               # Development setup
├── pyproject.toml             # Project configuration
├── mkdocs.yml                 # Documentation config
├── uv.toml                    # uv configuration
├── .gitignore                 # Git ignore rules
├── .pre-commit-config.yaml    # Pre-commit hooks
├── LICENSE                    # License file
├── README.md                  # Project README
└── CONTRIBUTING.md            # Contribution guidelines

What You Get

CLI Application

A fully functional CLI application with:

# Basic greeting command
my-project hello --name "Alice"

# Rich demo with progress bars and tables
my-project demo

# Configuration management
my-project config --show
my-project config --reset

# Version information
my-project --version

Development Tools

• Fast dependency management with uv
• Code formatting with Black and Ruff
• Type checking with mypy
• Testing with pytest and coverage
• Documentation with MkDocs Material
• Git hooks with pre-commit

CI/CD Pipeline

• Multi-platform testing (Linux, macOS, Windows)
• Multiple Python versions support
• Code quality checks on every PR
• Automated documentation deployment
• PyPI publishing on releases

Documentation Site

• Beautiful Material Design theme
• API documentation auto-generated from docstrings
• Installation and usage guides
• Development documentation
• Changelog tracking

Customization

Adding New Commands

# In src/my_project/cli.py
@app.command()
def new_command(
    option: str = typer.Option("default", help="An option")
) -> None:
    """A new command description."""
    console.print(f"New command with option: {option}")

Rich Components

The template includes examples of Rich components:

• Progress bars with spinners
• Styled tables
• Colored text and panels
• Error handling with beautiful tracebacks

Documentation

Extend the documentation by:

• Adding new pages to docs/
• Updating the navigation in mkdocs.yml
• Using mkdocstrings for API documentation

Best Practices Included

Code Quality

• Type hints throughout the codebase
• Google-style docstrings for all functions
• Comprehensive error handling
• Logging setup ready for expansion

Testing

• High test coverage (>90% target)
• CLI testing with Typer's test client
• Fixture organization in conftest.py
• Parametrized tests for multiple scenarios

Security

• Dependency scanning in CI
• Security linting with Ruff
• No hardcoded secrets patterns
• Safe file handling examples

Contributing to This Template

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Local Development

# Clone the template repository
git clone https://github.com/your-username/python-project-template.git
cd python-project-template

# Test the template locally
copier copy . test-project

# Make changes and test again
copier copy --force . test-project

Inspiration and Credits

This template is inspired by:

• Python Packaging Authority guidelines
• FastAPI project structure
• Typer best practices
• Rich examples
• Modern Python development workflows

License

This template is licensed under the MIT License. Projects generated from this template can use any license you choose.

Support

• Documentation: Template Documentation
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Happy coding! 🚀✨# eu.42sol.python_template