Skip to content

docs: overhaul CPA package README to CNA parity#222

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ulises-jeremias merged 1 commit into from
Jul 18, 2026
Merged

docs: overhaul CPA package README to CNA parity #222

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 95 additions & 62 deletions README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,12 @@
# create-python-app
<!--lint disable double-link awesome-heading awesome-git-repo-age awesome-toc-->

<div align="center">

# 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)
Expand All@@ -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).
</div>

## 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)
Expand All@@ -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 |
|------|------|------------|
Expand All@@ -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)
Loading
Loading