Skip to content

README.md

Latest commit

 

History

History
131 lines (99 loc) · 3.5 KB

README.md

File metadata and controls

131 lines (99 loc) · 3.5 KB

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:

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.