fastapi-spawn 0.1.0__py3-none-any.whl

fastapi_spawn/generator.py

@@ -0,0 +1,294 @@
+"""Core project generation engine for fastapi-spawn."""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+from pathlib import Path
+
+from jinja2 import Environment, PackageLoader, StrictUndefined, TemplateNotFound
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.tree import Tree
+
+from fastapi_spawn.config import ProjectConfig
+from fastapi_spawn.constants import CIProvider, MigrationTool, Stack
+
+console = Console()
+
+
+class ProjectGenerator:
+    """
+    Generates a FastAPI project from Jinja2 templates.
+
+    Final generated structure:
+        <project>/
+        ├── app/
+        │   ├── api/v1/           (health, auth?)
+        │   ├── core/             (config, logging, exceptions, security?, storage?, ai?)
+        │   ├── db/               (session)
+        │   ├── models/
+        │   ├── schemas/
+        │   ├── services/
+        │   └── repositories/
+        ├── tasks/                (celery_app, sample_tasks) — root level
+        ├── migrations/           (alembic env.py + versions/) — when alembic chosen
+        ├── infra/
+        │   ├── docker/
+        │   ├── helm/
+        │   └── terraform/
+        ├── tests/
+        ├── main.py               uv run entry point
+        ├── alembic.ini           when alembic chosen
+        ├── Dockerfile
+        ├── docker-compose.yml
+        ├── .env  .env.example  .gitignore  .pre-commit-config.yaml
+        ├── Makefile
+        └── pyproject.toml
+    """
+
+    def __init__(self, config: ProjectConfig, output_dir: Path) -> None:
+        self.config = config
+        self.output_dir = output_dir
+        self.ctx = config.to_context()
+        self._env = Environment(
+            loader=PackageLoader("fastapi_spawn", "templates"),
+            undefined=StrictUndefined,
+            keep_trailing_newline=True,
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+    # ── Public API ──────────────────────────────────────────────────────────
+
+    def generate(self) -> Path:
+        if self.config.dry_run:
+            self._dry_run_display()
+            return self.output_dir / self.config.project_name
+
+        project_path = self.output_dir / self.config.project_name
+
+        if project_path.exists() and self.config.force:
+            shutil.rmtree(project_path)
+
+        with tempfile.TemporaryDirectory() as staging_root:
+            staging = Path(staging_root) / self.config.project_name
+            staging.mkdir(parents=True)
+
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[bold cyan]{task.description}"),
+                transient=True,
+                console=console,
+            ) as progress:
+                task = progress.add_task("Writing root files...", total=None)
+
+                self._generate_root(staging)
+
+                progress.update(task, description="Writing app/ module...")
+                self._generate_app(staging)
+
+                if self.config.has_broker:
+                    progress.update(task, description="Writing tasks/...")
+                    self._generate_tasks(staging)
+
+                if self.config.has_alembic:
+                    progress.update(task, description="Writing Alembic migrations/...")
+                    self._generate_alembic(staging)
+
+                if self.config.include_tests:
+                    progress.update(task, description="Writing tests/...")
+                    self._generate_tests(staging)
+
+                if self.config.has_docker:
+                    progress.update(task, description="Writing Docker files...")
+                    self._generate_docker(staging)
+
+                if self.config.has_infra or self.config.stack == Stack.full:
+                    progress.update(task, description="Writing infra/...")
+                    self._generate_infra(staging)
+
+                if self.config.has_ci:
+                    progress.update(task, description="Writing CI/CD workflows...")
+                    self._generate_ci(staging)
+
+                if self.config.include_makefile:
+                    self._render_to(staging / "Makefile", "base/Makefile.j2")
+
+            shutil.copytree(str(staging), str(project_path))
+
+        return project_path
+
+    # ── Section generators ──────────────────────────────────────────────────
+
+    def _generate_root(self, root: Path) -> None:
+        self._render_to(root / "main.py", "root/main.py.j2")
+        self._render_to(root / "pyproject.toml", "base/pyproject.toml.j2")
+        self._render_to(root / ".env", "base/env.j2")
+        self._render_to(root / ".env.example", "base/env_example.j2")
+        self._render_to(root / ".gitignore", "base/gitignore.j2")
+        self._render_to(root / ".pre-commit-config.yaml", "base/pre_commit.j2")
+        self._render_to(root / "README.md", "base/README.md.j2")
+
+    def _generate_app(self, root: Path) -> None:
+        pkg = root / "app"
+        pkg.mkdir()
+        self._render_to(pkg / "__init__.py", "app/__init__.py.j2")
+        self._render_to(pkg / "main.py", "app/main.py.j2")
+
+        # core/
+        core = pkg / "core"
+        core.mkdir()
+        self._render_to(core / "__init__.py", "app/__init__.py.j2")
+        self._render_to(core / "config.py", "app/core/config.py.j2")
+        self._render_to(core / "logging.py", "app/core/logging.py.j2")
+        self._render_to(core / "exceptions.py", "app/core/exceptions.py.j2")
+        if self.config.has_auth:
+            self._render_to(core / "security.py", "app/core/security.py.j2")
+        if self.config.has_s3:
+            self._render_to(core / "storage.py", "app/core/storage.py.j2")
+        if self.config.has_ai:
+            self._render_to(core / "ai.py", "app/core/ai.py.j2")
+
+        # api/
+        api = pkg / "api"
+        api.mkdir()
+        self._render_to(api / "__init__.py", "app/__init__.py.j2")
+        self._render_to(api / "deps.py", "app/api/deps.py.j2")
+        v1 = api / "v1"
+        v1.mkdir()
+        self._render_to(v1 / "__init__.py", "app/__init__.py.j2")
+        self._render_to(v1 / "health.py", "app/api/v1/health.py.j2")
+        if self.config.has_auth:
+            self._render_to(v1 / "auth.py", "app/api/v1/auth.py.j2")
+
+        # db/ (only when a real database is chosen)
+        if self.config.db.value != "none":
+            db_dir = pkg / "db"
+            db_dir.mkdir()
+            self._render_to(db_dir / "__init__.py", "app/__init__.py.j2")
+            self._render_to(db_dir / "session.py", "app/db/session.py.j2")
+
+        # models/, schemas/, services/, repositories/
+        for sub in ("models", "schemas", "services", "repositories"):
+            d = pkg / sub
+            d.mkdir()
+            self._render_to(d / "__init__.py", "app/__init__.py.j2")
+
+    def _generate_tasks(self, root: Path) -> None:
+        """Root-level tasks/ directory."""
+        tasks = root / "tasks"
+        tasks.mkdir()
+        self._render_to(tasks / "__init__.py", "app/__init__.py.j2")
+        self._render_to(tasks / "celery_app.py", "tasks/celery_app.py.j2")
+        self._render_to(tasks / "sample_tasks.py", "tasks/sample_tasks.py.j2")
+
+    def _generate_alembic(self, root: Path) -> None:
+        """Alembic migration setup at project root."""
+        self._render_to(root / "alembic.ini", "alembic/alembic.ini.j2")
+        migrations = root / "migrations"
+        migrations.mkdir()
+        (migrations / "versions").mkdir()
+        self._render_to(migrations / "env.py", "alembic/env.py.j2")
+        self._render_to(migrations / "__init__.py", "app/__init__.py.j2")
+
+    def _generate_tests(self, root: Path) -> None:
+        tests = root / "tests"
+        tests.mkdir()
+        self._render_to(tests / "__init__.py", "app/__init__.py.j2")
+        self._render_to(tests / "conftest.py", "tests/conftest.py.j2")
+        self._render_to(tests / "test_health.py", "tests/test_health.py.j2")
+
+    def _generate_docker(self, root: Path) -> None:
+        self._render_to(root / "Dockerfile", "docker/Dockerfile.j2")
+        self._render_to(root / "docker-compose.yml", "docker/docker-compose.yml.j2")
+        self._render_to(root / ".dockerignore", "docker/dockerignore.j2")
+
+    def _generate_ci(self, root: Path) -> None:
+        ci = self.config.ci
+        if ci in (CIProvider.github, CIProvider.both):
+            gha = root / ".github" / "workflows"
+            gha.mkdir(parents=True)
+            self._render_to(gha / "tests.yml", "ci/github/tests.yml.j2")
+            self._render_to(gha / "publish.yml", "ci/github/publish.yml.j2")
+        if ci in (CIProvider.gitlab, CIProvider.both):
+            self._render_to(root / ".gitlab-ci.yml", "ci/gitlab/gitlab-ci.yml.j2")
+
+    def _generate_infra(self, root: Path) -> None:
+        infra = root / "infra"
+        (infra / "docker").mkdir(parents=True)
+        self._render_to(infra / "docker" / "docker-compose.prod.yml", "infra/docker/docker-compose.prod.yml.j2")
+        helm = infra / "helm"
+        helm.mkdir()
+        self._render_to(helm / "Chart.yaml", "infra/helm/Chart.yaml.j2")
+        self._render_to(helm / "values.yaml", "infra/helm/values.yaml.j2")
+        tf = infra / "terraform"
+        tf.mkdir()
+        self._render_to(tf / "main.tf", "infra/terraform/main.tf.j2")
+        self._render_to(tf / "variables.tf", "infra/terraform/variables.tf.j2")
+
+    # ── Render helper ───────────────────────────────────────────────────────
+
+    def _render_to(self, dest: Path, template_name: str) -> None:
+        try:
+            tmpl = self._env.get_template(template_name)
+        except TemplateNotFound:
+            return
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(tmpl.render(**self.ctx), encoding="utf-8")
+
+    # ── Dry-run display ─────────────────────────────────────────────────────
+
+    def _dry_run_display(self) -> None:
+        cfg = self.config
+        tree = Tree(
+            f":open_file_folder: [bold green]{cfg.project_name}/[/bold green]",
+            guide_style="dim",
+        )
+
+        app = tree.add("[bold blue]app/[/bold blue]")
+        app.add("__init__.py  main.py")
+        core_items = "config.py  logging.py  exceptions.py"
+        if cfg.has_auth:       core_items += "  security.py"
+        if cfg.has_s3:         core_items += "  storage.py"
+        if cfg.has_ai:         core_items += "  ai.py"
+        app.add(f"[blue]core/[/blue]  {core_items}")
+        api = app.add("[blue]api/[/blue]  deps.py")
+        v1 = "health.py" + ("  auth.py" if cfg.has_auth else "")
+        api.add(f"[blue]v1/[/blue]  {v1}")
+        if cfg.db.value != "none":
+            app.add("[blue]db/[/blue]  session.py")
+        for sub in ("models/", "schemas/", "services/", "repositories/"):
+            app.add(sub)
+
+        if cfg.has_broker:
+            t = tree.add("[blue]tasks/[/blue]")
+            t.add("celery_app.py  sample_tasks.py")
+
+        if cfg.has_alembic:
+            m = tree.add("[blue]migrations/[/blue]")
+            m.add("env.py  [dim]versions/[/dim]")
+            tree.add("alembic.ini")
+
+        if cfg.include_tests:
+            t = tree.add("[blue]tests/[/blue]")
+            t.add("conftest.py  test_health.py")
+
+        if cfg.has_infra or cfg.stack == Stack.full:
+            infra = tree.add("[blue]infra/[/blue]")
+            infra.add("[blue]docker/[/blue]  docker-compose.prod.yml")
+            infra.add("[blue]helm/[/blue]  Chart.yaml  values.yaml")
+            infra.add("[blue]terraform/[/blue]  main.tf  variables.tf")
+
+        if cfg.has_ci and cfg.ci in (CIProvider.github, CIProvider.both):
+            ci = tree.add("[blue].github/workflows/[/blue]")
+            ci.add("tests.yml  publish.yml")
+
+        root_files = "main.py  pyproject.toml  .env  .env.example  .gitignore  .pre-commit-config.yaml  README.md"
+        if cfg.has_docker:
+            root_files += "  Dockerfile  docker-compose.yml  .dockerignore"
+        if cfg.include_makefile:
+            root_files += "  Makefile"
+        tree.add(root_files)
+
+        console.print(tree)

