Cookiecutter Python Template

This folder contains a complete, production-ready cookiecutter template for starting new Python projects.

📦 What's Inside

• Production-ready cookiecutter template with 50+ configuration options
• Complete project structure with modern Python best practices
• CI/CD workflows for GitHub Actions with multi-version testing
• Security scanning and compliance tools (OWASP Top 10 compliant)
• Docker containerization with production-ready configurations
• Performance testing with Locust and k6
• Background job processing with ARQ or Celery
• Redis caching and health check endpoints
• Sentry monitoring integration

📁 Folder Structure

cookiecutter-python-template/
├── cookiecutter.json              # Main configuration (40+ options)
├── hooks/
│   ├── pre_gen_project.py        # Pre-generation validation
│   └── post_gen_project.py       # Post-generation cleanup
├── {{cookiecutter.project_slug}}/  # Main template (60+ files)
│   ├── .github/
│   │   └── workflows/            # 8 CI/CD workflows (CI, codecov, release, security, docs, etc.)
│   ├── src/{{cookiecutter.project_slug}}/
│   │   ├── __init__.py
│   │   ├── cli.py                # Optional CLI
│   │   ├── api/                  # API endpoints (optional)
│   │   │   └── health.py         # Health check endpoints
│   │   ├── core/                 # Core functionality
│   │   │   ├── cache.py          # Redis caching (optional)
│   │   │   └── sentry.py         # Sentry monitoring (optional)
│   │   ├── jobs/                 # Background jobs (optional)
│   │   │   └── worker.py         # ARQ/Celery workers
│   │   ├── middleware/           # API middleware (optional)
│   │   │   └── security.py       # OWASP security middleware
│   │   └── utils/                # Utility modules
│   ├── tests/
│   │   ├── conftest.py
│   │   ├── unit/                 # Unit tests
│   │   ├── integration/          # Integration tests
│   │   ├── load/                 # Load tests (optional)
│   │   │   ├── locustfile.py     # Locust configuration
│   │   │   ├── k6-script.js      # k6 configuration
│   │   │   └── README.md         # Load testing guide
│   │   └── test_example.py
│   ├── docs/
│   │   ├── ADRs/                 # Architecture Decision Records
│   │   ├── planning/             # Project planning templates
│   │   └── PYTHON_COMPATIBILITY.md  # Python version compatibility guide
│   ├── pyproject.toml            # UV/PEP 621 configuration
│   ├── Dockerfile                # Production-ready container (optional)
│   ├── docker-compose.yml        # Development environment (optional)
│   ├── docker-compose.prod.yml   # Production environment (optional)
│   ├── .dockerignore             # Docker ignore patterns
│   ├── .pre-commit-config.yaml   # Pre-commit hooks
│   ├── codecov.yml               # Code coverage config
│   ├── renovate.json             # Dependency updates
│   ├── mkdocs.yml                # Documentation site
│   ├── README.md
│   ├── LICENSE
│   ├── SECURITY.md
│   ├── CONTRIBUTING.md
│   └── ... (40+ more files)
├── {{ cookiecutter.repo_name }}/  # Optional monitoring utilities
│   ├── src/monitoring/           # Monitoring components
│   │   ├── ab_testing_dashboard.py
│   │   ├── metrics_collector.py
│   │   ├── performance_dashboard.py
│   │   └── service_token_monitor.py
│   └── tests/unit/monitoring/    # Monitoring tests
├── .github/
│   ├── workflows/
│   │   ├── validate-template.yml # Template validation
│   │   └── release-drafter.yml   # Auto release notes
│   └── release-drafter.yml       # Release config
├── .pre-commit-config.yaml       # Template repo hooks
└── QUICK_START.sh                # Interactive setup script

🚀 How to Use This Template

Option 1: Copy to GitHub Repository

1. Create a new repository on GitHub:

   • Repository name: cookiecutter-python-template-2 (or your choice)
   • Description: "Production-ready Python cookiecutter template"
   • Public repository
   • DO NOT initialize with README

