Template Customization

Learn how to customize templates to fit your specific needs

Customization Basics

Templates provided by create-awesome-python-app are designed to be customizable. This guide shows how to adapt generated Python projects — from project layout and tooling configuration to dependencies and environment settings.

Project Structure Customization

After scaffolding, reorganize modules to match your domain. Common patterns across CPA templates:

Feature modules

Group routers, services, and schemas by feature (e.g. src/users/, src/billing/).

Shared core

Keep cross-cutting code in src/core/ or packages/common/ for workspace templates.

Settings layout

Centralize configuration with pydantic-settings; extend the generated settings class rather than scattering env reads.

Tests mirror src

Place tests under tests/ mirroring the package layout for easier navigation.

Configuration Customization

Templates ship with uv, Ruff, pytest, and type-checker defaults you can tune:

[project]
name = "my-app"
requires-python = ">=3.12"
dependencies = [
  "fastapi>=0.115",
  "uvicorn[standard]>=0.32",
]

[dependency-groups]
dev = [
  "pytest>=8.0",
  "ruff>=0.8",
  "mypy>=1.13",
]

[tool.uv]
dev-dependencies = []

Adjust Python version bounds, add runtime deps with uv add, and extend dev tooling in [dependency-groups].

Dependency Customization

Manage dependencies with uv after scaffolding:

# Add a runtime dependency
uv add httpx

# Add a dev dependency
uv add --dev pytest-asyncio

# Update the lockfile after manual pyproject edits
uv sync

# Remove a dependency
uv remove unused-package

After adding packages that need app wiring (ORM, Redis, Sentry), follow the extension or template docs for initialization hooks.

Adding Extensions After Project Creation

If you want extensions on an existing project, you can manually port the files from cpa-templates/extensions or re-scaffold with the desired combination:

Manual integration: Copy extension files and merge pyproject.toml fragments, then run uv sync.
Re-scaffold: Create a fresh project with the same template plus extensions, then migrate your application code.
Git branch: Apply extension changes on a branch and merge after review.

Note

The CLI applies extensions at scaffold time only. Post-create extension application may be added in future releases.

Template-Specific Customization

Different CPA templates have distinct extension points:

FastAPI Starter

Routers: Register new routers in the app factory; pair with python-sqlalchemy or python-auth-jwt when needed.
Settings: Extend the generated Settings class for new env vars.
Observability: Add python-sentry during scaffold or wire Sentry manually in lifespan hooks.

# app/main.py (simplified)
from fastapi import FastAPI
from app.api.routes import health, users

app = FastAPI(title="my-app")
app.include_router(health.router, prefix="/health", tags=["health"])
app.include_router(users.router, prefix="/users", tags=["users"])

Advanced Customization

For deeper changes, adjust runtime configuration and deployment artifacts:

Environment Variables

Use .env locally (never commit secrets) and typed settings in code:

# .env.example
APP_ENV=development
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/app
SENTRY_DSN=

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
    app_env: str = "development"
    database_url: str

Docker & Compose

When you scaffold with python-docker, customize Dockerfile, compose.yml, and health checks for your deployment target. Rebuild with docker compose up --build after changes.

Back to Contributing Advanced Usage