Python Project Template

🚀 A production‑ready Python project template to help developers bootstrap new Python projects fast. It includes modern packaging, local tooling, Docker, and a complete CI/CD suite.

Click Use this template to start a new repository from this scaffold.

Other Languages: English | 繁體中文 | 简体中文

✨ Highlights

• Modern src/ layout and type‑hinted code
• Fast dependency management via uv
• Pre‑commit suite: ruff, mdformat(+plugins), codespell, nbstripout, mypy, uv hooks
• Strong typing: mypy with Pydantic plugin configuration
• Pytest with coverage and xdist; PR coverage summary comment
• Coverage gate at 80% with HTML/XML reports committed under .github/
• MkDocs Material with mkdocstrings (inheritance diagrams), markdown‑exec, MathJax
• Dev server at 0.0.0.0:9987; bilingual docs scaffolded
• Docs generator script: by class/file, optional notebook execution, concurrency, preserves folder structure
• Async file processing via anyio and rich progress bars
• Packaging with uv build and changelog via git-cliff
• Automatic PEP 440 versioning from git via dunamai in CI
• Dockerfile multi‑stage with uv/uvx and Node.js; Compose services (Redis/Postgres/Mongo/MySQL) with healthchecks and volumes
• GitHub Actions: tests, quality, docs deploy, package build, docker image publish (GHCR with buildx cache), release drafter, auto labeler, secret scan, semantic PR, pre‑commit auto‑update
• Pre‑commit runs on multiple git stages (pre‑commit, post‑checkout, post‑merge, post‑rewrite)
• i18n‑friendly linting (Chinese punctuation allowed confusables)
• Alternative env managers documented (Rye, Conda)
• Legacy compatibility: export requirements.txt via uv pip if needed

🚀 Quick Start

Prerequisites:

• Python 3.10–3.13
• uv (install with make uv-install)
• Pre-commit hooks: either uv tool install pre-commit or uv sync --group dev

Local setup:

make uv-install               # once
uv sync                       # install base deps
uv tool install pre-commit    # or: uv sync --group dev
make format                   # run pre-commit hooks
make test                     # run tests

Run the example CLI:

uv run coding-agent

🧰 Commands Reference

# Development
make help               # List available make targets
make clean              # Clean caches, artifacts and generated docs
make format             # Run all pre-commit hooks
make test               # Run pytest across the repository
make gen-docs           # Generate docs from src/ and scripts/

# Git submodules (if you use them)
make submodule-init     # Init and update all submodules
make submodule-update   # Update all submodules to remote

# Dependencies (via uv)
make uv-install         # Install uv on your system
uv add <pkg>            # Add production dependency
uv add <pkg> --dev      # Add development dependency
# Sync optional groups
uv sync --group dev     # Install dev-only deps (pre-commit, poe, notebook)
uv sync --group test    # Install test-only deps
uv sync --group docs    # Install docs-only deps

📚 Documentation

• Live docs are built with MkDocs Material.
• Generate API docs locally and serve:

uv sync --group docs
make gen-docs
uv run mkdocs serve    # http://localhost:9987

• Auto generation script: scripts/gen_docs.py (supports .py and .ipynb)

# Generate docs by class (default)
uv run python ./scripts/gen_docs.py --source ./src --output ./docs/Reference gen_docs

# Generate docs by file
uv run python ./scripts/gen_docs.py --source ./src --output ./docs/Reference --mode file gen_docs

🐳 Docker and Local Services

docker-compose.yaml includes optional services for local development: redis, postgresql, mongodb, mysql, and an example app service that runs the CLI.

Create a .env file to configure ports and credentials (defaults shown):

REDIS_PORT=6379
POSTGRES_DB=postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_PORT=5432
MONGO_PORT=27017
MYSQL_ROOT_PASSWORD=root
MYSQL_DATABASE=mysql
MYSQL_USER=mysql
MYSQL_PASSWORD=mysql
MYSQL_PORT=3306

Run services:

docker compose up -d redis postgresql mongodb mysql