2. Copy this folder to the new repository:

   # From your local machine
   cd /path/to/this/folder/cookiecutter-template
   git init
   git add .
   git commit -m "Initial commit: Production-ready Python cookiecutter template"
   git branch -M main
   git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git
   git push -u origin main

3. Enable as template repository:

   • Go to repository Settings → General
   • Check ✅ "Template repository"

Option 2: Use Locally

# Install cookiecutter
pip install cookiecutter

# Use the template directly from this folder
cookiecutter /path/to/this/folder/cookiecutter-template

# Or after copying to your templates directory
cp -r cookiecutter-template ~/my-templates/
cookiecutter ~/my-templates/cookiecutter-template

🎯 Key Features

Production-Ready Infrastructure

Monitoring and Observability:

• include_sentry: Sentry error tracking and APM
• include_health_checks: Kubernetes-ready health endpoints (liveness, readiness, startup)

Containerization:

• include_docker: Multi-stage Dockerfile with security hardening
• Docker Compose for development and production
• Non-root user, health checks, optimized caching

Performance and Scalability:

• include_background_jobs: ARQ (async) or Celery task queues
• include_caching: Redis caching with decorator patterns
• include_load_testing: Locust and k6 load testing tools

Security:

• API security middleware (OWASP headers, rate limiting, SSRF prevention)
• SBOM generation in release workflow (CycloneDX format)
• 7+ security scanning tools integrated

Enhanced Configuration Options (50+ total)

MCP Server Support (from zen-mcp-server):

• include_mcp_server: Add MCP protocol support
• mcp_transport: stdio/http/sse options

API Integration (from xero-practice-management):

• include_api_client: API client factory pattern
• api_auth_type: OAuth2/API key/JWT authentication
• include_retry_logic: Exponential backoff retry
• include_rate_limiting: Rate limiting support

Database/Ledger Patterns (from ledgerbase):

• include_database: SQLAlchemy with migrations
• include_repository_pattern: Repository pattern
• include_unit_of_work: Unit of Work pattern
• database_dialect: PostgreSQL/MySQL/SQLite

Enhanced Security (from pp-security-master):

• include_gitleaks: Secrets detection
• include_compliance_docs: Compliance templates
• include_threat_model: Threat modeling
• include_fuzzing: Fuzzing infrastructure

Financial Patterns (from FISProject):

• include_financial_validators: Financial validation
• include_audit_logging: Audit trail
• use_decimal_precision: Decimal for money

Community Health & Compliance Scaffolding (cluster C):

• include_editorconfig: 4-space Python .editorconfig with YAML/JSON/TOML overrides
• community_health_style: full Contributor Covenant 2.1 + GOVERNANCE.md, or org_pointer short pointer files that reference the org .github repo
• sole_contributor: solo-maintainer mode for branch protection (required_approving_review_count = 0 and require_code_owner_reviews = false)
• auto_setup_branch_protection: opt-in auto-run of setup_github_protection.py during generation (requires GITHUB_TOKEN and a configured origin remote; fails non-fatally with an actionable hint if either is missing)

Template Files ({{cookiecutter.project_slug}}/)

Complete project structure with:

Core Infrastructure:

• ✅ 8 GitHub Actions workflows (CI, codecov, security, docs, release, PyPI, fuzzing)
• ✅ UV + PEP 621 packaging (10-100x faster than pip/poetry)
• ✅ Hatchling build backend
• ✅ Cruft template update tracking
• ✅ Python 3.10-3.14 support with multi-version CI testing

Code Quality:

• ✅ Ruff consolidated linting
• ✅ BasedPyright strict type checking
• ✅ pytest with 80% coverage target
• ✅ SonarCloud continuous code quality and security analysis (optional)
• ✅ Pre-commit hooks (9+ automated checks)
• ✅ Mutation testing with mutmut

Documentation:

• ✅ MkDocs Material documentation site
• ✅ Python compatibility guide (version-specific features)
• ✅ Architecture Decision Records (ADRs)

