Welcome to the documentation for the Buffalo Blueprint project!

This is a copier-based template project for creating new Python projects for the Buffalo Herd organization hosted on Codeberg with a consistent structure, tooling, and documentation.

What You Get

Generated projects include:

src/ layout (src/<package_name>/...)
pyproject.toml with uv dependcy groups
Testing + coverage (pytest + coverage)
Lint/type checking (ruff, mypy, basedpyright)
Sphinx + MyST documentation scaffold
Towncrier changelog workflow
Forgejo/Codeberg CI workflows (docs publishing, CI, towncrier checks)
Standard repo files (LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, CITATION)

Quick Start

Below is a quick summary of how this project is intended to be used. See the copier workflow documents for more information.

Create a New Project

From a remote template repo:

pipx run copier copy --vcs-ref main \
     https://codeberg.org/BuffaloHerd/BuffaloBlueprint.git \
     ./MyNewProject

Or from a local checkout:

pipx run copier copy ./BuffaloBlueprint ./MyNewProject

Update an Existing Project from Template Changes

From inside the generated project:

pipx run copier update

This uses .copier-answers.yaml stored in the project root directory.

Inputs

Copier will prompt for a small set of project-specific values (name, slug, package name, supported Python versions, keywords, etc.). These are stored in .copier-answers.yaml in the project root directory. See the copier project variables document for the details.

Design Choices

This template intentionally standardizes on:

src/ layout
uv for environment + dependency group management
Towncrier for changelog fragments and release notes
Sphinx/MyST for HTML documentation
Codeberg/Forgejo workflows for CI + docs publishing

If you want different defaults, fork this template and adjust copier.yaml and the templated files.

License

This template is licensed under GPLv3. Generated projects inherit the same license by default.

Guides