# Or run the example app container
docker compose up -d app

📦 Packaging and Distribution

Build artifacts with uv (wheel and sdist go to dist/):

uv build

Publish to PyPI (requires UV_PUBLISH_TOKEN):

UV_PUBLISH_TOKEN=... uv publish

CI builds also run automatically on tags matching v* and upload artifacts. Uncomment the publish step in build_package.yml to automate releases to PyPI.

Run your CLI locally and from PyPI

• Local (from this repo):

uv run coding-agent
uv run cli

• From PyPI with uvx after publishing (ephemeral install):

# If your console script is named "coding-agent"
uvx coding-agent

# Disambiguate or pin a package/version
uvx --from your-package-name==0.1.0 your-entrypoint

🧭 Optional task runner (Poe the Poet)

Convenience tasks are defined under [tool.poe.tasks] in pyproject.toml and available after installing the dev group (uv sync --group dev) or via uvx:

uv run poe docs        # generate + serve docs (requires dev group)
uv run poe gen         # generate + deploy docs (gh-deploy) (requires dev group)
uv run poe main        # run CLI entry (same as uv run coding-agent)

# or ephemeral via uvx (no local install)
uvx poe docs

🔁 CI/CD Actions Overview

All workflows live in .github/workflows/. This section explains what each action does, when it runs, and what to configure.

• Tests (test.yml)

  • Trigger: Pull requests to main or release/* (ignores md files)
  • Runs pytest on Python 3.10/3.11/3.12/3.13 with coverage and comments a summary
  • Setup needed: none

• Code Quality Check (code-quality-check.yml)

  • Trigger: Pull requests
  • Runs ruff and other pre-commit hooks
  • Setup needed: none

• Docs Deploy (deploy.yml)

  • Trigger: Push to main and tags v*
  • Builds mkdocs site and publishes to GitHub Pages
  • Setup needed:
    • Enable GitHub Pages for the repo (Actions → Pages)
    • The workflow configures and uploads the site automatically

• Build Package (build_package.yml)

  • Trigger: Tags v*
  • Builds wheel/sdist via uv build and uploads artifacts; updates changelog
  • Optional publish: uncomment the uv publish step and add secret UV_PUBLISH_TOKEN

• Publish Docker Image (build_image.yml)

  • Trigger: Push to main and tags v*
  • Builds and pushes a Docker image to GHCR: ghcr.io/<owner>/<repo>
  • Setup needed: none (uses GITHUB_TOKEN); ensure docker/Dockerfile defines prod target

• Build Executable (build_executable.yml)

  • Trigger: Tags v* (Windows runner)
  • Currently stubs out packaging (example commented). Uploads a zip artifact
  • To ship a real executable, add your PyInstaller (or similar) steps

• Release Drafter (release_drafter.yml)

  • Trigger: Push to main and PR events
  • Maintains a draft release based on Conventional Commits

• Pull Request Labeler (auto_labeler.yml)

  • Trigger: PRs and pushes
  • Auto-applies labels defined in .github/labeler.yml

• Secret Scanning (secret_scan.yml)

  • Trigger: Push and PR
  • Runs gitleaks to detect leaked secrets

• Semantic Pull Request (semantic-pull-request.yml)

  • Trigger: PR open/edit/sync
  • Enforces Conventional Commit style PR titles

CI/CD Configuration Checklist

• Conventional commits for PR titles (enforced by the workflow)
• Optional: set UV_PUBLISH_TOKEN secret to publish to PyPI
• Optional: enable GitHub Pages (used by docs deploy)
• Container Registry permissions are handled automatically via GITHUB_TOKEN

🧩 Example CLI

Console entry points are defined in pyproject.toml as coding-agent and cli. The example returns a simple Response model; replace with your own CLI logic.

uv run coding-agent

🤝 Contributing

• Open issues/PRs
• Follow the coding style (ruff, type hints)
• Use Conventional Commit messages and descriptive PR titles

📄 License

MIT — see LICENSE.