Security (OWASP Top 10 Compliant):

• ✅ 7+ security tools (Bandit, Safety, OSV-Scanner, CodeQL, Gitleaks, etc.)
• ✅ SBOM generation (CycloneDX format)
• ✅ API security middleware (headers, rate limiting, SSRF prevention)
• ✅ Secrets scanning with Gitleaks

Production Features (Optional):

• ✅ Docker containerization (multi-stage, security-hardened)
• ✅ Kubernetes health checks (liveness, readiness, startup)
• ✅ Sentry monitoring (error tracking, APM, profiling)
• ✅ Background jobs (ARQ or Celery)
• ✅ Redis caching (decorator-based)
• ✅ Load testing (Locust and k6)

Optional Frameworks:

• ✅ Click CLI (optional)
• ✅ FastAPI with security middleware (optional)
• ✅ PyTorch ML (optional)
• ✅ SQLAlchemy with migrations (optional)

📊 Template Coverage

Expected User Impact:

• 100% of users: Enhanced security
• 40-50% of users: API integration patterns
• 40-50% of users: Database/ORM patterns
• 10-15% of users: Financial/ledger patterns
• 5-10% of users: MCP server patterns

Time Savings: 4-8 hours per project (120-240× ROI)

📝 Example Usage

# Install cookiecutter and cruft
pip install cookiecutter cruft

# Option 1: Use with Cruft (recommended - enables template updates)
cruft create /path/to/cookiecutter-template

# Option 2: Use with Cookiecutter (traditional method)
cookiecutter /path/to/cookiecutter-template

# Answer prompts:
project_name [My Python Project]: My Awesome Project
python_version [3.12]: 3.12
license [MIT]: MIT
include_cli [yes]: yes
include_api_client [no]: yes
api_auth_type [oauth2]: oauth2
include_database [sqlalchemy_migrations]: sqlalchemy_migrations
include_repository_pattern [yes]: yes

# Generated project structure:
my_awesome_project/
├── .github/workflows/      # 4 CI/CD workflows
├── src/my_awesome_project/
│   ├── cli.py
│   ├── core/
│   └── utils/
├── tests/
├── docs/
├── pyproject.toml
├── uv.lock               # UV lock file
├── .cruft.json          # Template tracking (cruft only)
└── README.md

🔍 SonarCloud Setup (Optional)

Generated projects support SonarCloud for continuous code quality and security analysis. This template repository does not run SonarCloud analysis: the Jinja2 template body is not statically analyzable as plain Python, and analysis was failing with a curl 403 from the quality-gate API. Generated child projects opt into their own SonarCloud analysis via the rendered config that ships inside the template output directory.

For Generated Projects

When creating a new project with include_sonarcloud=yes, you need to:

1. Create SonarCloud Project:

   • Go to SonarCloud
   • Click "+" → "Analyze new project"
   • Select your GitHub repository
   • Choose your organization (e.g., williaby)
   • Project key will be: {github_org}_{project_slug}

2. Configure GitHub Secret:

   • If using organization-level token (recommended):
     • Already configured as SONAR_TOKEN in organization secrets
     • No additional action needed
   • If using repository-level token:
     • Go to repository Settings → Secrets and variables → Actions
     • Add secret: SONAR_TOKEN with your SonarCloud token

3. Verify Configuration:

   # After project generation
   cd your-project
   
   # Check workflow exists
   ls .github/workflows/sonarcloud.yml
   
   # Check configuration
   cat sonar-project.properties

4. First Analysis:

   • Push code to GitHub (main branch or PR)
   • SonarCloud workflow runs automatically
   • View results in SonarCloud Dashboard

SonarCloud Features

Generated projects include:

• Quality Gate Enforcement: Fails if code doesn't meet quality standards
• PR Decoration: Shows issues directly in pull requests
• Coverage Tracking: Integrates pytest coverage reports
• Security Analysis: Detects vulnerabilities and security hotspots
• Code Smells: Identifies maintainability issues
• Technical Debt: Quantifies effort to fix issues