fastapi_spawn/interactive.py

@@ -0,0 +1,192 @@
+"""Interactive TUI prompts using questionary."""
+
+from __future__ import annotations
+
+import questionary
+from questionary import Style
+
+from fastapi_spawn.constants import (
+    AUTH_LABELS,
+    BROKER_LABELS,
+    DB_LABELS,
+    STACK_DESCRIPTIONS,
+    AuthType,
+    Broker,
+    Cache,
+    CIProvider,
+    Database,
+    LogLibrary,
+    ORM,
+    ORM_DB_COMPAT,
+    Stack,
+)
+from fastapi_spawn.validators import questionary_validator, validate_project_name
+
+SPAWN_STYLE = Style(
+    [
+        ("qmark", "fg:#7c3aed bold"),
+        ("question", "bold"),
+        ("answer", "fg:#22d3ee bold"),
+        ("pointer", "fg:#7c3aed bold"),
+        ("highlighted", "fg:#7c3aed bold"),
+        ("selected", "fg:#22d3ee"),
+        ("separator", "fg:#6b7280"),
+        ("instruction", "fg:#6b7280"),
+    ]
+)
+
+
+def prompt_project_name(default: str = "") -> str:
+    return questionary.text(
+        "Project name:",
+        default=default,
+        validate=questionary_validator(validate_project_name),
+        style=SPAWN_STYLE,
+    ).unsafe_ask()
+
+
+def prompt_database() -> Database:
+    choices = [
+        questionary.Choice(title=label, value=db)
+        for db, label in DB_LABELS.items()
+    ]
+    return questionary.select(
+        "Database backend:",
+        choices=choices,
+        style=SPAWN_STYLE,
+    ).unsafe_ask()
+
+
+def prompt_orm(db: Database) -> ORM:
+    compatible = ORM_DB_COMPAT.get(ORM.none, [])
+    valid_orms = [
+        orm for orm in ORM
+        if db in ORM_DB_COMPAT.get(orm, []) or orm == ORM.none
+    ]
+    # Filter ORMs truly compatible with the chosen DB
+    valid_orms = [
+        orm for orm in ORM
+        if db in ORM_DB_COMPAT.get(orm, compatible)
+    ]
+    choices = [questionary.Choice(title=o.value, value=o) for o in valid_orms]
+    if not choices:
+        return ORM.none
+    return questionary.select(
+        "ORM / ODM:",
+        choices=choices,
+        style=SPAWN_STYLE,
+    ).unsafe_ask()
+
+
+def prompt_auth() -> AuthType:
+    choices = [
+        questionary.Choice(title=label, value=auth)
+        for auth, label in AUTH_LABELS.items()
+    ]
+    return questionary.select(
+        "Authentication strategy:",
+        choices=choices,
+        style=SPAWN_STYLE,
+    ).unsafe_ask()
+
+
+def prompt_broker() -> Broker:
+    choices = [
+        questionary.Choice(title=label, value=broker)
+        for broker, label in BROKER_LABELS.items()
+    ]
+    return questionary.select(
+        "Message broker:",
+        choices=choices,
+        style=SPAWN_STYLE,
+    ).unsafe_ask()
+
+
+def prompt_cache() -> Cache:
+    choices = [
+        questionary.Choice(title=c.value, value=c)
+        for c in Cache
+    ]
+    return questionary.select(
+        "Cache layer:",
+        choices=choices,
+        style=SPAWN_STYLE,
+    ).unsafe_ask()
+
+
+def prompt_stack() -> Stack:
+    choices = [
+        questionary.Choice(title=f"{s.value}  —  {STACK_DESCRIPTIONS[s]}", value=s)
+        for s in Stack
+    ]
+    return questionary.select(
+        "Deployment stack:",
+        choices=choices,
+        style=SPAWN_STYLE,
+    ).unsafe_ask()
+
+
+def prompt_ci() -> CIProvider:
+    choices = [
+        questionary.Choice(title=c.value, value=c)
+        for c in CIProvider
+    ]
+    return questionary.select(
+        "CI/CD provider:",
+        choices=choices,
+        style=SPAWN_STYLE,
+    ).unsafe_ask()
+
+
+def prompt_log_lib() -> LogLibrary:
+    choices = [
+        questionary.Choice(title=l.value, value=l)
+        for l in LogLibrary
+    ]
+    return questionary.select(
+        "Logging library:",
+        choices=choices,
+        style=SPAWN_STYLE,
+    ).unsafe_ask()
+
+
+def prompt_flags() -> tuple[bool, bool]:
+    """Returns (include_docker, include_tests)."""
+    include_docker = questionary.confirm(
+        "Include Docker files?", default=True, style=SPAWN_STYLE
+    ).unsafe_ask()
+    include_tests = questionary.confirm(
+        "Include test suite?", default=True, style=SPAWN_STYLE
+    ).unsafe_ask()
+    return include_docker, include_tests
+
+
+def run_interactive_flow(project_name: str = "") -> dict:
+    """
+    Run the full interactive TUI and return a dict of selected options
+    suitable for passing to ProjectConfig.
+    """
+    name = prompt_project_name(project_name)
+    db = prompt_database()
+    orm = prompt_orm(db)
+    auth = prompt_auth()
+    broker = prompt_broker()
+    cache = prompt_cache()
+    stack = prompt_stack()
+    ci = prompt_ci()
+    log_lib = prompt_log_lib()
+    include_docker, include_tests = prompt_flags()
+
+    return {
+        "project_name": name,
+        "db": db,
+        "orm": orm,
+        "auth": auth,
+        "broker": broker,
+        "cache": cache,
+        "stack": stack,
+        "ci": ci,
+        "log_lib": log_lib,
+        "include_docker": include_docker,
+        "include_tests": include_tests,
+    }

