PythonPackageCookiecutter

A cookiecutter template for modern Python libraries with:

• uv for environment and dependency management
• PEP 621 metadata in pyproject.toml
• src/ package layout
• Ruff, Pytest, pre-commit, and GitHub Actions
• starter docs for both maintainers and new contributors

Quick Start

Install the two tools you need:

uv tool install cookiecutter

Generate a new project:

cookiecutter https://github.com/HenriquesLab/PythonPackageCookiecutter

Enter the generated project and bootstrap it with uv:

cd your-project-name
uv sync
uv run pre-commit install
uv run pytest

What The Template Generates

Each generated project includes:

• pyproject.toml configured for modern packaging and uv
• .python-version for a pinned local interpreter target
• README.md with a project overview and key commands
• GETTING_STARTED.md with a minimal setup guide and command explanations
• CONTRIBUTING.md with a contributor workflow
• makefile with common uv-powered shortcuts
• ruff.toml and .pre-commit-config.yaml for code quality
• a simple GitHub Actions workflow
• src/ and tests/ starter structure

Generated Layout

your-project/
├── .github/workflows/ci.yml
├── .python-version
├── .editorconfig
├── .pre-commit-config.yaml
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── GETTING_STARTED.md
├── LICENSE.txt
├── makefile
├── pyproject.toml
├── README.md
├── ruff.toml
├── src/
│   └── your_package/
│       ├── __init__.py
│       └── your_module.py
└── tests/
    └── test_your_class.py

Template Prompts

When you run Cookiecutter, you will be prompted for:

• author_name: maintainer name for package metadata
• author_email: maintainer contact email
• directory_name: repository and top-level folder name
• file_name: starter module filename inside the package
• package_name: import/package name
• class_name: example class used by the starter code and test
• description: short project description
• repository_url: canonical repository URL used in package metadata
• minimum_python_version: minimum supported Python version
• license: SPDX license expression used in package metadata and LICENSE.txt

The pre-generation hook validates package_name so it stays compatible with common Python packaging conventions.

Development Workflow In Generated Projects

The template is designed around uv:

uv sync
uv run pytest
uv run ruff check .
uv run ruff format .
uv run python -m build

If you prefer short aliases, the generated makefile wraps the same commands:

make sync
make test
make lint
make format
make build

Documentation

Repo-level documentation:

• README.md
• docs/template-guide.md

Generated-project documentation:

• README.md for the project overview
• GETTING_STARTED.md for first-time setup
• CONTRIBUTING.md for the contributor workflow

Maintaining This Template

To update the template, edit files under {{cookiecutter.directory_name}}/ and keep the repository docs aligned with the generated docs. The licenses/ directory is only a temporary template asset and is removed automatically by the post-generation hook.

License

This repository contains the template itself. Generated projects can choose one of the bundled license options, and the matching LICENSE.txt will be included automatically.