Analysis Method

Generated projects use CI-Based Analysis (not Automatic):

• ✅ Full Python language support
• ✅ Test coverage integration
• ✅ Quality gate enforcement
• ✅ Branch analysis and PR decoration
• ✅ Comprehensive metrics (security, maintainability, reliability)

🤖 Claude Code Integration

This template includes enhanced support for Claude Code with user-level settings integration.

User-Level Settings Setup

During project generation, you'll be prompted to set up user-level Claude Code settings. These settings enhance Claude Code's capabilities across all your projects:

What's Included:

• Global CLAUDE.md: Best practices, workflows, and development patterns
• Skills: Reusable capabilities for common tasks
• Agents: Specialized task handlers for security, testing, documentation, etc.
• Custom Commands: Slash commands and hooks for enhanced workflows

Setup Process:

When you create a new project using this template, the post-generation hook will:

1. Check for existing user-level settings at ~/.claude/ or ~/.config/claude/
2. Prompt you to set up settings if not found
3. Clone the settings repo (default: https://github.com/ByronWilliamsCPA/.claude)
4. Verify installation of CLAUDE.md, skills, agents, and commands

Manual Setup:

If you skip the automatic setup, you can install user-level settings later:

# Using the default settings repo
git clone https://github.com/ByronWilliamsCPA/.claude ~/.claude

# Or using your own settings repo
git clone https://github.com/YOUR_USERNAME/YOUR_CLAUDE_SETTINGS ~/.claude

Benefits:

✅ Consistent workflows across all projects ✅ Supervisor patterns with agent delegation ✅ Reusable skills for common tasks ✅ Custom slash commands for your workflow ✅ Global best practices inherited by all projects

Note: User-level settings are optional but recommended for the best Claude Code experience. Projects work without them but have enhanced capabilities when available.

🔄 Template Updates with Cruft

This template fully supports Cruft for keeping generated projects in sync with template updates.

✅ Status: Cruft integration is working and tested

• Projects created with cruft create include .cruft.json tracking file
• cruft check verifies template is up to date
• cruft update applies template changes to existing projects
• cruft diff shows pending template changes

Why Use Cruft?

• Stay Updated: Automatically pull in template improvements, bug fixes, and new features
• Selective Updates: Review and accept/reject changes before applying them
• Track Template Version: .cruft.json tracks which template version your project uses
• Conflict Resolution: Smart merging handles conflicts between template updates and your changes

Using Cruft with This Template

Create a new project with Cruft:

# Install cruft
pip install cruft

# Create project (automatically adds .cruft.json)
cruft create https://github.com/YOUR_USERNAME/YOUR_TEMPLATE_REPO

# Or use local path
cruft create /path/to/cookiecutter-python-template

Check for template updates:

cd your-project
cruft check

Update your project:

cruft update
# Review changes, accept/reject updates

View differences:

cruft diff

Update template variables:

cruft update --variables

Automated Update Checks

You can add a GitHub Action to automatically check for template updates:

# .github/workflows/cruft-update.yml
name: Check Template Updates

on:
  schedule:
    - cron: '0 0 * * 1'  # Weekly on Monday
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check for template updates
        run: |
          pip install cruft
          cruft check

Downstream Project Tracking

This template includes a system to track projects created from it and notify them when updates are available.

How it works:

1. Registry: Projects are registered in downstream-projects.json
2. Notifications: When a new template release is published, registered projects receive GitHub issues with update instructions
3. Opt-out: Projects can opt out by setting "notify": false in the registry

Registering your project:

Note: downstream-projects.json and the associated notification workflow are planned but not yet implemented. The section below describes the intended interface.

If you've created a project using this template and want to receive update notifications, add your project to downstream-projects.json:

{
  "repository": "your-org/your-project",
  "description": "Brief description of your project",
  "created_from_commit": "abc123...",
  "notify": true,
  "notification_method": "issue"
}

Important: Fix your .cruft.json

If you created your project locally, your .cruft.json may contain a local path instead of the GitHub URL. Update it to:

{
  "template": "https://github.com/ByronWilliamsCPA/cookiecutter-python-template",
  "checkout": "main"
}

This ensures cruft check and cruft update work correctly.

For template maintainers:

• Notifications are triggered automatically on new releases
• Manual trigger available via GitHub Actions workflow dispatch
• Dry run mode available for testing

🔄 Version History

• v2.1 (2025-11-18): Production-Ready Enhancement Release
  • NEW: Python 3.10-3.14 cross-version support with multi-version CI testing
  • NEW: Docker containerization (multi-stage, security-hardened, optional)
  • NEW: Kubernetes health check endpoints (liveness, readiness, startup)
  • NEW: Sentry monitoring integration (error tracking, APM, profiling)
  • NEW: Background job processing (ARQ and Celery options)
  • NEW: Redis caching with decorator patterns
  • NEW: Load testing tools (Locust and k6)
  • NEW: API security middleware (OWASP headers, rate limiting, SSRF prevention)
  • NEW: SBOM generation in release workflow (CycloneDX format)
  • NEW: Codecov multi-version coverage tracking
  • IMPROVED: Post-generation hook removes unwanted optional files
  • IMPROVED: Success message shows included features and setup steps
  • OWASP Top 10 compliant security configuration
  • 50+ configuration options (up from 40+)
  • 60+ template files (up from 46)
• v2.0 (2025-11-17): UV & Cruft Migration Release
  • BREAKING: Migrated from Poetry to UV for package management
  • Added Cruft support for template updates
  • Updated all dependencies to use standard PEP 621 format
  • Changed build backend from poetry-core to hatchling
  • Updated all documentation and CI/CD workflows for UV
  • Added .cruft.json for template tracking
  • 10-100x faster dependency resolution with UV
• v1.2 (2025-11-17): Claude Code Enhancement Release
  • Added interactive user-level Claude settings setup
  • Streamlined dependency management (Poetry as single source of truth)
  • Simplified CLI help text for better UX
  • Enhanced post-generation hook with Claude Code integration
• v1.1 (2025-11-17): Streamlined release
  • Removed reference documentation (docs-reference/)
  • Added optional monitoring utilities
  • Focused on core template functionality
• v1.0 (2025-11-17): Initial release with patterns from 5 repositories
  • 73 files, 40+ configuration options
  • Complete Python project template

📖 Documentation

• QUICK_START.sh: Interactive script for template setup
• cookiecutter.json: All configuration options with detailed comments
• Template README: Each generated project includes comprehensive documentation

🙏 Based On

This template was created from patterns found in:

1. image-preprocessing-detector: Base project structure
2. zen-mcp-server: MCP protocol patterns
3. xero-practice-management: API integration patterns
4. pp-security-master: Security enhancements
5. FISProject: Financial system patterns
6. ledgerbase: Database/ledger patterns

📞 Support

For questions or issues:

• Review the generated project's documentation (in each project's docs/ folder)
• Check the cookiecutter.json file for all available configuration options
• Use QUICK_START.sh for interactive template setup

🎁 Optional Components

Monitoring Utilities ({{ cookiecutter.repo_name }}/)

Optional monitoring components available for advanced use cases:

• A/B Testing Dashboard: Track and visualize A/B test results
• Metrics Collector: Collect and aggregate system metrics
• Performance Dashboard: Monitor application performance
• Service Token Monitor: Track service token usage and rotation

These components are not included in generated projects by default but can be copied manually for specific use cases.

---

Configuration Options: 50+ options Template Files: 60+ files in main template Python Versions: 3.10-3.14 (full multi-version CI support) GitHub Workflows: 8 automated workflows Security Tools: 7+ integrated scanners (OWASP compliant) Production Features: Docker, Sentry, health checks, caching, background jobs, load testing Coverage: Production-ready for 95%+ of Python project needs Last Updated: 2025-11-18