Skip to content

prd-create-python-app.md

Latest commit

 

History

History
250 lines (183 loc) · 13.8 KB

prd-create-python-app.md

File metadata and controls

250 lines (183 loc) · 13.8 KB
Raw

PRD: create-python-app

A decision-guided scaffolding CLI for Python backends and Python CLI tools

Status: Draft v1 Owner: [you] Last updated: July 2026

1. Problem Statement

Python developers starting a new project face two recurring, well-documented sources of friction:

  1. Framework paralysis for backends. Developers openly describe spending weeks comparing Django vs FastAPI vs Flask before writing a line of business logic, with entire threads dedicated to "which should I learn/use first."
  2. No guided path for CLI tools. Python has at least five viable CLI frameworks (argparse, Click, Typer, Cyclopts, docopt) with no tool that recommends one based on actual project needs — only static comparison articles.

Existing scaffolding tools solve the file generation problem but not the decision problem:

Tool What it does What it's missing
PyScaffold Generates Python packages via flags (--django, --cookiecutter) Flag-driven, not question-driven; no recommendation logic; no CLI-tool path
fastapi-scaffold Generates a FastAPI project with auth/DB/Docker Single framework only; no Django/Flask alternative; no CLI path
Copier / Cookiecutter Template rendering engines Zero opinions — you must already know which template to use
cobra-cli Scaffolds Go CLIs Go only, not Python

The gap: nothing asks "what are you building, who's it for, how will it be used" and recommends a framework/library before scaffolding — the way create-t3-app does for the JS/Next.js ecosystem, backed by visible reasoning rather than a single opinionated stack baked in once.

2. Goals

  • Ship a single CLI (create-python-app or cpa) that scaffolds two distinct kinds of Python projects, chosen via one initial branch:
    1. Backend / API projects
    2. CLI tool projects
  • Replace static "which framework should I use" articles with an interactive, opinionated decision tree.
  • Make every recommendation traceable to a reason (not a black box), so users learn why, not just what.
  • Generate projects that already follow current best practice for Python tooling (2026 baseline: uv-managed, ruff-linted, type-checked, tested, CI-ready) so the user starts from a production-grade baseline, not a toy example.

Non-goals (v1)

  • Not a full low-code app builder — it generates a real, editable codebase, then gets out of the way (same philosophy as create-t3-app: "once you initialize an app, it's yours").
  • Not attempting a hosted/SaaS version yet — v1 is a local, open-source CLI distributed via PyPI.
  • Not supporting non-Python target languages.

3. Users & Use Cases

User Scenario
Solo/hobby developer Wants to spin up a side-project API or script fast without researching frameworks
Junior/early-career developer Doesn't yet have the experience to judge Django vs FastAPI vs Flask tradeoffs
Freelancer / consultant Needs to bootstrap a new client project quickly with sane, current defaults
Small team lead Wants consistent scaffolding conventions across multiple internal tools/services

4. Product Flow

Entry point

$ uvx create-python-app
# or
$ pipx run create-python-app

First question, always:

What are you building?

  1. A backend / API (web service, microservice, data API)
  2. A CLI tool (script, dev tool, internal utility)

Everything below branches from this.

4.1 Path A — Backend / API

Decision questions (in order):

  1. What's the shape of this project?

    • Pure API (no server-rendered pages)
    • Full-stack app (templates, admin panel, forms)
    • Microservice / internal service

  2. Expected scale / context?

    • Hobby / learning project
    • Small team, real users
    • Production, expects real load or ships to customers

  3. Do you need real-time or async-heavy workloads? (WebSockets, streaming, high-concurrency I/O)

    • Yes / No

  4. Do you need an admin panel or content-management out of the box?

    • Yes / No

Recommendation logic (encoded, not hardcoded forever — see §6 on keeping this current):

Answers Recommendation Why (shown to user)
Pure API + async/real-time need FastAPI Async-first, automatic OpenAPI docs, best fit for high-concurrency APIs and ML/service endpoints
Full-stack + admin panel need Django Batteries-included: ORM, auth, admin panel, migrations out of the box — fastest path to a working CRUD app
Hobby / quick script-like service, no admin needed Flask or FastAPI (lite) Minimal, flexible, low ceremony
Microservice, production scale FastAPI Async, lightweight, container-friendly, integrates cleanly with other services

