Python template with some awesome tools to quickstart any Python project

🚀 Enterprise Python Project Template - AI-enhanced development template with TDD workflows, quality standards, and zero-config tooling.

⚡ Quick Start

Using This Template

# 1. Clone the template
git clone https://github.com/nullhack/python-project-template
cd python-project-template

# 2. Install UV package manager (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. **IMPORTANT**: Customize the template for your project
python setup_project.py
# This interactive script will:
# - Rename directories from 'app' to your package name
# - Update pyproject.toml with your project details  
# - Fix Docker configuration paths
# - Replace all template placeholders

# 4. Follow the Git configuration commands shown by setup_project.py
# Example: git remote set-url origin https://github.com/yourname/yourproject

# 5. Setup development environment  
uv venv && uv pip install -e '.[dev]'

# 6. Validate everything works
task test && task lint && task static-check

# 7. Initialize AI development environment (optional)
opencode && /init

⚠️ Template State Notice: This project is currently in "template state" with placeholder values. The setup_project.py script must be run to properly configure Docker, package paths, and project metadata before development.

Requirements: Python 3.13+ and UV package manager are required.

🎯 What This Template Provides

This template creates a production-ready Python project with:

🔧 Project Setup & Customization

• Automated setup script (setup_project.py) - Interactive customization with your project details
• Smart folder renaming - Automatically renames app/ directory to match your project
• Docker path fixing - Updates Docker configuration to match your project structure
• Git configuration - Provides ready-to-use Git commands for remotes and user setup
• Template processing - Replaces all placeholders in pyproject.toml and configuration files

🤖 AI-Enhanced Development Workflow

• Multi-session continuity - Projects span multiple AI sessions with shared state in TODO.md
• Specialized agents - Built-in agents for architecture, development, QA, and repository management
• Skills system - Modular workflows for TDD, feature definition, prototyping, and releases

🏗️ Enterprise Architecture & Quality

• SOLID principles - Enforced through AI architecture reviews via OpenCode agents
• Object Calisthenics - Clean, behavior-rich code patterns enforced by QA workflows
• 100% test coverage - TDD workflows with acceptance criteria docstrings and property-based testing (Hypothesis)
• Mutation testing - mutmut integration for test quality validation
• Zero-config tooling - UV, taskipy, Ruff, PyTest, Hypothesis, PyRight pre-configured

🤖 AI-Powered Development

This project includes built-in AI agents to accelerate your development.

Multi-Session Development

Complex projects are developed across multiple AI sessions. TODO.md at the root acts as the shared state — any AI agent can pick up exactly where the last session stopped.

# Start any session: read state, orient, continue
@developer /skill session-workflow

# End any session: update TODO.md, commit progress, hand off
@developer /skill session-workflow

Feature Development Workflow

# Define new features with SOLID principles
@developer /skill feature-definition

# Create prototypes and validate concepts  
@developer /skill prototype-script

# Write comprehensive tests first (TDD)
@developer /skill tdd

# Get architecture review before implementing
@architect

# Implement with guided TDD workflow
@developer /skill implementation

# Create releases with smart versioning
@repo-manager /skill git-release

🏗️ Architecture & Standards

• 🎯 SOLID Principles - Single responsibility, dependency inversion, clean interfaces
• 🔧 Object Calisthenics - No primitives, small classes, behavior-rich objects
• 🧪 TDD Testing - Acceptance criteria format with Given/When/Then docstrings, 100% coverage requirement
• 🔬 Property-Based Testing - Hypothesis integration for robust edge case validation
• 🧬 Mutation Testing - mutmut for genetic algorithm-based test quality assurance
• ⚡ Modern Toolchain - UV, taskipy, Ruff, PyTest, Hypothesis, PyRight
• 🚀 Smart Releases - Hybrid major.minor.calver versioning with AI-generated themed names

📋 Development Commands

This project uses taskipy for task automation (configured in pyproject.toml):

# Core development workflow
task run              # Execute version module (demo command)
task test             # Run comprehensive test suite with coverage
task test-fast        # Run fast tests only (skip slow tests)
task test-slow        # Run only slow tests (marked with @pytest.mark.slow)
task lint             # Format and lint code with ruff
task static-check     # Type safety validation with pyright

# Documentation
task doc-serve        # Live pdoc documentation server (localhost:8080)
task doc-build        # Build static pdoc API docs to docs/api/
task doc-publish      # Publish API docs to GitHub Pages

# Quality assurance
task test-report      # Detailed coverage report (included in task test)
task mut              # Mutation testing with mutmut
task mut-clean        # Reset mutation testing cache

🐳 Docker Usage

⚠️ Important: Run python setup_project.py first to configure the template before using Docker.

Docker provides development environment with hot reload and integrated tooling:

# Development environment with hot reload
docker-compose up                     # Main application (ports 8000, 8080, 5678)

# Specialized services (use profiles)
docker-compose --profile test up      # Run complete test suite
docker-compose --profile docs up      # Documentation server (localhost:8080)  
docker-compose --profile quality up   # Code quality checks (lint + typecheck)

# Build standalone image
docker build -t your-project-name .   # Build development image

Current Docker Configuration:

• Main service: Hot reload development with volume mounts
• Test profile: Full test suite execution
• Docs profile: Live documentation server
• Quality profile: Linting and type checking

Note: The Docker configuration currently references template paths and requires setup_project.py to be run for proper functionality.

🔧 Technology Stack

📈 Quality Metrics

• ✅ 100% Test Coverage - pytest-cov with fail-under=100 requirement
• ✅ Static Type Safety - PyRight type checking with full type hints
• ✅ Zero Linting Issues - Ruff automated formatting and Google-style conventions
• ✅ Property-Based Testing - Hypothesis integration for robust validation
• ✅ Mutation Testing - mutmut for genetic algorithm-based test quality validation
• ✅ Acceptance Criteria Format - Given/When/Then docstrings with pytest-html reporting
• ✅ Architecture Compliance - AI-enforced SOLID principles through OpenCode agents

🚀 Deployment Ready

Projects generated from this template include Docker support for development:

# After running setup_project.py in your configured project
docker build -t your-project-name .
docker run -p 8000:8000 your-project-name

# Docker Compose development environment
docker-compose up                     # Development environment with hot reload
docker-compose --profile test up      # Run test suite
docker-compose --profile docs up      # Documentation server
docker-compose --profile quality up   # Code quality checks

# API documentation
task doc-build  # Generates docs/api/index.html
task doc-serve  # http://localhost:8080 (live server)

🤝 Contributing

Help improve this template for the entire Python community:

Template Improvements

# Fork and improve the template
git clone https://github.com/your-username/python-project-template  
cd python-project-template

# Test your changes
python setup_project.py --dry-run --github-username testuser --yes

# Add new skills, agents, or template features
# Submit pull request with improvements

Areas for Contribution

• New Skills - Add specialized workflows (deployment, security, performance)
• Agent Enhancements - Improve existing agents or add new specialized ones
• Template Updates - Better project structures, additional tooling, improved defaults
• Documentation - Usage guides, examples, best practices

📄 License

Distributed under the MIT License. See LICENSE for details.

🙏 Built With

• Python Project Template - Enterprise-grade Python project template
• OpenCode - AI-powered development platform
• UV - Modern Python package manager
• Ruff - Extremely fast Python linter

Author: eol (@nullhack)
Project: python-project-template
Documentation: nullhack.github.io/python-project-template