DEV Community

Huy Nguyen
Huy Nguyen

Posted on

🚀 Streamline Your Python & Django Development with Production-Ready Cookiecutter Templates

#python #cookiecutter #bestpractices #devtools

TL;DR: I've created a comprehensive cookiecutter template collection that generates production-ready Python apps, PyPI packages, Django REST APIs, and DRF packages with modern tooling, best practices, and zero configuration hassle.

The Problem: Starting Projects Shouldn't Be This Hard

How many times have you started a new Python project and spent hours setting up the same boilerplate code? Configuring pyproject.toml, setting up pre-commit hooks, writing GitHub Actions, configuring Docker, setting up Django with all the modern best practices...

The list goes on. And then you realize you forgot to configure type checking, or your test coverage setup is broken, or you're missing that one crucial piece of tooling that makes development smooth.

I've been there. We've all been there.

The Solution: One Template to Rule Them All (Actually, Four)

That's why I created cookiecutter-python — a curated collection of four specialized cookiecutter templates that cover the most common Python development scenarios:

🐍 Python App - For General-Purpose Applications

Perfect for CLI tools, data processing scripts, or any standalone Python application.

📦 Python Package - For PyPI Publishing

Ready-to-publish package structure with documentation, CI/CD, and multiple license options.

🌐 Django REST App - For Full-Stack Web APIs

Complete Django REST Framework setup with authentication, database, optional Celery/WebSockets, and cloud deployment support.

🧩 DRF Package - For Reusable Django Components

Lightweight structure for building and distributing Django REST Framework extensions.

What Makes These Templates Special?

✨ Modern Tooling Out of the Box

Each template is carefully configured with specialized tooling for its use case:

🔧 Universal Tools (All Templates):

  • UV for lightning-fast dependency management with intelligent dependency groups
  • Ruff for blazing-fast linting and formatting
  • Black for consistent code formatting
  • Dual type checking with both mypy and pyright for maximum type safety
  • Pre-commit hooks for automated quality checks
  • pytest with parallel execution (pytest-xdist) and coverage reporting
  • GitHub Actions CI/CD pipelines

📦 Package Templates (PyPackage & DRF Package) Add:

  • Commitizen for conventional commits and automated versioning
  • Interrogate for docstring coverage monitoring with badge generation
  • Sphinx ecosystem for professional documentation (myst-parser, ReadTheDocs theme)
  • Automated publishing workflows to PyPI

🌐 Django Templates (DRF & DRF Package) Add:

🏗️ Production-Ready Architecture

The Django templates include:

  • PostgreSQL integration with connection pooling
  • Redis support for Celery and WebSockets
  • JWT authentication with django-rest-auth
  • API documentation with Swagger/ReDoc
  • Docker containerization
  • Cloud storage support (AWS S3, GCP, Azure)
  • Email providers integration (SendGrid, Mailgun, etc.)

🎯 Zero Configuration Philosophy

Each generated project is immediately runnable. No additional setup required. Just generate, install dependencies, and start developing.

Quick Start Guide

Prerequisites

First, you'll need to install cookiecutter. I recommend using Homebrew (macOS) or pipx for a clean installation:

macOS (Recommended):

brew install cookiecutter
Enter fullscreen mode Exit fullscreen mode

Linux/Windows with pipx:

pipx install cookiecutter
Enter fullscreen mode Exit fullscreen mode

Alternative (with pip):

python3 -m pip install --user cookiecutter
Enter fullscreen mode Exit fullscreen mode

Why not just pip install cookiecutter? Since we'll be using UV for Python dependency management in the generated projects, keeping cookiecutter isolated prevents potential conflicts and keeps your global Python environment clean.

Generate Your Project 

cookiecutter gh:huynguyengl99/cookiecutter-python
Enter fullscreen mode Exit fullscreen mode

You'll be prompted to select your template type:

Select a template
1 - Python app (A cookiecutter template for a normal python app)
2 - Python package (A cookiecutter template for a python package)  
3 - DRF (A cookiecutter template for a django rest framework app)
4 - DRF package (A cookiecutter template for a drf package)
Choose from [1/2/3/4] (1):
Enter fullscreen mode Exit fullscreen mode

