Skip to content

Cookiecutter Python Package

A modern cookiecutter template for Python packages with best practices built-in.

CI Documentation Python versions License: MIT

Get Started in 30 Seconds

pip install cookiecutter
cookiecutter https://github.com/s-celles/cookiecutter-python-package.git

Development Status

This project is currently in active development.

AI-Generated Content Notice

A significant portion of this project's content (including code, documentation, and examples) has been generated using AI assistance. Please review all code and documentation carefully before use in production environments. We recommend thorough testing and validation of any AI-generated components.

What You Get

This template creates a Python package with modern best practices and industry-standard tools:

📦 Modern Package Structure

  • Source layout (src/ directory) for cleaner organization
  • PEP 621 compliant pyproject.toml configuration
  • Build backend selection (setuptools, hatchling, flit, or pdm)
  • Type hints and py.typed marker for better IDE support
  • Entry points for CLI applications

🧪 Quality Assurance

  • pytest for modern testing with fixtures and parametrization
  • Coverage reporting with HTML/XML output
  • Ruff for ultra-fast linting and formatting
  • MyPy for static type checking
  • Bandit for security vulnerability scanning

🔧 Development Tools

  • uv for ultra-fast package management (optional)
  • pre-commit hooks for automated quality checks
  • GitHub Actions for CI/CD automation
  • Dependabot for dependency updates

🛠️ CLI Support

Choose your preferred CLI framework: - Typer (modern, type-based) - Click (decorator-based) - Argparse (standard library)

⚙️ Template Options Overview

Customize your generated project by choosing from these options:

  • Build Backend: setuptools, hatchling, flit, or pdm
  • Code Quality: Ruff, MyPy, Bandit, Safety
  • Testing: pytest, coverage reporting
  • Documentation: MkDocs or Sphinx
  • CLI Framework: Typer, Click, Argparse, or none
  • Package Management: uv or pip
  • Automation: pre-commit, GitHub Actions, Dependabot

See Template Configuration for detailed explanations of all options.

📚 Documentation Ready

  • MkDocs or Sphinx support
  • README templates with badges
  • CHANGELOG following Keep a Changelog format
  • Contributing guidelines

Quick Examples

Perfect for simple libraries: 

cookiecutter https://github.com/s-celles/cookiecutter-python-package.git
# Choose 'n' for most optional tools

Complete setup with all quality tools: 

cookiecutter https://github.com/s-celles/cookiecutter-python-package.git
# Choose 'y' for recommended tools

Command-line application with Typer: 

cookiecutter https://github.com/s-celles/cookiecutter-python-package.git
# Select 'typer' for command_line_interface

Why This Template?

Modern Best Practices

  • PEP 621 compliant packaging
  • Source layout for cleaner imports
  • Type hints throughout
  • Security scanning built-in

Developer Experience

  • Fast setup with sensible defaults
  • Comprehensive tooling options
  • Automated quality checks
  • CI/CD ready workflows

Flexibility

  • All tools optional - choose what you need
  • Multiple CLI frameworks supported
  • Documentation options (MkDocs/Sphinx)
  • Container support with Docker

Next Steps

  1. Quick Start - Create your first package in minutes
  2. Configuration - Understand all available options
  3. Tools Guide - Learn about included tools
  4. Examples - See real-world usage patterns

Community

Built with ❤️ for the Python community