fastapi_spawn/templates/alembic/alembic.ini.j2

@@ -0,0 +1,39 @@
+[alembic]
+script_location = migrations
+prepend_sys_path = .
+version_path_separator = os
+sqlalchemy.url =
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

fastapi_spawn/templates/alembic/env.py.j2

@@ -0,0 +1,64 @@
+"""Alembic environment configuration."""
+
+from __future__ import annotations
+
+import asyncio
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from app.core.config import settings
+from app.db.session import Base
+
+# Import all models so Alembic picks them up for autogenerate
+# from app.models import user  # noqa: F401
+
+config = context.config
+config.set_main_option("sqlalchemy.url", settings.database_url)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    context.configure(connection=connection, target_metadata=target_metadata)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

fastapi_spawn/templates/app/__init__.py.j2

@@ -0,0 +1 @@
+"""Empty __init__.py"""

fastapi_spawn/templates/app/api/deps.py.j2

@@ -0,0 +1,39 @@
+"""FastAPI dependency injection."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+{% if has_relational_db and orm == "sqlalchemy" %}
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.session import get_session
+
+DBSession = Annotated[AsyncSession, Depends(get_session)]
+{% endif %}
+{% if has_auth %}
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+
+from app.core.security import decode_token
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
+
+
+async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]) -> dict:
+    """Decode JWT and return the payload. Raise 401 on failure."""
+    try:
+        payload = decode_token(token)
+        return payload
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=str(exc),
+            headers={"WWW-Authenticate": "Bearer"},
+        ) from exc
+
+
+CurrentUser = Annotated[dict, Depends(get_current_user)]
+{% else %}
+from fastapi import Depends
+{% endif %}

fastapi_spawn/templates/app/api/v1/auth.py.j2

@@ -0,0 +1,59 @@
+"""Auth endpoints."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordRequestForm
+from pydantic import BaseModel
+from typing import Annotated
+
+from app.core.security import create_access_token, create_refresh_token
+
+router = APIRouter(prefix="/auth")
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+
+
+@router.post("/login", response_model=TokenResponse, summary="Obtain access token")
+async def login(
+    form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
+) -> TokenResponse:
+    """
+    Exchange username + password for JWT tokens.
+    Replace the stub validation below with real user lookup.
+    """
+    # TODO: Replace with real user lookup from DB
+    if form_data.username != "admin" or form_data.password != "secret":
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect username or password.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return TokenResponse(
+        access_token=create_access_token(subject=form_data.username),
+        refresh_token=create_refresh_token(subject=form_data.username),
+    )
+
+
+@router.post("/refresh", response_model=TokenResponse, summary="Refresh access token")
+async def refresh(refresh_token: str) -> TokenResponse:
+    """Exchange a valid refresh token for a new access token."""
+    from app.core.security import decode_token
+    try:
+        payload = decode_token(refresh_token)
+        if payload.get("type") != "refresh":
+            raise ValueError("Not a refresh token.")
+        subject = payload["sub"]
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=str(exc),
+        ) from exc
+    return TokenResponse(
+        access_token=create_access_token(subject=subject),
+        refresh_token=create_refresh_token(subject=subject),
+    )