Then branch into supporting choices:

  • Database: PostgreSQL (default for anything beyond hobby), SQLite (hobby/local), leave-empty option
  • ORM: SQLModel or SQLAlchemy 2.0 (FastAPI path), Django ORM (Django path, automatic)
  • Migrations: Alembic (FastAPI path), Django migrations (automatic)
  • Auth: JWT via fastapi-users/Authlib (API-only), Django's built-in auth (full-stack path), or skip
  • Containerization: Docker + uv-based Dockerfile (toggle)
  • CI: GitHub Actions workflow with uv sync --frozen, ruff check, pytest (toggle)

4.2 Path B — CLI Tool

Decision questions (in order):

  1. How complex is the command surface?

    • Single command, a few flags
    • Multiple subcommands (like git commit, git push)
    • Deeply nested command tree

  2. Who is this for?

    • Just me (local script)
    • My team (internal tool)
    • Public distribution (other people will install it)

  3. Do you want type-hint-driven development, or full manual control?

    • Type hints / minimal boilerplate
    • Full manual control, zero dependencies

  4. How will people run it?

    • They already have Python + pip/uv
    • They should NOT need Python installed (standalone binary)

Recommendation logic:

Answers Recommendation Why (shown to user)
Single command, zero deps argparse Standard library, zero install, fine for one-off scripts
Subcommands, public distribution, polish matters Click Mature, nested commands, excellent auto-generated help pages
Type hints preferred, modern DX Typer Type-hint-driven, minimal boilerplate, best editor support
Standalone binary requested Any of the above + PyInstaller or uv single-file build packaging step Solves the "don't make users install Python" distribution problem — the most underserved pain point in this space

Then branch into supporting choices:

  • Packaging: pyproject.toml with [project.scripts] entry point (always)
  • Distribution target: PyPI package, or standalone binary via PyInstaller
  • Testing: Click's CliRunner / Typer's test utilities, scaffolded with example tests
  • Rich output (optional toggle): rich for tables/progress bars/colored output

5. Functional Requirements

  1. CLI must run via uvx create-python-app with zero pre-install step beyond having uv.
  2. Interactive mode (prompts) by default; non-interactive/CI mode via flags (--backend fastapi --db postgres --auth jwt --ci) for scripting and reproducibility — mirrors create-t3-app's --CI flag pattern.
  3. Every recommendation displayed to the user includes a one-line "why" — no silent black-box decisions.
  4. Generated projects must be immediately runnable:
    • Backend: uv sync && uv run <start-command> boots the server.
    • CLI: uv sync && uv run <tool-name> --help shows generated help output.
  5. Generated projects include, by default:
    • pyproject.toml (PEP 621 compliant, uv-managed)
    • ruff config for lint + format
    • Type checker config (see §6)
    • pytest with one working example test
    • .gitignore, README.md with setup instructions
    • GitHub Actions CI workflow (optional toggle, on by default)
  6. Underlying file generation uses Copier (or Cookiecutter) as the template engine — the product's own code should own only the decision tree and prompt flow, not reinvent templating.
  7. Must support re-running to add features later (stretch goal, v2) — inspired by Kirimase's "generate into an existing project" model rather than one-shot only.

6. Tech Stack

6.1 Building the tool itself (bleeding-edge, as of mid-2026)

Concern Choice Why this, now
Packaging / env / distribution uv (Astral) De facto standard as of 2026 — 10–100x faster than pip, single static binary, no Python required to install it, now backed by OpenAI's acquisition of Astral (announced March 2026)
CLI framework (dogfooding) Typer Same framework you'd recommend to modern users; type-hint driven, minimal boilerplate
Interactive prompts Questionary The library Copier itself uses for interactive branching prompts — proven for exactly this use case
Templating engine Copier Actively maintained, supports conditional files/questions natively, more modern than Cookiecutter for versioned template updates
Terminal output Rich Tables, progress bars, colored diagnostics for the "why" explanations
Linting/formatting Ruff (Astral) Already the ecosystem standard; replaced flake8 + black for most new projects
Type checking ty (Astral, beta) or Pyrefly (Meta, stable) ty is 10–100x faster than mypy/Pyright but still beta with ~15% spec conformance; Pyrefly hit stable 1.0 in May 2026 with ~58% conformance. Recommendation: ship with Pyrefly for reliability today, watch ty for a fast-follow once it stabilizes — don't bet the tool's own CI on beta software.
Testing pytest Unchanged industry standard
CI GitHub Actions with astral-sh/setup-uv action (caches uv + deps) Matches what's scaffolded for generated projects — dogfood the same CI pattern
Distribution of the tool itself PyPI package, runnable via uvx create-python-app Zero-install trial, matches how modern Python tools (ruff, ty) are distributed

