From 66ade25a855722f2dd0de1eeec9f77d07c9a670a Mon Sep 17 00:00:00 2001 From: ulises-jeremias Date: Sat, 18 Jul 2026 17:14:07 -0300 Subject: [PATCH] docs: overhaul CPA package README to CNA parity Rewrite the PyPI-facing create-awesome-python-app README with install channels, recipes, CLI/cache reference, and site links; refresh the monorepo README to point users at the package docs (#221). Co-authored-by: Cursor --- README.md | 157 +++-- packages/create-awesome-python-app/README.md | 601 ++++++++++++++++++- 2 files changed, 685 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 81ad28b..0fdc0cf 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,12 @@ -# create-python-app + + +
+ +# Create Awesome Python App + +**The open-source monorepo behind `create-awesome-python-app`: compose templates and addons into production-ready Python, FastAPI, Django, Celery, CLI, and uv workspace projects.** + +One command. Any stack. [![CI Tests](https://github.com/Create-Python-App/create-python-app/actions/workflows/test.yml/badge.svg)](https://github.com/Create-Python-App/create-python-app/actions/workflows/test.yml) [![Lint](https://github.com/Create-Python-App/create-python-app/actions/workflows/lint.yml/badge.svg)](https://github.com/Create-Python-App/create-python-app/actions/workflows/lint.yml) @@ -9,70 +17,70 @@ [![Homebrew](https://img.shields.io/badge/homebrew-Create--Python--App%2Ftap-orange?logo=homebrew)](https://github.com/Create-Python-App/homebrew-tap) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) -Composable scaffolding CLI for production-ready Python apps. +[Package README](./packages/create-awesome-python-app/README.md) · [Official Site](https://create-awesome-python-app.vercel.app) · [Templates](https://create-awesome-python-app.vercel.app/templates) · [Extensions](https://create-awesome-python-app.vercel.app/extensions) · [Contributing](./CONTRIBUTING.md) · [Troubleshooting](./docs/TROUBLESHOOTING.md) -> **Status:** CLI monorepo bootstrapped. Template bank: [`cpa-templates`](https://github.com/Create-Python-App/cpa-templates). Roadmap: [#1](https://github.com/Create-Python-App/create-python-app/issues/1). +
-## Ecosystem +--- -| Repository | Role | -|------------|------| -| [create-python-app](https://github.com/Create-Python-App/create-python-app) (this repo) | CLI (`create-awesome-python-app`) and scaffolding engine (`create-python-app-core`) | -| [cpa-templates](https://github.com/Create-Python-App/cpa-templates) | Official templates and extensions (`templates.json` catalog) | -| [homebrew-tap](https://github.com/Create-Python-App/homebrew-tap) | Homebrew formula | -| [aur-package](https://github.com/Create-Python-App/aur-package) | AUR PKGBUILD mirror | +## What This Repo Contains -The CLI fetches the catalog from: +This repository contains the source code for [`create-awesome-python-app`](https://pypi.org/project/create-awesome-python-app/), the CLI that composes curated templates, addons, custom options, and AI-ready conventions into working projects. -`https://raw.githubusercontent.com/Create-Python-App/cpa-templates/main/templates.json` +Use this README if you want to understand the codebase, run it locally, contribute a fix, improve documentation, or work on the CLI packages. If you only want to generate an app, start with the [package README](./packages/create-awesome-python-app/README.md). -Override with `CPA_CATALOG_URL` for forks or local testing (`file://` supported). +--- -## Install +## Quick Start For Users ```bash -# PyPI / uv uvx create-awesome-python-app@latest my-app - -# Homebrew -brew tap Create-Python-App/tap -brew install create-awesome-python-app - -# AUR -yay -S create-awesome-python-app - -# Docker -docker run --rm -it -v "${PWD}:/app" -w /app \ - ulisesjeremias/create-awesome-python-app my-app ``` -Or pin a version: +Run headlessly for scripts, CI, or platform automation: ```bash -uvx create-awesome-python-app@0.1.0 my-app --template fastapi-starter --no-interactive +uvx create-awesome-python-app my-api \ + --template fastapi-starter \ + --addons github-setup \ + --addons fastapi-sqlalchemy \ + --no-interactive ``` -From this workspace (development): +More examples live in the [CLI package README](./packages/create-awesome-python-app/README.md). -```bash -uv sync -uv run create-awesome-python-app --help -``` +--- -### Shell completion +## Ecosystem -```bash -create-awesome-python-app --install-completion # bash / zsh / fish -create-awesome-python-app --show-completion # print script only -``` +| Repository | Role | +|------------|------| +| [create-python-app](https://github.com/Create-Python-App/create-python-app) (this repo) | CLI (`create-awesome-python-app`) and scaffolding engine (`create-python-app-core`) | +| [cpa-templates](https://github.com/Create-Python-App/cpa-templates) | Official templates and extensions (`templates.json` catalog) | +| [website](https://github.com/Create-Python-App/website) | Docs + catalog UI ([create-awesome-python-app.vercel.app](https://create-awesome-python-app.vercel.app)) | +| [homebrew-tap](https://github.com/Create-Python-App/homebrew-tap) | Homebrew formula | +| [aur-package](https://github.com/Create-Python-App/aur-package) | AUR PKGBUILD mirror | -## License +The CLI fetches the catalog from: -MIT — see [LICENSE](./LICENSE). +`https://raw.githubusercontent.com/Create-Python-App/cpa-templates/main/templates.json` + +Override with `CPA_CATALOG_URL` for forks or local testing (`file://` supported). -## Monorepo layout (uv workspaces) +--- -This repository is a **virtual uv workspace**: the root is not published; packages live under `packages/*` and share one `uv.lock` / `.venv`. +## Repository Map + +This is a **virtual uv workspace**: the root is not published; packages live under `packages/*` and share one `uv.lock` / `.venv`. + +| Path | Purpose | +|------|---------| +| [`packages/create-awesome-python-app`](./packages/create-awesome-python-app) | Main CLI package (Typer), interactive wizard, catalog listing | +| [`packages/create-python-app-core`](./packages/create-python-app-core) | Scaffolding engine: resolve sources, merge layers, install, git init | +| [`docs/`](./docs) | Brand, troubleshooting, migration, distribution, versioning | +| [`.github/workflows`](./.github/workflows) | CI, release, Docker / Homebrew / AUR publish, distribution smoke | + +Template and extension data is maintained in [`Create-Python-App/cpa-templates`](https://github.com/Create-Python-App/cpa-templates). This repo consumes that catalog remotely. ```text create-python-app/ # virtual workspace root (no [project] table) @@ -84,16 +92,34 @@ create-python-app/ # virtual workspace root (no [project] table) └── create-awesome-python-app/ # CLI (depends on core via workspace) ``` -### Setup +--- + +## Local Development + +Requires **Python 3.12+** (pinned in `.python-version`) and [uv](https://docs.astral.sh/uv/): ```bash -# Requires uv: https://docs.astral.sh/uv/ +git clone https://github.com/Create-Python-App/create-python-app.git +cd create-python-app uv sync --group dev +uv run create-awesome-python-app --help ``` -## Development commands +Non-interactive local smoke test: -From the repo root (requires [uv](https://docs.astral.sh/uv/)): +```bash +uv run create-awesome-python-app smoke-app \ + --template fastapi-starter \ + --addons github-setup \ + --no-interactive \ + --no-install +``` + +Install git hooks: `uv run pre-commit install` + +--- + +## Development Commands | Task | Make | Equivalent | |------|------|------------| @@ -103,38 +129,45 @@ From the repo root (requires [uv](https://docs.astral.sh/uv/)): | Type-check | `make typecheck` | `uv run pyright` | | Build packages | `make build` | `uv build --all` | -Install git hooks: `uv run pre-commit install` - -## Python version +--- -- **Pin file:** `.python-version` → `3.12` -- **Constraint:** every workspace member sets `requires-python = ">=3.12"` -- **CI:** workflows install Python 3.12+ matching this pin +## Install Channels (published package) ```bash -uv python install -uv sync --group dev -``` +# PyPI / uv +uvx create-awesome-python-app@latest my-app -## Docker +# Homebrew +brew tap Create-Python-App/tap +brew install create-awesome-python-app -Published image: [`ulisesjeremias/create-awesome-python-app`](https://hub.docker.com/r/ulisesjeremias/create-awesome-python-app) +# AUR +yay -S create-awesome-python-app -```bash -docker run --rm ulisesjeremias/create-awesome-python-app:0.1.0 --version +# Docker docker run --rm -it -v "${PWD}:/app" -w /app \ - ulisesjeremias/create-awesome-python-app my-app --template fastapi-starter --no-interactive + ulisesjeremias/create-awesome-python-app:latest my-app \ + --template fastapi-starter ``` -Local build (installs the given PyPI version into the image): +Published image: [`ulisesjeremias/create-awesome-python-app`](https://hub.docker.com/r/ulisesjeremias/create-awesome-python-app) + +Local image build (installs the given PyPI version into the image): ```bash -docker build --build-arg VERSION=0.1.0 -t create-awesome-python-app . +docker build --build-arg VERSION=0.2.5 -t create-awesome-python-app . docker run --rm create-awesome-python-app --help ``` +--- + +## License + +MIT — see [LICENSE](./LICENSE). + ### Reference +- [Package README](./packages/create-awesome-python-app/README.md) — user-facing CLI docs - [uv workspaces handbook](https://pydevtools.com/handbook/how-to/how-to-set-up-a-python-monorepo-with-uv-workspaces/) - [cpa-templates](https://github.com/Create-Python-App/cpa-templates) — template and extension bank - Node parity: [Create-Node-App/create-node-app](https://github.com/Create-Node-App/create-node-app) + [cna-templates](https://github.com/Create-Node-App/cna-templates) diff --git a/packages/create-awesome-python-app/README.md b/packages/create-awesome-python-app/README.md index 2f90100..e698183 100644 --- a/packages/create-awesome-python-app/README.md +++ b/packages/create-awesome-python-app/README.md @@ -1,26 +1,605 @@ -# create-awesome-python-app + -![banner](./assets/hero.svg) +
-CLI package. Framework: **Typer** (chosen over Click for richer typing/help). +Create Awesome Python App banner + +# Create Awesome Python App + +**One command. Any stack.** Generate production-ready Python apps by composing templates, addons, and AI-ready conventions. + +From blank folder to a working FastAPI, Django, Celery, CLI, or uv workspace project with modern tooling and team-friendly automation. + +[![PyPI][pypiversion]][pypiurl] +[![Python][pythonbadge]][pythonurl] +[![Stars][starsbadge]][starsurl] +[![License: MIT][licensebadge]][licenseurl] + +[![AUR][aurbadge]][aururl] +[![Homebrew][homebrewbadge]][homebrewurl] +[![Docker][dockerbadge]][dockerurl] +[![Smoke tests][smokebadge]][smokeurl] + +[![Tests][testsbadge]][testsurl] +[![Lint][lintbadge]][linturl] +[![Typecheck][typecheckbadge]][typecheckurl] +[![MegaLinter][megalinterbadge]][megalinterurl] +[![Shellcheck][shellcheckbadge]][shellcheckurl] +[![Commit Activity][commitactivitybadge]][commitactivityurl] + +**[Official Site](https://create-awesome-python-app.vercel.app)** · [Templates](https://create-awesome-python-app.vercel.app/templates) · [Extensions](https://create-awesome-python-app.vercel.app/extensions) · [Docs](https://create-awesome-python-app.vercel.app/docs) · [GitHub](https://github.com/Create-Python-App/create-python-app) · [PyPI](https://pypi.org/project/create-awesome-python-app/) + +
+ +--- + +## Install + +**uv (recommended):** + +```bash +uvx create-awesome-python-app@latest my-app +``` + +**pipx:** ```bash -uv run create-awesome-python-app --help -uvx create-awesome-python-app@latest my-app # after PyPI publish pipx run create-awesome-python-app my-app ``` -## Shell completion +**Homebrew (macOS / Linux):** + +```bash +brew tap Create-Python-App/tap +brew install create-awesome-python-app +``` + +**AUR (Arch Linux):** + +```bash +yay -S create-awesome-python-app # or: paru -S create-awesome-python-app +``` + +**Docker:** + +```bash +docker run --rm -it -v "${PWD}:/app" -w /app \ + ulisesjeremias/create-awesome-python-app:latest my-app \ + --template fastapi-starter +``` -Typer installs completion scripts for bash, zsh, and fish: +Interactive by default outside CI. For automation, run headless with flags: ```bash -# Interactive install into your shell profile -create-awesome-python-app --install-completion +uvx create-awesome-python-app my-api \ + --template fastapi-starter \ + --addons github-setup \ + --addons fastapi-sqlalchemy \ + --no-interactive +``` + +| If you want... | Start here | +| ----------------------------- | ------------------------------------------------------- | +| A guided local setup | `uvx create-awesome-python-app@latest my-app` | +| A repeatable CI/platform flow | `--no-interactive` with explicit flags | +| Your company starter | `--template ` or `--template file://` | +| Private standards layered in | `--extend ` | -# Or print the script and source it manually -create-awesome-python-app --show-completion +### Shell completion + +```bash +create-awesome-python-app --install-completion # bash / zsh / fish +create-awesome-python-app --show-completion # print script only ``` After installing, restart the shell (or `source` your profile) and tab-complete flags such as `--template`, `--addons`, and `cache` subcommands. + +--- + +## Why CPA? + +| Capability | Value | +| -------------------------------- | ---------------------------------------------------------------------------------------------- | +| **Composable by design** | Start with a template, then layer only the addons your project actually needs. | +| **Production-ready defaults** | uv, Ruff, Pyright, tests, docs, and practical DX defaults out of the box. | +| **AI-ready from day one** | Supported templates generate `AGENTS.md` so coding agents understand the project context. | +| **CI and platform friendly** | Use `--no-interactive`, `--set`, `--template `, and `--extend ` for repeatable runs. | + +--- + +## Composition Model + +```text +template -> addons -> custom options -> install -> git init -> AI-ready project +``` + +You can mix catalog templates and addons with your own GitHub or `file://` sources. + +--- + +## What You Can Generate + +### Template Families + +| Category | Example templates | +| -------- | ------------------------------------------------------ | +| Backend | `fastapi-starter`, `django-api`, `celery-worker` | +| CLI | `cli-starter` | +| Monorepo | `uv-workspace-starter` | + +### Addon Families + +| Category | Examples | +| -------------- | ------------------------------------------------------------- | +| CI / tooling | `github-setup`, `development-container` | +| Containers | `fastapi-docker`, `django-docker`, `celery-docker` | +| Database | `postgres`, `fastapi-sqlalchemy`, `fastapi-redis` | +| Observability | `fastapi-sentry` | +| Security | `fastapi-auth-jwt` | + +Browse the live catalog on the [official site](https://create-awesome-python-app.vercel.app/templates) or in [`cpa-templates`](https://github.com/Create-Python-App/cpa-templates). + +--- + +## Popular Recipes + +### FastAPI + GitHub + SQLAlchemy + +```bash +uvx create-awesome-python-app my-api \ + --template fastapi-starter \ + --addons github-setup \ + --addons fastapi-sqlalchemy \ + --no-interactive +``` + +### Django API + Postgres + Docker + +```bash +uvx create-awesome-python-app my-django \ + --template django-api \ + --addons github-setup \ + --addons postgres \ + --addons django-docker \ + --no-interactive +``` + +### Celery worker + Redis-friendly stack + +```bash +uvx create-awesome-python-app my-worker \ + --template celery-worker \ + --addons github-setup \ + --addons celery-docker \ + --no-interactive +``` + +### Typer / Click CLI starter + +```bash +uvx create-awesome-python-app my-cli \ + --template cli-starter \ + --addons github-setup \ + --no-interactive +``` + +### uv workspace monorepo + +```bash +uvx create-awesome-python-app my-workspace \ + --template uv-workspace-starter \ + --addons github-setup \ + --no-interactive +``` + +### Internal platform template (GitHub URL) + +```bash +uvx create-awesome-python-app my-internal-app \ + --template "https://github.com/your-org/platform-starters?subdir=templates/internal-app" \ + --no-interactive +``` + +### Local template development (`file://`) + +```bash +uvx create-awesome-python-app my-local-app \ + --template "file:///absolute/path/to/cpa-templates?subdir=templates/fastapi-starter" \ + --no-interactive +``` + +> `file://` template URLs should be absolute paths (for example `file:///Users/...` or `file:///home/...`). + +### Layer a private extension + +```bash +uvx create-awesome-python-app my-app \ + --template fastapi-starter \ + --addons github-setup \ + --extend "https://github.com/your-org/platform-starters?subdir=extensions/company-ci" +``` + +### Pass custom template values + +```bash +uvx create-awesome-python-app my-app \ + --template fastapi-starter \ + --set "productName=Acme Cloud" \ + --set "author=Platform Team" \ + --no-interactive +``` + +--- + +## Built For Modern Teams + +- Python 3.12+ runtime support. +- uv-first workflows (with pipx / Homebrew / AUR / Docker install paths). +- Interactive wizard for local workflows. +- `--no-interactive` mode for CI, scripts, and platform automation. +- GitHub URL and local `file://` template inputs. +- `--extend` support for private addon layering. +- `--set key=value` overrides for deterministic custom options. + +--- + +## Explore The Catalog + +Browse visually at **[create-awesome-python-app.vercel.app](https://create-awesome-python-app.vercel.app)** or discover from the terminal: + +```bash +# List all available templates +uvx create-awesome-python-app --list-templates + +# List addons (optionally filtered by template) +uvx create-awesome-python-app --template fastapi-starter --list-addons +``` + +Full catalog: + +- **Templates:** [create-awesome-python-app.vercel.app/templates](https://create-awesome-python-app.vercel.app/templates) +- **Extensions:** [create-awesome-python-app.vercel.app/extensions](https://create-awesome-python-app.vercel.app/extensions) +- **Source data:** [`cpa-templates/templates.json`](https://github.com/Create-Python-App/cpa-templates/blob/main/templates.json) + +Override the catalog URL with `CPA_CATALOG_URL` (HTTPS or `file://`) for forks and local testing. + +--- + +## AI-Ready With `AGENTS.md` + +Supported templates generate an `AGENTS.md` file so coding assistants understand project context before editing: + +| Context | Why it matters | +| ---------------------- | ----------------------------------------------------------- | +| Project purpose | Agents understand what the app is for before changing code. | +| Directory layout | Suggestions align with the real structure. | +| Scripts and validation | Agents know how to lint, test, and verify changes. | +| Team conventions | Output follows naming and workflow expectations. | + +--- + +## Interactive Wizard + +Run the CLI without flags and CPA guides you through: + +| Step | What you choose | +| ----------------- | ----------------------------------------------------------------------- | +| Project name | Confirm or set the target directory | +| Category | Backend, CLI, Monorepo, or custom URL | +| Template | Pick from curated starters with descriptions and labels | +| Addons | Multi-select compatible extensions grouped by purpose | +| Custom options | Answer `cpa.config.json` / registry prompts when present | +| Custom extensions | Layer extra URLs for internal standards | + +--- + +## Requirements + +- **Python >= 3.12** +- [uv](https://docs.astral.sh/uv/) recommended (or pipx / Homebrew / AUR / Docker) +- `git` available on `PATH` (required to clone templates) + +Recommended quick start: + +```bash +uv python install 3.12 +uvx create-awesome-python-app@latest my-app +``` + +--- + +## CLI Reference + +```text +Usage: create-awesome-python-app [OPTIONS] [project_directory] +``` + +| Flag | Description | +| ---------------------------- | ----------------------------------------------------- | +| `--interactive` | Force interactive wizard (default outside CI) | +| `--no-interactive` | Disable wizard and use flags only | +| `-t, --template ` | Template slug from catalog or remote/local URL | +| `--addons ` | Addon slug or URL (repeat the flag for multiple) | +| `--extend ` | Extra extension URL layered on top (repeatable) | +| `--set ` | Set custom template options; quote values with spaces | +| `--no-install` | Generate files without installing dependencies | +| `-f, --force` | Allow scaffolding into a non-empty target directory | +| `--list-templates` | Print all templates | +| `--list-addons` | Print addons, optionally filtered by `--template` | +| `--offline` | Use the local cache only; do not refresh templates | +| `--no-cache` | Disable the catalog cache; force a refresh each run | +| `--cache-dir ` | Override the cache root (default: `~/.cache/cpa`) | +| `--refresh ` | When to refresh: `always` \| `stale` \| `manual` | +| `--pin ` | Pin template to a specific commit SHA, tag, or branch | +| `--strict-version` | Fail if a newer CLI version is available | +| `--keep-on-failure` | Keep partial output if scaffolding fails | +| `-v, --verbose` | Output resolved generation config as JSON | +| `-i, --info` | Print Python, uv, git, and OS diagnostics | +| `--version` | Print CLI version | +| `--help` | Show help | + +### `cache` subcommand + +```text +Usage: create-awesome-python-app cache [OPTIONS] COMMAND [ARGS]... + +Commands: + dir Print the cache root directory + list List cached templates and extensions + clean Remove one or all entries + verify Run `git fsck` on one or all entries + outdated List cached entries that are behind their remote tip + update Refresh one or all cached entries from their remote + doctor Diagnose cache health (git, network, permissions) +``` + +Inspect and manage the on-disk cache: + +```bash +# Where is my cache? +uvx create-awesome-python-app cache dir +# /home//.cache/cpa + +# What's in it? +uvx create-awesome-python-app cache list + +# Verify integrity +uvx create-awesome-python-app cache verify + +# Clear everything +uvx create-awesome-python-app cache clean + +# Check for outdated entries +uvx create-awesome-python-app cache outdated + +# Refresh a specific entry (or all) +uvx create-awesome-python-app cache update + +# Diagnose cache health +uvx create-awesome-python-app cache doctor +``` + +--- + +## Cache & Updates + +CPA caches both the **template catalog** (`templates.json` from +`raw.githubusercontent.com`) and the **template git repos** themselves. The +cache lives at `~/.cache/cpa` by default; override with `--cache-dir +` or `CPA_CACHE_DIR`. + +| Path | Contents | +| ----------------------- | ---------------------------------- | +| `~/.cache/cpa/catalog/` | Cached `templates.json` | +| `~/.cache/cpa/repos/` | Shallow clones of templates / addons | + +### Refresh modes (set with `--refresh ` or `CPA_REFRESH=`) + +- **`stale`** (default): pull only when the cache is older than + `CPA_REFRESH_AFTER_HOURS` (default `24`). No network on a warm cache. +- **`always`**: pull on every run. +- **`manual`**: never pull unless `--refresh` is passed. + +### Pinning templates + +Pin a template to a specific commit SHA, tag, or branch: + +```bash +uvx create-awesome-python-app my-app \ + --template fastapi-starter \ + --pin abc123def456abc123def456abc123def456abc1 \ + --no-interactive +``` + +The `--pin` flag is equivalent to appending `?ref=` to the template URL. +Combine with `CPA_STRICT_REPRO=1` to enforce full 40-character SHAs. + +### CI and offline usage + +```bash +# Fully offline CI: use the local cache only, no network. +uvx create-awesome-python-app my-app \ + --template fastapi-starter \ + --offline \ + --no-interactive + +# Pin the cache to a project-local directory (useful in monorepos and CI). +CPA_CACHE_DIR="$PWD/.cpa-cache" uvx create-awesome-python-app my-app \ + --template fastapi-starter \ + --no-interactive +``` + +--- + +## Programmatic Usage + +Need to integrate CPA into your own tooling? The core is importable: + +```python +import asyncio +from create_python_app_core import create_python_app + +asyncio.run( + create_python_app( + "my-app", + { + "template": ( + "https://github.com/Create-Python-App/cpa-templates" + "?subdir=templates/fastapi-starter" + ), + "addons": [], + "install": False, + }, + ) +) +``` + +> The programmatic API is experimental and subject to change. Prefer the CLI for stable usage. + +See also: [`create-python-app-core` README](https://github.com/Create-Python-App/create-python-app/blob/main/packages/create-python-app-core/README.md). + +--- + +## Security + +CPA downloads templates from remote sources. Prefer catalog slugs or hash-pinned +refs (`--pin` / `?ref=`), audit custom URLs before use, and report vulnerabilities +via GitHub Security Advisories on +[Create-Python-App/create-python-app](https://github.com/Create-Python-App/create-python-app). + +--- + +## FAQ + +
+Why another scaffolder? + +Most scaffolders lock you into one stack. CPA is composable: choose a template, layer focused addons, and plug in your own GitHub/local blueprints — mirroring [Create Awesome Node App](https://github.com/Create-Node-App/create-node-app) for the Python ecosystem. + +
+ +
+Can I use my own template? + +Yes. Pass a GitHub URL or local `file://` URL with `--template` (supports `?subdir=` and `?ref=`). + +
+ +
+Can I use private/internal extensions? + +Yes. Use `--extend ` to layer private extensions on top of a template and addon set. + +
+ +
+Are addons order-sensitive? + +Yes. Addons are applied in sequence. If two addons modify the same file, later addons win. + +
+ +
+Does it support monorepos? + +Yes. Use `uv-workspace-starter` to bootstrap a multi-package uv workspace with shared tooling. + +
+ +
+Can I use it in CI? + +Yes. Pass all required flags and use `--no-interactive` for deterministic automation. Set `CI=true` to disable the wizard by default. + +
+ +
+Is Python 3.12 required? + +Yes. CPA targets Python 3.12+ to keep runtime behavior modern and predictable. + +
+ +
+Does CPA work with AI coding assistants? + +Yes. Supported templates generate `AGENTS.md`, helping assistants understand project layout, scripts, and conventions. + +
+ +
+Docker says `git executable not found` + +Images from `0.2.5` onward ship `git`. Pull `ulisesjeremias/create-awesome-python-app:latest` (or `0.2.5+`) and retry. + +
+ +--- + +## Roadmap + +- More framework templates and vertical starters. +- Additional testing and observability packs. +- Diff-based upgrade paths for pinned templates. +- Richer template analytics and usage insights. + +Track progress in [Issues](https://github.com/Create-Python-App/create-python-app/issues) and [Discussions](https://github.com/Create-Python-App/create-python-app/discussions). + +--- + +## Contributing + +Templates, addons, bug fixes, docs, recipes, and ideas are all welcome. + +- **Main repo:** [github.com/Create-Python-App/create-python-app](https://github.com/Create-Python-App/create-python-app) +- **Template and extension data:** [github.com/Create-Python-App/cpa-templates](https://github.com/Create-Python-App/cpa-templates) +- **Contributing guide:** [CONTRIBUTING.md](https://github.com/Create-Python-App/create-python-app/blob/main/CONTRIBUTING.md) +- **Troubleshooting:** [docs/TROUBLESHOOTING.md](https://github.com/Create-Python-App/create-python-app/blob/main/docs/TROUBLESHOOTING.md) + +--- + +## License + +MIT © [Create Python App Contributors](https://github.com/Create-Python-App/create-python-app/graphs/contributors) + +--- + +
+ +**[create-awesome-python-app.vercel.app](https://create-awesome-python-app.vercel.app)** + +_Built for developers who value speed, composability, craft, and AI-ready workflows._ + +
+ + + +[testsbadge]: https://github.com/Create-Python-App/create-python-app/actions/workflows/test.yml/badge.svg +[lintbadge]: https://github.com/Create-Python-App/create-python-app/actions/workflows/lint.yml/badge.svg +[typecheckbadge]: https://github.com/Create-Python-App/create-python-app/actions/workflows/type-check.yml/badge.svg +[shellcheckbadge]: https://github.com/Create-Python-App/create-python-app/actions/workflows/shellcheck.yml/badge.svg +[megalinterbadge]: https://github.com/Create-Python-App/create-python-app/actions/workflows/mega-linter.yml/badge.svg +[pypiversion]: https://img.shields.io/pypi/v/create-awesome-python-app.svg?style=flat-square&color=3775A9 +[pythonbadge]: https://img.shields.io/pypi/pyversions/create-awesome-python-app.svg?style=flat-square +[starsbadge]: https://img.shields.io/github/stars/Create-Python-App/create-python-app?style=flat-square&color=yellow +[licensebadge]: https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square +[testsurl]: https://github.com/Create-Python-App/create-python-app/actions/workflows/test.yml +[linturl]: https://github.com/Create-Python-App/create-python-app/actions/workflows/lint.yml +[typecheckurl]: https://github.com/Create-Python-App/create-python-app/actions/workflows/type-check.yml +[shellcheckurl]: https://github.com/Create-Python-App/create-python-app/actions/workflows/shellcheck.yml +[megalinterurl]: https://github.com/Create-Python-App/create-python-app/actions/workflows/mega-linter.yml +[pypiurl]: https://pypi.org/project/create-awesome-python-app/ +[pythonurl]: https://pypi.org/project/create-awesome-python-app/ +[licenseurl]: https://github.com/Create-Python-App/create-python-app/blob/main/LICENSE +[starsurl]: https://github.com/Create-Python-App/create-python-app/stargazers +[commitactivitybadge]: https://img.shields.io/github/commit-activity/m/Create-Python-App/create-python-app?style=flat-square&logo=github&label=commits +[commitactivityurl]: https://github.com/Create-Python-App/create-python-app/pulse +[aururl]: https://aur.archlinux.org/packages/create-awesome-python-app +[aurbadge]: https://img.shields.io/aur/version/create-awesome-python-app?style=flat-square&label=AUR&logo=archlinux +[homebrewurl]: https://github.com/Create-Python-App/homebrew-tap +[homebrewbadge]: https://img.shields.io/badge/homebrew-Create--Python--App%2Ftap-orange?style=flat-square&logo=homebrew +[dockerurl]: https://hub.docker.com/r/ulisesjeremias/create-awesome-python-app +[dockerbadge]: https://img.shields.io/docker/v/ulisesjeremias/create-awesome-python-app?style=flat-square&label=Docker&logo=docker&color=2496ED +[smokebadge]: https://github.com/Create-Python-App/create-python-app/actions/workflows/smoke-distribution.yml/badge.svg?event=schedule +[smokeurl]: https://github.com/Create-Python-App/create-python-app/actions/workflows/smoke-distribution.yml