fastapi-forge-cli 0.1.0__py3-none-any.whl

fastapi_forge/__init__.py

@@ -0,0 +1,7 @@
+"""FastAPI Forge project generator."""
+
+from fastapi_forge.cli import ForgeError, create_project, project_slug
+
+__version__ = "0.1.0"
+
+__all__ = ["ForgeError", "__version__", "create_project", "project_slug"]

fastapi_forge/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry point for ``python -m fastapi_forge``."""
+
+from fastapi_forge.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fastapi_forge/cli.py

@@ -0,0 +1,211 @@
+"""Command-line interface for FastAPI Forge."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import shutil
+import sys
+import tempfile
+import uuid
+from collections.abc import Iterable
+from importlib import resources
+from pathlib import Path
+
+PACKAGE = "fastapi_forge"
+TEMPLATE_SENTINEL = "__PROJECT_NAME__"
+DATABASE_SENTINEL = "project_name"
+IGNORED_TEMPLATE_NAMES = {
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    "__pycache__",
+}
+EXAMPLES = """Examples:
+  fastapi-forge create "Inventory API" --with-rbac
+  fastapi-forge create "Public API" --without-rbac
+  fastapi-forge create "Billing API" --with-rbac --output-dir ./projects
+  fastapi-forge create "Inventory API" --with-rbac --force
+
+Run 'fastapi-forge create --help' for all project-generation options.
+"""
+
+
+class ForgeError(ValueError):
+    pass
+
+
+def project_slug(value: str) -> str:
+    slug = re.sub(r"[^a-zA-Z0-9_-]+", "-", value.strip()).strip("-_").lower()
+    if not slug:
+        raise ForgeError("Project name must contain a letter or number.")
+    return slug
+
+
+def ask_for_rbac(default: bool = True) -> bool:
+    suffix = "Y/n" if default else "y/N"
+    while True:
+        answer = input(f"Include role-based access control? [{suffix}] ").strip().lower()
+        if not answer:
+            return default
+        if answer in {"y", "yes"}:
+            return True
+        if answer in {"n", "no"}:
+            return False
+        print("Please answer yes or no.")
+
+
+def resolve_rbac(args: argparse.Namespace) -> bool:
+    if args.with_rbac:
+        return True
+    if args.without_rbac:
+        return False
+    return ask_for_rbac() if sys.stdin.isatty() else True
+
+
+def copy_resource_tree(source, destination: Path) -> None:
+    destination.mkdir(parents=True, exist_ok=True)
+    for item in source.iterdir():
+        if item.name in IGNORED_TEMPLATE_NAMES or item.name.endswith((".pyc", ".pyo")):
+            continue
+        target_name = {
+            "_gitignore": ".gitignore",
+            "_dockerignore": ".dockerignore",
+            "_github": ".github",
+        }.get(item.name, item.name)
+        target = destination / target_name
+        if item.is_dir():
+            copy_resource_tree(item, target)
+        else:
+            target.write_bytes(item.read_bytes())
+
+
+def personalize(destination: Path, display_name: str, slug: str) -> None:
+    replacements = {
+        TEMPLATE_SENTINEL: display_name,
+        DATABASE_SENTINEL: slug.replace("-", "_"),
+    }
+    for relative in ("README.md", "sample.env", "app/core/config.py"):
+        path = destination / relative
+        text = path.read_text(encoding="utf-8")
+        for old, new in replacements.items():
+            text = text.replace(old, new)
+        path.write_text(text, encoding="utf-8")
+
+
+def create_project(
+    name: str,
+    output_dir: Path,
+    with_rbac: bool,
+    force: bool = False,
+) -> Path:
+    slug = project_slug(name)
+    parent = output_dir.expanduser().resolve()
+    destination = parent / slug
+
+    if destination.exists():
+        if not force:
+            raise ForgeError(
+                f"Destination already exists: {destination}. Use --force to replace it."
+            )
+        if destination == Path.cwd().resolve():
+            raise ForgeError("Refusing to replace the current working directory.")
+        if destination.is_symlink():
+            raise ForgeError("Refusing to replace a symbolic-link destination.")
+
+    variant = "with_rbac" if with_rbac else "without_rbac"
+    template = resources.files(PACKAGE).joinpath("templates", variant)
+    if not template.is_dir():
+        raise ForgeError(f"Packaged template is missing: {variant}")
+
+    parent.mkdir(parents=True, exist_ok=True)
+    staging = Path(tempfile.mkdtemp(prefix=f".{slug}-", dir=parent))
+    backup: Path | None = None
+    try:
+        copy_resource_tree(template, staging)
+        personalize(staging, name.strip(), slug)
+        if destination.exists():
+            backup = parent / f".{slug}.backup-{uuid.uuid4().hex}"
+            os.replace(destination, backup)
+        os.replace(staging, destination)
+        if backup is not None:
+            shutil.rmtree(backup)
+    except Exception:
+        shutil.rmtree(staging, ignore_errors=True)
+        if backup is not None and backup.exists() and not destination.exists():
+            os.replace(backup, destination)
+        raise
+    return destination
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="fastapi-forge",
+        description="Generate ready-to-run, production-oriented FastAPI projects.",
+        epilog="Run 'fastapi-forge examples' to see common commands.",
+    )
+    parser.add_argument("--version", action="version", version="%(prog)s 0.1.0")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    create = commands.add_parser(
+        "create",
+        help="Create a new FastAPI project.",
+        description="Generate a FastAPI project with PostgreSQL and optional RBAC.",
+        epilog=EXAMPLES,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    create.add_argument(
+        "name",
+        help='Project display name; for example, "Inventory API".',
+    )
+    create.add_argument(
+        "--output-dir",
+        type=Path,
+        default=Path.cwd(),
+        help="Parent directory for the generated project (default: current directory).",
+    )
+    choice = create.add_mutually_exclusive_group()
+    choice.add_argument(
+        "--with-rbac",
+        action="store_true",
+        help="Include roles, permissions, and RBAC administration APIs.",
+    )
+    choice.add_argument(
+        "--without-rbac",
+        action="store_true",
+        help="Use simpler superuser-based administration without RBAC.",
+    )
+    create.add_argument(
+        "--force",
+        action="store_true",
+        help="Replace the matching destination after generating a safe backup.",
+    )
+    commands.add_parser(
+        "examples",
+        help="Show common FastAPI Forge commands.",
+        description="Show copy-ready examples for generating projects.",
+    )
+    return parser
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "examples":
+        print(EXAMPLES)
+        return 0
+
+    try:
+        destination = create_project(
+            name=args.name,
+            output_dir=args.output_dir,
+            with_rbac=resolve_rbac(args),
+            force=args.force,
+        )
+    except ForgeError as exc:
+        parser.error(str(exc))
+
+    print(f"Created project: {destination}")
+    return 0

fastapi_forge/templates/with_rbac/Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.12-slim AS builder
+
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+WORKDIR /build
+COPY requirements.txt .
+RUN python -m venv /opt/venv && /opt/venv/bin/pip install --upgrade pip && \
+    /opt/venv/bin/pip install -r requirements.txt
+
+FROM python:3.12-slim AS runtime
+
+ENV PATH="/opt/venv/bin:$PATH" \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+RUN groupadd --system app && useradd --system --gid app --create-home app
+WORKDIR /app
+COPY --from=builder /opt/venv /opt/venv
+COPY --chown=app:app alembic alembic
+COPY --chown=app:app alembic.ini .
+COPY --chown=app:app app app
+COPY --chown=app:app scripts scripts
+
+USER app
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/api/v1/health/live', timeout=3)"
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2", "--proxy-headers"]
+

fastapi_forge/templates/with_rbac/README.md

@@ -0,0 +1,121 @@
+# __PROJECT_NAME__
+
+A production-oriented FastAPI service with JWT authentication, PostgreSQL, Alembic, persistent audit logs, and role-based access control.
+
+## Included
+
+- Access tokens plus cookie-only rotating refresh tokens, revocation, and sessions
+- Password reset and email verification
+- Hierarchical roles, permissions, and per-user permissions
+- Structured logs, request IDs, CORS, trusted hosts, rate limiting, and security headers
+- Sync and async SQLAlchemy sessions with configurable pools
+- Liveness, readiness, and database health endpoints
+- Alembic migrations and an idempotent RBAC seed command
+- A non-root Docker image, local Compose stack, tests, Ruff, and CI
+
+## Requirements
+
+Python 3.12+, PostgreSQL 14+, and optionally Docker with Compose v2.
+
+## Local setup
+
+Create the PostgreSQL database configured by `.env`, then:
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -r requirements-dev.txt
+cp sample.env .env
+alembic upgrade head
+python scripts/seed_first_user.py \
+  --email admin@example.com \
+  --password 'ChangeMe123!' \
+  --full-name 'System Administrator'
+uvicorn app.main:app --reload
+```
+
+On Windows PowerShell, activate with `.venv\\Scripts\\Activate.ps1`. Development API documentation is at `http://localhost:8000/docs`.
+
+## Docker development
+
+```bash
+cp sample.env .env
+docker compose up --build
+```
+
+Seed the administrator from another terminal:
+
+```bash
+docker compose exec api python scripts/seed_first_user.py \
+  --email admin@example.com \
+  --password 'ChangeMe123!' \
+  --full-name 'System Administrator'
+```
+
+The Compose stack is for development; its credentials and bind mount are not production settings.
+
+## Configuration
+
+| Setting | Purpose |
+| --- | --- |
+| `APP_ENV` | Use `development`, `test`, or `production` |
+| `SECRET_KEY` | JWT signing key; production requires a unique 32+ character value |
+| `PG_*` | PostgreSQL connection and TLS mode |
+| `ALLOWED_HOSTS` | Comma-separated production hostnames |
+| `ALLOWED_ORIGINS` | Comma-separated browser origins |
+| `USE_REDIS`, `REDIS_URL` | Shared rate limits across replicas |
+| `LOG_TO_FILES`, `LOG_DIR` | Optional rotating files; stdout stays enabled |
+| `MAIL_*`, `FRONTEND_URL` | Email delivery and frontend links |
+
+Production startup rejects default/short secrets, wildcard hosts/origins, and non-TLS PostgreSQL modes.
+
+## RBAC
+
+Roles contain permissions and may have a parent; users can also receive permissions directly. Codes follow `resource:action`:
+
+```python
+@router.get(
+    "/reports",
+    dependencies=[Depends(require_permissions("reports:read"))],
+)
+async def list_reports():
+    ...
+```
+
+`require_any_permission(...)` accepts any listed permission. Superusers and tokens containing `*` bypass individual checks. The seed command creates `SUPER ADMIN`, `ADMIN`, and `USER`.
+
+## Endpoints
+
+- `/api/v1/auth`, `/users`, `/roles`, `/permissions`, and `/audit-logs`
+- `/api/v1/health/live`: process liveness
+- `/api/v1/health/ready`: database readiness; returns `503` when unavailable
+
+Docs and OpenAPI are disabled in production.
+
+The refresh token is stored only in a scoped HTTP-only cookie. Call
+`POST /api/v1/auth/refresh` with credentials enabled; it returns a new access token
+and rotates the refresh cookie without exposing that token to browser JavaScript.
+
+## Tests
+
+```bash
+pytest
+ruff check .
+```
+
+## Production checklist
+
+1. Build an immutable image: `docker build -t project-api:1.0.0 .`
+2. Supply secrets externally; configure explicit HTTPS origins and hosts.
+3. Use managed PostgreSQL with verified TLS and Redis for multi-replica rate limits.
+4. Run `alembic upgrade head` once as a release job before new replicas.
+5. Terminate TLS at a trusted proxy and centralize stdout/stderr logs.
+6. Monitor liveness/readiness; test backups, restores, rotation, and rollback.
+
+```bash
+docker run --rm --env-file .env project-api:1.0.0 alembic upgrade head
+docker run --rm --env-file .env -p 8000:8000 project-api:1.0.0
+```
+
+Do not run migrations concurrently from every application replica.

fastapi_forge/templates/with_rbac/_dockerignore

@@ -0,0 +1,16 @@
+.git
+.github
+.env
+.env.*
+.venv
+__pycache__
+*.py[cod]
+.pytest_cache
+.ruff_cache
+.coverage
+htmlcov
+logs
+uploads
+tests
+README.md
+

fastapi_forge/templates/with_rbac/_github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: pip install -r requirements-dev.txt
+      - run: ruff check .
+      - run: pytest
+

fastapi_forge/templates/with_rbac/_gitignore

@@ -0,0 +1,19 @@
+.env
+.env.*
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.idea/
+.vscode/
+uploads/*
+!uploads/.gitkeep
+
+DENTICON_DATA_FLOW.md
+
+
+logs/
+
+fastapi-forge

fastapi_forge/templates/with_rbac/alembic/README

@@ -0,0 +1 @@
+Generate migrations after model changes with: alembic revision --autogenerate -m "describe change"

fastapi_forge/templates/with_rbac/alembic/__init__.py

@@ -0,0 +1 @@
+

fastapi_forge/templates/with_rbac/alembic/env.py

@@ -0,0 +1,51 @@
+from logging.config import fileConfig
+
+from alembic import context
+from app.db.base import Base
+
+from app.core.config import settings
+from app.db.models import *
+
+config = context.config
+config.set_main_option("sqlalchemy.url", settings.postgres_url)
+
+if config.config_file_name:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline():
+    context.configure(
+        url=settings.postgres_url,
+        target_metadata=target_metadata,
+        include_schemas=True,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online():
+    from sqlalchemy import engine_from_config, pool
+
+    connectable = engine_from_config(
+        configuration=config.get_section(config.config_ini_section),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            include_schemas=True,
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

fastapi_forge/templates/with_rbac/alembic/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}