6.2 What gets scaffolded into generated backend projects

  • FastAPI path: FastAPI + SQLModel (or SQLAlchemy 2.0 if more control is wanted) + Alembic migrations + Pydantic v2 + Uvicorn, optional fastapi-users for auth
  • Django path: Django (current LTS) + Django REST Framework if API-only mode is also selected + built-in ORM/admin/auth
  • Flask path: Flask + Flask-SQLAlchemy, minimal by design
  • All backend paths: uv-based Dockerfile (multi-stage, copies uv.lock for reproducible builds), ruff + type checker config pre-wired

6.3 What gets scaffolded into generated CLI projects

  • Typer or Click or argparse, per the decision tree
  • [project.scripts] entry point wired in pyproject.toml
  • Optional Rich integration for polished output
  • Optional PyInstaller build step for standalone binaries (solves the distribution pain point directly)
  • pytest + framework-appropriate test runner (CliRunner, Typer's CliRunner, or plain subprocess for argparse)

7. Non-Functional Requirements

  • Speed: scaffold generation should complete in under 5 seconds on a warm cache (in line with the uv/ruff-era expectation that tooling is instant).
  • No lock-in: generated code must be fully standard, editable, and have zero runtime dependency on create-python-app itself after generation — same principle create-t3-app states explicitly ("once you initialize an app, it's yours").
  • Transparency: the decision logic (which framework maps to which answers, and why) should live in a human-readable config, not buried in code, so it can be inspected, debated, and updated as the ecosystem shifts.
  • Currency: recommendation defaults should be revisited on a regular cadence (quarterly) against real signal — PyPI download stats, GitHub star velocity — rather than left static like a one-time opinion.

8. MVP Scope (v1) vs. Later

V1 (ship first):

  • CLI tool path only (smaller surface, more clearly underserved niche than backend scaffolding)
  • 3 questions → recommend argparse/Click/Typer → generate with uv, ruff, pytest, packaging
  • Non-interactive flag mode for CI use

V2:

  • Add backend path (FastAPI/Django/Flask) in full
  • Add Docker + CI toggles
  • Add "why" explanations sourced from a versioned, editable rationale file

V3 (stretch):

  • "Generate into existing project" mode (add a new module/route/command to an already-scaffolded project, Kirimase-style)
  • Optional hosted template registry/marketplace layer

9. Success Metrics (for an OSS tool)

  • GitHub stars / adoption velocity in first 90 days post-launch
  • % of users who use non-interactive/CI flags (signal of repeat/scripted use, not just one-off curiosity)
  • Issues/PRs requesting new framework options (signal of engaged usage, same growth pattern create-t3-app saw)
  • Retention proxy: % of generated projects with a subsequent git commit beyond the initial scaffold (would require opt-in telemetry — flag as open question)

10. Open Risks & Honest Caveats

  • Monetization is unclear. Copier/Cookiecutter/PyScaffold are free and mature; this is realistically an open-source community tool first, not a standalone business, unless a hosted registry/marketplace layer is added later.
  • Recommendation logic will age. Framework popularity shifts (e.g., Litestar gaining ground as a FastAPI alternative) — the decision tree needs an owner and a review cadence, not a "set once" mentality.
  • ty vs Pyrefly is still shifting. Revisit this choice before v1 ships; the type-checker landscape moved twice in the last six months alone and may move again.
  • Scope discipline. The biggest failure mode for a tool like this is create-t3-app's own stated trap — "adding everything." Every optional feature must solve a specific, evidenced problem, not just seem nice to have.