Start Developing Immediately

For a Django REST App:

cd your-project
uv sync                    # Install dependencies
docker compose up -d       # Start PostgreSQL/Redis
scripts/manage.sh migrate  # Run migrations
scripts/manage.sh runserver # Start development server
Enter fullscreen mode Exit fullscreen mode

Your API documentation is immediately available at:

  • Swagger UI: http://localhost:8000/api/schema/swg/
  • ReDoc: http://localhost:8000/api/schema/redoc/

Deep Dive: What Each Template Provides

🐍 Python App Template

Perfect for: CLI tools, data processing, automation scripts

Includes:

  • Modern pyproject.toml configuration
  • Docker setup for easy deployment
  • Comprehensive testing framework
  • Code quality tools (Ruff, Black, mypy, pyright)
  • GitHub Actions for CI/CD

Generated Structure:

my-app/
├── pyproject.toml
├── docker-compose.yml
├── Dockerfile
├── scripts/
│   └── lint.sh
└── my_app/
    └── __init__.py
Enter fullscreen mode Exit fullscreen mode

📦 Python Package Template

Perfect for: Open-source libraries, reusable components

Includes:

  • PyPI-ready project structure
  • Sphinx documentation with ReadTheDocs integration
  • Multiple license options (MIT, BSD, Apache, GPL)
  • Automated versioning with Commitizen
  • Publishing workflow to PyPI

Generated Structure:

my-package/
├── pyproject.toml
├── LICENSE
├── docs/
├── tests/
├── .github/workflows/
└── my_package/
    └── __init__.py
Enter fullscreen mode Exit fullscreen mode

🌐 Django REST App Template

Perfect for: Web APIs, SaaS backends, microservices

Configuration Options:

  • Database: PostgreSQL with multiple version options
  • Authentication: JWT with optional Google OAuth
  • Background Tasks: Optional Celery integration
  • Real-time: Optional WebSocket support with Channels
  • Cloud Storage: AWS S3, Google Cloud, Azure support
  • Email: 10+ provider integrations (SendGrid, Mailgun, etc.)
  • API Style: Optional camelCase conversion

Generated Structure:

my-api/
├── pyproject.toml
├── docker-compose.yml
├── Dockerfile
├── scripts/
│   └── manage.sh
└── my_api/
    ├── config/
    │   ├── settings/
    │   ├── urls.py
    │   └── wsgi.py
    ├── accounts/        # Custom user model
    ├── core/           # Utilities
    └── status/         # Health check
Enter fullscreen mode Exit fullscreen mode

Key Features:

  • Custom User Model with email authentication
  • JWT Authentication with refresh token rotation
  • API Versioning ready structure
  • Comprehensive Testing with factories and fixtures
  • Admin Interface customization
  • Structured Logging with structured logs
  • Health Checks and monitoring endpoints

🧩 DRF Package Template

Perfect for: Django REST Framework extensions, reusable API components

Includes:

  • Sandbox Django project for testing
  • Documentation with Django integration
  • Package publishing to PyPI
  • Testing across multiple Django/DRF versions

Unique Feature: The sandbox directory serves dual purposes:

  1. Testing Environment: Run tests against your package
  2. Development Playground: Manual testing with a real Django app

Advanced Features That Set These Apart

🔧 Intelligent Dependency Management with UV

Each template uses UV's dependency groups for optimal development experience:

[dependency-groups]
dev = ["commitizen", "factory-boy", "pytest-django"]  # Core development
lint = ["black", "ruff", "mypy", "pyright"]           # Code quality  
test = ["pytest-cov", "pytest-xdist", "coverage"]    # Testing tools
docs = ["sphinx", "myst-parser", "interrogate"]      # Documentation
Enter fullscreen mode Exit fullscreen mode

Smart defaults with uv sync:

  • Application templates: Auto-installs dev + lint groups
  • Package templates: Auto-installs all groups for comprehensive development
  • Selective installation: uv sync --group test for specific workflows

🛡️ Type Safety First

Every template includes comprehensive type checking with dual tools for maximum coverage:

  • mypy with specialized Django and DRF plugins for framework-specific type checking
  • pyright for advanced static analysis and fast feedback
  • django-stubs for comprehensive Django typing (Django templates)

