fastapi-spawn 0.1.0__py3-none-any.whl

fastapi_spawn/templates/infra/docker/docker-compose.prod.yml.j2

@@ -0,0 +1,43 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ slug }}
+  labels:
+    app: {{ slug }}
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: {{ slug }}
+  template:
+    metadata:
+      labels:
+        app: {{ slug }}
+    spec:
+      containers:
+        - name: {{ slug }}
+          image: ghcr.io/your-org/{{ slug }}:latest
+          ports:
+            - containerPort: 8000
+          envFrom:
+            - secretRef:
+                name: {{ slug }}-secrets
+          livenessProbe:
+            httpGet:
+              path: /api/v1/health/liveness
+              port: 8000
+            initialDelaySeconds: 15
+            periodSeconds: 20
+          readinessProbe:
+            httpGet:
+              path: /api/v1/health/readiness
+              port: 8000
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          resources:
+            requests:
+              memory: "128Mi"
+              cpu: "100m"
+            limits:
+              memory: "512Mi"
+              cpu: "500m"

fastapi_spawn/templates/infra/helm/Chart.yaml.j2

@@ -0,0 +1,6 @@
+apiVersion: v2
+name: {{ slug }}
+description: Helm chart for {{ project_name }}
+type: application
+version: 0.1.0
+appVersion: "0.1.0"

fastapi_spawn/templates/infra/helm/values.yaml.j2

@@ -0,0 +1,26 @@
+replicaCount: 2
+
+image:
+  repository: ghcr.io/your-org/{{ slug }}
+  tag: latest
+  pullPolicy: IfNotPresent
+
+service:
+  type: ClusterIP
+  port: 8000
+
+ingress:
+  enabled: false
+  host: {{ slug }}.example.com
+
+env:
+  APP_ENV: production
+  DEBUG: "false"
+
+resources:
+  requests:
+    memory: "128Mi"
+    cpu: "100m"
+  limits:
+    memory: "512Mi"
+    cpu: "500m"

fastapi_spawn/templates/infra/terraform/main.tf.j2

@@ -0,0 +1,26 @@
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+  }
+}
+
+provider "aws" {
+  region = var.aws_region
+}
+
+# ECR repository
+resource "aws_ecr_repository" "app" {
+  name                 = "{{ slug }}"
+  image_tag_mutability = "MUTABLE"
+  image_scanning_configuration {
+    scan_on_push = true
+  }
+}
+
+# ECS Cluster
+resource "aws_ecs_cluster" "main" {
+  name = "{{ slug }}-cluster"
+}

fastapi_spawn/templates/infra/terraform/variables.tf.j2

@@ -0,0 +1,17 @@
+variable "aws_region" {
+  description = "AWS region to deploy to"
+  type        = string
+  default     = "us-east-1"
+}
+
+variable "app_name" {
+  description = "Application name"
+  type        = string
+  default     = "{{ slug }}"
+}
+
+variable "container_port" {
+  description = "Port the container listens on"
+  type        = number
+  default     = 8000
+}

fastapi_spawn/templates/root/main.py.j2

@@ -0,0 +1,16 @@
+"""Entry point for {{ project_name }}.
+
+Run with:  uv run main.py
+Or:        uvicorn app.main:app --reload
+"""
+
+import uvicorn
+
+if __name__ == "__main__":
+    uvicorn.run(
+        "app.main:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=True,
+        log_level="info",
+    )

fastapi_spawn/templates/tasks/celery_app.py.j2

@@ -0,0 +1,37 @@
+"""Celery application factory for {{ project_name }}."""
+
+from __future__ import annotations
+
+from celery import Celery
+
+from app.core.config import settings
+
+{% if broker == "redis" %}
+celery_app = Celery(
+    "{{ slug }}",
+    broker=settings.REDIS_URL,
+    backend=settings.REDIS_URL,
+)
+{% elif broker == "rabbitmq" %}
+celery_app = Celery(
+    "{{ slug }}",
+    broker=settings.RABBITMQ_URL,
+    backend="rpc://",
+)
+{% else %}
+celery_app = Celery("{{ slug }}")
+{% endif %}
+
+celery_app.conf.update(
+    task_serializer="json",
+    result_serializer="json",
+    accept_content=["json"],
+    timezone="UTC",
+    enable_utc=True,
+    task_track_started=True,
+    worker_prefetch_multiplier=1,
+    task_acks_late=True,
+)
+
+# Auto-discover tasks in the tasks/ package
+celery_app.autodiscover_tasks(["tasks"])

fastapi_spawn/templates/tasks/sample_tasks.py.j2

