Skip to content

README.md

Latest commit

 

History

History
250 lines (184 loc) · 7.45 KB

README.md

File metadata and controls

250 lines (184 loc) · 7.45 KB

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

🔄 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 "john.doe@example.com" "jane@example.com"
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:

License

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

Support

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