This dual approach catches different categories of type issues and provides the most robust type safety available in the Python ecosystem.

📊 Quality Metrics & Automation

Package templates include sophisticated quality monitoring:

# Docstring coverage with automatic badge generation
interrogate --generate-badge docs/_static/ my_package

# Conventional commits with automated versioning
cz commit  # Interactive commit creation
cz bump    # Automatic version bumping and changelog

# Parallel testing for faster feedback
pytest -n5  # Runs tests across 5 parallel processes
Enter fullscreen mode Exit fullscreen mode

Quality gates enforce standards:

  • 80% docstring coverage requirement
  • 100% type hint coverage with mypy strict mode
  • Zero linting violations with Ruff and Black
  • Conventional commit format for automated changelog generation

⚡ Modern Python Practices

  • PEP 621 compliant pyproject.toml
  • UV for dependency management (10x faster than pip)
  • Ruff for linting (100x faster than flake8)
  • Python 3.10+ with modern syntax support

🚀 Production Deployment Ready

Django templates include:

  • Multi-stage Docker builds for optimized images
  • Gunicorn configuration for production WSGI
  • Environment-based settings (dev/test/production)
  • Static file handling with WhiteNoise
  • Database connection pooling

Real-World Usage Examples

Scenario 1: Building a SaaS API 

cookiecutter gh:huynguyengl99/cookiecutter-python
# Select: 3 - DRF
# Configure: PostgreSQL, JWT auth, Celery, SendGrid emails, AWS S3

cd my-saas-api
uv sync
docker compose up -d
scripts/manage.sh migrate
scripts/manage.sh createsuperuser
scripts/manage.sh runserver
Enter fullscreen mode Exit fullscreen mode

Result: Full-featured API with user authentication, background tasks, email integration, and cloud storage. Ready for production deployment.

Scenario 2: Publishing a Python Library 

cookiecutter gh:huynguyengl99/cookiecutter-python
# Select: 2 - Python package
# Configure: MIT license, GitHub username, PyPI publishing

cd my-library
uv sync
pytest  # Tests pass immediately
scripts/lint.sh  # Code quality checks pass
cz commit  # Conventional commits
Enter fullscreen mode Exit fullscreen mode

Result: Professional package structure ready for PyPI publishing with documentation, CI/CD, and automated releases.

Scenario 3: Building a DRF Extension 

cookiecutter gh:huynguyengl99/cookiecutter-python
# Select: 4 - DRF package

cd my-drf-extension
uv sync
docker compose up -d  # Test database
pytest sandbox  # Test against real Django app
python sandbox/manage.py runserver  # Manual testing
Enter fullscreen mode Exit fullscreen mode

Result: Professional DRF package with testing sandbox and publishing workflow.

Best Practices Baked In

🧪 Testing Excellence

Each template includes sophisticated testing infrastructure:

🏃‍♂️ Performance-Optimized Testing:

  • Parallel execution with pytest-xdist (5 parallel processes by default)
  • Smart test discovery with proper Django integration
  • Coverage reporting with branch coverage and XML output for CI integration

🏭 Test Data Generation (Django Templates):

# Factory Boy integration for realistic test data
from accounts.factories import UserFactory

def test_user_creation():
    user = UserFactory.create(email="test@example.com")
    assert user.is_active
Enter fullscreen mode Exit fullscreen mode

⏰ Time-Based Testing:

# Freezegun for testing time-dependent code
from freezegun import freeze_time

@freeze_time("2023-01-01")
def test_timestamp_behavior():
    # Test behavior at specific time
    pass
Enter fullscreen mode Exit fullscreen mode

🔧 Advanced Testing Features:

  • pytest-mock for sophisticated mocking
  • pytest-django for Django-specific fixtures and database handling
  • Factory Boy with custom factory metaclass for type-safe model factories
  • Coverage exclusions for migrations, settings, and other non-testable code

📝 Documentation Standards

Package templates include professional documentation tooling:

📖 Sphinx Documentation:

  • Automatic API documentation generation
  • ReadTheDocs integration with automated builds
  • MyST parser for Markdown support in reStructuredText projects
  • Cross-references and intersphinx linking