@@ -0,0 +1,27 @@
+"""Sample Celery tasks for {{ project_name }}."""
+
+from __future__ import annotations
+
+import time
+
+from tasks.celery_app import celery_app
+
+
+@celery_app.task(bind=True, name="tasks.sample.add", max_retries=3)
+def add(self, x: int, y: int) -> int:
+    """Simple addition task — use as a template."""
+    return x + y
+
+
+@celery_app.task(bind=True, name="tasks.sample.slow_task", max_retries=3)
+def slow_task(self, seconds: int = 5) -> str:
+    """Simulate a long-running task."""
+    time.sleep(seconds)
+    return f"Completed after {seconds}s"
+
+
+@celery_app.task(bind=True, name="tasks.sample.send_email", max_retries=3)
+def send_email(self, to: str, subject: str, body: str) -> dict:
+    """Stub email sending task. Replace with real email logic."""
+    # TODO: integrate with SendGrid / SES / SMTP
+    return {"status": "sent", "to": to, "subject": subject}

fastapi_spawn/templates/tests/conftest.py.j2

@@ -0,0 +1,22 @@
+"""pytest configuration and fixtures for {{ project_name }}."""
+
+from __future__ import annotations
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+
+from app.main import app
+
+
+@pytest.fixture(scope="session")
+def anyio_backend() -> str:
+    return "asyncio"
+
+
+@pytest.fixture
+async def client() -> AsyncClient:  # type: ignore[return]
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://testserver",
+    ) as ac:
+        yield ac

fastapi_spawn/templates/tests/test_health.py.j2

@@ -0,0 +1,30 @@
+"""Health endpoint tests for {{ project_name }}."""
+
+from __future__ import annotations
+
+import pytest
+from httpx import AsyncClient
+
+
+@pytest.mark.anyio
+async def test_health_ok(client: AsyncClient) -> None:
+    response = await client.get("/api/v1/health")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["status"] == "ok"
+    assert "uptime_seconds" in data
+    assert data["service"] == "{{ project_name }}"
+
+
+@pytest.mark.anyio
+async def test_readiness(client: AsyncClient) -> None:
+    response = await client.get("/api/v1/health/readiness")
+    assert response.status_code == 200
+    assert response.json() == {"status": "ready"}
+
+
+@pytest.mark.anyio
+async def test_liveness(client: AsyncClient) -> None:
+    response = await client.get("/api/v1/health/liveness")
+    assert response.status_code == 200
+    assert response.json() == {"status": "alive"}

fastapi_spawn/utils.py

@@ -0,0 +1,58 @@
+"""Utility helpers for fastapi-spawn."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+def to_snake_case(name: str) -> str:
+    """Convert a string to snake_case."""
+    s = re.sub(r"[-\s]+", "_", name)
+    s = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", s)
+    s = re.sub(r"([a-z\d])([A-Z])", r"\1_\2", s)
+    return s.lower()
+
+
+def to_pascal_case(name: str) -> str:
+    """Convert a snake_case or kebab-case string to PascalCase."""
+    return "".join(word.capitalize() for word in re.split(r"[-_\s]+", name))
+
+
+def to_kebab_case(name: str) -> str:
+    """Convert a string to kebab-case."""
+    s = re.sub(r"[_\s]+", "-", name)
+    s = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1-\2", s)
+    s = re.sub(r"([a-z\d])([A-Z])", r"\1-\2", s)
+    return s.lower()
+
+
+def render_tree(root: Path, prefix: str = "") -> str:
+    """
+    Recursively render a directory tree as a Rich-compatible string.
+    Used in --dry-run mode.
+    """
+    lines: list[str] = []
+    try:
+        items = sorted(root.iterdir(), key=lambda p: (p.is_file(), p.name))
+    except PermissionError:
+        return ""
+    for i, item in enumerate(items):
+        connector = "└── " if i == len(items) - 1 else "├── "
+        lines.append(prefix + connector + item.name)
+        if item.is_dir():
+            extension = "    " if i == len(items) - 1 else "│   "
+            lines.append(render_tree(item, prefix + extension))
+    return "\n".join(filter(None, lines))
+
+
+def collect_dry_run_paths(root: Path) -> list[str]:
+    """
+    Walk a directory and return all relative file paths as strings.
+    Used by the generator in dry-run mode.
+    """
+    paths = []
+    for path in sorted(root.rglob("*")):
+        if path.is_file():
+            paths.append(str(path.relative_to(root)))
+    return paths

fastapi_spawn/validators.py

@@ -0,0 +1,67 @@
+"""Input validators for fastapi-spawn."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from fastapi_spawn.constants import ORM, ORM_DB_COMPAT, Database
+
+
+def validate_project_name(name: str) -> str:
+    """
+    Validate that a project name is a valid Python package identifier
+    (allows hyphens which are converted to underscores).
+    Returns the cleaned name or raises ValueError.
+    """
+    cleaned = name.strip()
+    if not cleaned:
+        raise ValueError("Project name cannot be empty.")
+    if not re.match(r"^[a-zA-Z][a-zA-Z0-9_-]*$", cleaned):
+        raise ValueError(
+            f"Invalid project name '{cleaned}'. "
+            "Use letters, numbers, hyphens, or underscores. Must start with a letter."
+        )
+    if len(cleaned) > 64:
+        raise ValueError("Project name must be 64 characters or fewer.")
+    return cleaned
+
+
+def validate_orm_db_compat(orm: ORM, db: Database) -> None:
+    """
+    Raise ValueError if the selected ORM is not compatible with the selected DB.
+    """
+    compatible_dbs = ORM_DB_COMPAT.get(orm, [])
+    if db not in compatible_dbs:
+        compat_str = ", ".join(d.value for d in compatible_dbs)
+        raise ValueError(
+            f"ORM '{orm.value}' is not compatible with database '{db.value}'. "
+            f"Compatible databases: {compat_str}"
+        )
+
+
+def validate_output_dir(path: Path, force: bool) -> None:
+    """
+    Validate that the output directory can be safely created.
+    Raises ValueError if the directory exists and --force was not passed.
+    """
+    if path.exists() and not force:
+        raise ValueError(
+            f"Directory '{path}' already exists. Use --force to overwrite."
+        )
+
+
+def questionary_validator(validate_fn):  # type: ignore[no-untyped-def]
+    """
+    Wrap a validation function for use as a questionary validator.
+    Returns a callable that returns True on success or an error string on failure.
+    """
+
+    def _inner(val: str):  # type: ignore[no-untyped-def]
+        try:
+            validate_fn(val)
+            return True
+        except ValueError as exc:
+            return str(exc)
+
+    return _inner

