Skip to content

template-guide.md

Latest commit

 

History

History
76 lines (49 loc) · 2.22 KB

template-guide.md

File metadata and controls

76 lines (49 loc) · 2.22 KB

Template Guide

This repository provides a Cookiecutter template for bootstrapping small to medium Python libraries with a modern local workflow.

Goals

The template is optimized for:

  • fast local setup with uv
  • standard Python packaging metadata in pyproject.toml
  • simple quality checks that are easy to explain to new contributors
  • docs that help a project feel usable immediately after generation

Tooling Choices

uv

Generated projects use uv as the default project manager. In practice that means:

  • uv sync creates and updates the local environment
  • uv run ... executes commands inside the managed environment
  • dependency groups are defined in pyproject.toml

hatchling

The generated package uses hatchling as the build backend. It keeps the packaging configuration compact and works cleanly with uv.

Packaging metadata

The template follows current PyPA guidance by including:

  • SPDX license expressions in project.license
  • license-files metadata
  • standardized project.urls labels such as Homepage, Repository, Issues, and Changelog
  • dependency groups for dev and test workflows

Ruff and Pytest

The code quality stack is intentionally small:

  • Ruff handles linting and formatting
  • Pytest handles testing
  • pre-commit wires the checks into git hooks

Documentation Strategy

The generated project includes two levels of onboarding:

  • README.md: short project overview and the most common commands
  • GETTING_STARTED.md: minimal step-by-step setup guide that explains what each command does

CONTRIBUTING.md then expands that into a maintainer-friendly workflow.

Updating The Template

When changing commands or tooling:

  1. Update the generated project files in {{cookiecutter.directory_name}}/
  2. Update this repository README so the public usage instructions stay accurate
  3. Check the post-generation hook message so it matches the new workflow
  4. Keep the generated docs internally consistent

Recommended Verification

After editing the template, verify:

cookiecutter . --no-input
cd MyPackageFolder
uv sync
uv run pytest
uv run ruff check .
uv run python -m build

If any command changes, update both the repo docs and the generated docs in the same pass.