Skip to content

Cookiecutter: Templating Engine

Tool: Cookiecutter

Cookiecutter is a cross-platform command-line utility that creates projects from project templates (cookiecutters). Zenith is authored as a Cookiecutter template.

What It Does

Cookiecutter renders directory structures and configuration files using Jinja templating. By evaluating user inputs against interactive prompts and choice matrices defined in cookiecutter.json, it dynamically scaffolds complete projects. Lifecycle hooks executed before and after file generation validate input parameters and perform programmatic filesystem adjustments.

Why It's in Zenith

Zenith is packaged as a Cookiecutter template to provide instant, zero-install scaffolding via uvx cookiecutter gh:bwrob/zenith. As the universal standard for project templating across the Python community, Cookiecutter ensures broad compatibility with existing developer workflows.

Zenith uses post-generation lifecycle hooks (hooks/post_gen_project.py) to enforce strict project hygiene: conditionally stripping optional features like CLI code, removing explanatory comments from rendered configuration files, and establishing symlinks and configuration profiles for AI coding agents.

Configuration in Zenith

Configured in cookiecutter.json at the repository root:

{
    "project_name": "Zenith",
    "project_slug": "{{ cookiecutter.project_name | slugify }}",
    "package_name": "{{ cookiecutter.project_slug | slugify(separator='_') }}",
    "description": "An opinionated, strict Python project powered by uv, ruff, pyrefly, and zensical.",
    "author_name": "bwrob",
    "author_email": "contact@bwrob.dev",
    "github_username": "bwrob",
    "version": "0.1.0",
    "python_version": [
        "3.13",
        "3.12",
        "3.14",
        "3.15"
    ],
    "license": [
        "MIT",
        "Apache-2.0",
        "BSD-3-Clause",
        "None"
    ],
    "include_cli": true,
    "include_ci_testing": true,
    "include_ci_publishing": true,
    "include_agent_skills": true,
    "ai_tools": "all",
    "__year": "{% now 'utc', '%Y' %}",
    "_new_lines": "\n",
    "_jinja2_env_vars": {
        "lstrip_blocks": true
    },
    "_copy_without_render": [
        "docs/assets/*",
        "*.svg",
        "*.png",
        "*.ico"
    ],
    "__prompts__": {
        "project_name": "Project Name (Human-readable title)",
        "project_slug": "Project Slug (Repository and PyPI distribution name)",
        "package_name": "Python Package Name (Import identifier in src/)",
        "description": "Short Project Description",
        "author_name": "Author Full Name",
        "author_email": "Author Email",
        "github_username": "GitHub Username or Organization",
        "version": "Initial Project Version",
        "python_version": {
            "__prompt__": "Target Python Version:",
            "3.13": "Python 3.13 (Current stable, recommended)",
            "3.12": "Python 3.12 (LTS baseline)",
            "3.14": "Python 3.14 (Bleeding edge)",
            "3.15": "Python 3.15 (Future / experimental)"
        },
        "license": {
            "__prompt__": "Select Open Source License:",
            "MIT": "MIT License (Permissive, widely adopted)",
            "Apache-2.0": "Apache 2.0 (Permissive with patent grant)",
            "BSD-3-Clause": "BSD 3-Clause (Permissive with attribution)",
            "None": "Proprietary / No License (All Rights Reserved)"
        },
        "include_cli": "Scaffold Typer/Rich command-line interface?",
        "include_ci_testing": "Generate GitHub Actions workflows for CI testing and code quality?",
        "include_ci_publishing": "Generate GitHub Actions workflow for PyPI Trusted Publishing and documentation deployment?",
        "include_agent_skills": "Include Zenith agent skills suite and SDD subagents (.agents/)?",
        "ai_tools": "AI assistant configs to scaffold ('all', 'recommended', 'ide-only', 'cli-only', 'minimal', 'none', or comma-separated names):"
    }
}

Key Invocations

# Scaffold a new project from remote repository
uvx cookiecutter https://github.com/bwrob/zenith.git

# Scaffold locally during template development
cookiecutter .

Upstream Documentation