fastapi_spawn-0.1.0.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: fastapi-spawn
+Version: 0.1.0
+Summary: A powerful CLI tool to scaffold production-ready FastAPI projects with flexible database, auth, broker, and deployment options.
+Project-URL: Homepage, https://github.com/Bishwajitgarai/fastapi-spawn
+Project-URL: Documentation, https://github.com/Bishwajitgarai/fastapi-spawn#readme
+Project-URL: Repository, https://github.com/Bishwajitgarai/fastapi-spawn
+Project-URL: Bug Tracker, https://github.com/Bishwajitgarai/fastapi-spawn/issues
+Project-URL: Changelog, https://github.com/Bishwajitgarai/fastapi-spawn/blob/main/CHANGELOG.md
+Author-email: Bishwajit Garai <bishwajitgarai@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: boilerplate,cli,devtools,docker,fastapi,generator,jwt,project-generator,python,scaffold,sqlalchemy,template
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: jinja2>=3.1.4
+Requires-Dist: questionary>=2.0.1
+Requires-Dist: rich>=13.7.0
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# ⚡ fastapi-spawn
+
+**The most complete FastAPI project scaffolding CLI — built for modern Python development.**
+
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-spawn.svg?color=cyan&style=flat-square)](https://pypi.org/project/fastapi-spawn/)
+[![Python](https://img.shields.io/pypi/pyversions/fastapi-spawn.svg?style=flat-square)](https://pypi.org/project/fastapi-spawn/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/Bishwajitgarai/fastapi-spawn/tests.yml?label=tests&style=flat-square)](https://github.com/Bishwajitgarai/fastapi-spawn/actions)
+
+</div>
+
+---
+
+## Why fastapi-spawn?
+
+`fastapi-spawn` generates **production-ready** FastAPI projects in seconds. No boilerplate, no guesswork — just run one command and get a fully structured, configured project with the exact stack you need.
+
+| Feature | scaffold-fastapi | **fastapi-spawn** |
+|---|---|---|
+| Interactive TUI | Basic prompts | ✅ Rich questionary TUI |
+| Databases | PostgreSQL, MongoDB, SQLite | ✅ + MySQL |
+| ORM | None | ✅ SQLAlchemy 2.x, Tortoise, Beanie |
+| Migrations | ❌ | ✅ Alembic (async), Aerich |
+| Auth | ❌ | ✅ JWT, OAuth2, API Key |
+| Message brokers | Redis, RabbitMQ | ✅ + Kafka |
+| File storage | ❌ | ✅ AWS S3 (boto3) |
+| AI integration | ❌ | ✅ OpenAI, Anthropic |
+| Config style | Single URL | ✅ Individual fields + `@property` URL |
+| Entry point | app/main.py | ✅ Root `main.py` (`uv run main.py`) |
+| CI/CD | GitHub Actions | ✅ GitHub Actions + GitLab CI |
+| Observability | ❌ | ✅ /health /readiness /liveness |
+| Logging | None | ✅ loguru / structlog / standard |
+| Package manager | uv | ✅ uv (with `[tool.uv]` config) |
+| Dry-run mode | ❌ | ✅ Preview tree before generating |
+
+---
+
+## Installation
+
+```bash
+pip install fastapi-spawn
+# or
+uv pip install fastapi-spawn
+```
+
+---
+
+## Quick Start
+
+```bash
+# Fully interactive — guided TUI
+fastapi-spawn new my-api
+
+# One-liner (all flags)
+fastapi-spawn new my-api \
+  --db postgresql \
+  --orm sqlalchemy \
+  --migration alembic \
+  --auth jwt \
+  --broker redis \
+  --storage s3 \
+  --ai openai \
+  --stack full \
+  --ci github \
+  --log-lib loguru
+
+# Preview without writing files
+fastapi-spawn new my-api --dry-run
+```
+
+---
+
+## Generated Project Structure
+
+```
+my-api/
+├── app/
+│   ├── api/
+│   │   └── v1/
+│   │       ├── health.py        # /health  /readiness  /liveness
+│   │       └── auth.py          # JWT login + refresh
+│   ├── core/
+│   │   ├── config.py            # Pydantic Settings v2 (individual env fields)
+│   │   ├── logging.py           # loguru / structlog / standard
+│   │   ├── exceptions.py        # Custom exception hierarchy
+│   │   ├── security.py          # JWT + bcrypt (when auth enabled)
+│   │   ├── storage.py           # AWS S3 utils (when s3 chosen)
+│   │   └── ai.py                # OpenAI / Anthropic client (when AI chosen)
+│   ├── db/
+│   │   └── session.py           # Async SQLAlchemy / Tortoise / Beanie
+│   ├── models/                  # ORM models
+│   ├── schemas/                 # Pydantic schemas
+│   ├── services/                # Business logic layer
+│   └── repositories/            # Data access layer
+├── tasks/                       # Celery workers (root-level)
+│   ├── celery_app.py
+│   └── sample_tasks.py
+├── migrations/                  # Alembic migrations
+│   ├── env.py                   # Async-compatible env
+│   └── versions/
+├── infra/
+│   ├── docker/
+│   ├── helm/
+│   └── terraform/
+├── tests/
+│   ├── conftest.py
+│   └── test_health.py
+├── main.py                      # uv run main.py entry point
+├── alembic.ini
+├── Dockerfile                   # Uses uv for fast builds
+├── docker-compose.yml           # All services pre-configured
+├── .env                         # gitignored
+├── .env.example
+├── .gitignore
+├── .pre-commit-config.yaml
+├── Makefile
+└── pyproject.toml               # uv-compatible
+```
+
+---
+
+## Environment Variables
+
+`fastapi-spawn` generates **individual env fields** (not URL strings) for every service, assembled into URLs via `@property`:
+
+```env
+# PostgreSQL — assembled into DATABASE_URL by settings
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_DB=my_api_db
+
+# OpenAI — supports custom base URL for Azure / LM Studio
+OPENAI_API_KEY=sk-placeholder
+OPENAI_MODEL=gpt-4o
+OPENAI_BASE_URL=                # blank = api.openai.com
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=0
+```
+
+---
+
+## All Options
+
+```
+fastapi-spawn new [OPTIONS] PROJECT_NAME
+
+  --db           postgresql | mysql | mongodb | sqlite | none
+  --orm          sqlalchemy | tortoise | beanie | none
+  --migration    alembic | aerich | none
+  --auth         jwt | oauth2 | api-key | none
+  --broker       redis | rabbitmq | kafka | none
+  --cache        redis | memcached | none
+  --storage      s3 | local | none
+  --ai           openai | anthropic | none
+  --stack        minimal | standard | full
+  --ci           github | gitlab | both | none
+  --log-lib      loguru | structlog | standard
+  --no-docker    Skip Docker files
+  --no-tests     Skip test suite
+  --dry-run      Preview file tree only
+  --force / -f   Overwrite existing directory
+  --output / -o  Output directory (default: .)
+```
+
+### Subcommands
+
+```bash
+fastapi-spawn list-templates   # Show all options + ORM/DB compatibility
+fastapi-spawn validate FILE    # Validate a .fastapi-spawn.toml
+```
+
+---
+
+## After Scaffolding
+
+```bash
+cd my-api
+uv sync                        # Install all dependencies
+uv run alembic upgrade head    # Run DB migrations (if alembic)
+docker compose up --build      # Start all services
+# or
+uv run main.py                 # Run locally
+```
+
+---
+
+## ORM ↔ Database Compatibility
+
+| ORM | Compatible Databases |
+|---|---|
+| `sqlalchemy` | postgresql, mysql, sqlite |
+| `tortoise` | postgresql, mysql, sqlite |
+| `beanie` | mongodb |
+| `none` | any |
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/Bishwajitgarai/fastapi-spawn
+cd fastapi-spawn
+uv sync --all-extras
+uv run pytest
+```
+
+PRs are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT © [Bishwajit Garai](https://github.com/Bishwajitgarai)