📊 Documentation Quality Monitoring:

  • Interrogate for docstring coverage monitoring
  • Automatic badge generation showing documentation coverage percentage
  • 80% coverage requirement enforced in CI/CD
  • SVG badges integrated into documentation and README 
# Check docstring coverage
interrogate -vv my_package

# Generate coverage badge
interrogate --generate-badge docs/_static/
Enter fullscreen mode Exit fullscreen mode

📋 API Documentation (Django Templates):

  • Swagger UI and ReDoc auto-generation from code
  • OpenAPI 3.0 specification export
  • Interactive API testing directly in documentation

🔄 CI/CD Pipeline

GitHub Actions workflows include:

🧪 Comprehensive Testing:

  • Multi-version testing across Python 3.10-3.13
  • Parallel test execution with pytest-xdist for faster feedback
  • Coverage reporting with Codecov integration and XML output
  • Matrix testing across multiple dependency versions (Django templates)

✅ Code Quality Gates:

  • Linting pipeline with Ruff for import sorting and style checks
  • Dual type checking with both mypy and pyright
  • Code formatting verification with Black
  • TOML file validation and sorting with toml-sort

📦 Automated Publishing (Package Templates):

  • Semantic versioning with Commitizen integration
  • Automated PyPI publishing on tagged releases
  • GitHub releases with automated changelog generation
  • Build artifact caching for faster CI runs

🔒 Security & Quality:

  • Dependency vulnerability scanning
  • Pre-commit hook validation in CI
  • Build reproducibility with UV lock files

🎨 Code Quality

Pre-commit hooks automatically run:

  • Ruff for linting and import sorting
  • Black for code formatting
  • toml-sort for TOML file organization
  • Type checking with mypy/pyright

Common Questions

Q: Why four separate templates instead of one configurable template?

A: Each template is optimized for its specific use case. A Python package has different needs than a Django API. Separate templates mean:

  • Cleaner code without excessive conditionals
  • Faster generation with only relevant files
  • Better maintenance with focused concerns
  • Easier customization for specific needs

Q: Why UV instead of pip/poetry?

A: UV is incredibly fast (10-100x faster than pip) and handles both Python version management and dependency resolution. It's the future of Python package management.

Q: Can I customize the generated templates?

A: Absolutely! The templates are designed to be starting points. All configuration is in standard files (pyproject.toml, settings.py, etc.) that you can modify as needed.

Q: What about database migrations in Django templates?

A: The Django templates include a custom user model and initial migrations. After generation, run scripts/manage.sh migrate and you're ready to go.

Future Roadmap

I'm continuously improving these templates based on community feedback:

  • FastAPI template for modern async APIs
  • Next.js + Django full-stack template
  • Kubernetes deployment configurations
  • More cloud provider integrations
  • Additional authentication providers

Getting Started Today

Ready to streamline your Python development? Here's how to get started:

  1. Install cookiecutter: pip install cookiecutter
  2. Generate your project: cookiecutter gh:huynguyengl99/cookiecutter-python
  3. Choose your template and configure options
  4. Start developing immediately!

Useful Links

  • 📂 Repository: github.com/huynguyengl99/cookiecutter-python
  • 📖 Documentation: Full README with detailed setup instructions
  • 🐛 Issues: Report bugs or request features
  • 💡 Discussions: Share your use cases and get help

Conclusion

These cookiecutter templates represent hundreds of hours of research, testing, and refinement to create the ideal starting point for Python projects. Whether you're building a simple CLI tool or a complex Django API, you can focus on your core business logic instead of wrestling with configuration.

The templates embody modern Python best practices:

  • Type safety with comprehensive type checking
  • Code quality with automated formatting and linting
  • Testing excellence with comprehensive test setups
  • Production readiness with Docker and deployment configs
  • Developer experience with helpful scripts and documentation

Give them a try for your next project. I'm confident they'll save you hours of setup time and help you ship better code faster.

What are you waiting for? Let's build something amazing together! 🚀

Have you used these templates? Found them helpful? Have suggestions for improvements? I'd love to hear about your experience! Drop a comment below or open an issue on GitHub.

Top comments (0)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.