Python Template Project

A modern Python project template with comprehensive tooling, testing, and development setup.

Features

• 🚀 Modern Python: Python 3.12+ with type hints
• 📦 UV Package Manager: Fast dependency resolution and management
• 🧪 Comprehensive Testing: pytest with coverage reporting
• 🔧 Code Quality: Black, isort, ruff, and mypy
• 📚 Documentation: Ready for MkDocs
• 🔒 Security: Pre-commit hooks and dependency scanning
• 🏗️ Build System: Hatchling for modern Python packaging

Quick Start

Prerequisites

• Python 3.12 or higher
• UV package manager

Installation

1. Clone and setup the project:

   git clone <your-repo-url>
   cd python-template
   python setup.py

2. Install dependencies:

   uv sync --dev

3. Run tests:

   uv run pytest

Development Setup

Environment Configuration

1. Copy the environment template:

   cp env.template .env

2. Edit .env with your configuration values.

Available Commands

• Setup project: python setup.py
• Install dependencies: uv sync --dev
• Run tests: uv run pytest
• Format code: uv run black src/ tests/
• Sort imports: uv run isort src/ tests/
• Lint code: uv run ruff check src/ tests/
• Type check: uv run mypy src/
• Run all checks: uv run pre-commit run --all-files

Testing

• Unit tests: uv run pytest tests/unit/ -v
• Integration tests: uv run pytest tests/integration/ -v
• Coverage report: uv run pytest --cov=src/python_template
• Specific test: uv run pytest tests/unit/test_file.py::test_function -v

Project Structure

python-template/
├── pyproject.toml          # Modern Python configuration
├── README.md              # This file
├── CHANGELOG.md           # Version tracking
├── LICENSE                # MIT License
├── .gitignore             # Git ignore rules
├── env.template           # Environment variables template
├── setup.py               # Quick setup script
├── src/                   # Source code
│   └── python_template/
│       ├── __init__.py
│       ├── main.py
│       └── config.py
├── tests/                 # Test suite
│   ├── unit/
│   ├── integration/
│   └── conftest.py
├── data/                  # Data files
└── scripts/               # Executable scripts

Configuration

The project uses Pydantic for configuration management. Configuration can be provided through:

1. Environment variables (see env.template)
2. Configuration files
3. Default values

Example configuration:

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "Python Template"
    debug: bool = False
    log_level: str = "INFO"
    
    class Config:
        env_file = ".env"

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: uv run pytest
5. Run code quality checks: uv run pre-commit run --all-files
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

Code Quality Standards

• Use type hints for all functions and classes
• Keep methods under 20 lines
• Split files if they exceed 300 lines
• Write comprehensive tests
• Follow SOLID principles
• Use meaningful variable and function names

Development Tools

Pre-commit Hooks

The project includes pre-commit hooks for:

• Code formatting (Black)
• Import sorting (isort)
• Linting (Ruff)
• Type checking (MyPy)
• Security scanning

IDE Configuration

Recommended VS Code extensions:

• Python
• Pylance
• Black Formatter
• Ruff
• MyPy Type Checker

License

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

Changelog

See CHANGELOG.md for a detailed history of changes.

Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Follow the issue template guidelines

Acknowledgments

• UV for fast Python package management
• Pydantic for data validation
• pytest for testing framework
• Black for code formatting
• Ruff for linting