Metadata-Version: 2.4
Name: fastapi-spawn
Version: 0.2.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)

Generate production-ready FastAPI projects in seconds — with exactly the stack you need.

</div>

---

## Installation

```bash
pip install fastapi-spawn
# or
uv pip install fastapi-spawn
```

---

## Quick Start

```bash
# Interactive TUI — guided step-by-step
fastapi-spawn new my-api

# One-liner with all flags
fastapi-spawn new my-api \
  --db postgresql \
  --orm sqlalchemy \
  --migration alembic \
  --auth jwt \
  --broker redis \
  --storage s3 \
  --ai openai \
  --monitoring sentry \
  --email sendgrid \
  --log-dest cloudwatch \
  --vector-db qdrant \
  --stack full \
  --ci github

# Preview file tree without writing
fastapi-spawn new my-api --dry-run

# Add a feature to an existing project
fastapi-spawn add openai
fastapi-spawn add alembic
fastapi-spawn add sentry
```

---

## What Gets Generated

```
my-api/
├── app/
│   ├── api/
│   │   └── v1/
│   │       ├── health.py        # GET /health  /readiness  /liveness
│   │       └── auth.py          # POST /auth/login  /auth/refresh
│   ├── core/
│   │   ├── config.py            # Pydantic Settings v2 — individual env fields + @property URLs
│   │   ├── logger.py            # Context-var logger — request ID, client IP, dual-timezone
│   │   ├── exceptions.py        # Custom exception hierarchy + handlers
│   │   ├── security.py          # JWT / bcrypt
│   │   ├── storage.py           # AWS S3 / MinIO helpers
│   │   ├── ai.py                # OpenAI / Anthropic / Gemini / Ollama async client
│   │   ├── email.py             # SendGrid / SMTP / SES
│   │   └── monitoring.py        # Sentry init / Prometheus metrics
│   ├── middleware/
│   │   ├── request_logger.py    # X-Request-ID, response time, structured logs
│   │   └── rate_limit.py        # slowapi — 429 with Retry-After
│   ├── db/
│   │   └── session.py           # Async SQLAlchemy / Tortoise / Beanie
│   ├── models/
│   ├── schemas/
│   ├── services/
│   └── repositories/
├── tasks/                       # Celery workers (root-level)
│   ├── celery_app.py
│   └── sample_tasks.py
├── migrations/                  # Alembic (async-compatible)
│   ├── env.py
│   └── versions/
├── infra/
│   ├── docker/
│   ├── helm/
│   └── terraform/
├── tests/
├── logs/                        # Local log rotation directory
├── main.py                      # uv run main.py
├── alembic.ini
├── Dockerfile                   # Uses uv for fast layer-cached builds
├── docker-compose.yml           # All selected services pre-configured
├── .env                         # gitignored
├── .env.example
├── .gitignore
├── .pre-commit-config.yaml
├── Makefile
└── pyproject.toml               # uv-compatible with [tool.uv.scripts]
```

---

## All Options

```
fastapi-spawn new [OPTIONS] PROJECT_NAME

Database & ORM
  --db           postgresql | mysql | mongodb | sqlite | none
  --orm          sqlalchemy | tortoise | beanie | none
  --migration    alembic | aerich | none

Auth & Security
  --auth         jwt | oauth2 | api-key | none

Messaging & Cache
  --broker       redis | rabbitmq | kafka | none
  --cache        redis | memcached | none

Storage
  --storage      s3 | local | none          (s3 = AWS S3 or MinIO)

AI / LLM
  --ai           openai | anthropic | gemini | ollama | none

Monitoring
  --monitoring   sentry | prometheus | both | none

Email
  --email        sendgrid | smtp | ses | none

Notifications
  --notify       slack | discord | none

Logging
  --log-lib      loguru | structlog | standard
  --log-dest     local | cloudwatch | datadog | none

Vector Database
  --vector-db    qdrant | pinecone | elasticsearch | none

Deployment
  --stack        minimal | standard | full
  --ci           github | gitlab | both | none

Flags
  --no-docker    Skip Docker files
  --no-tests     Skip test suite
  --dry-run      Preview file tree without writing
  --force / -f   Overwrite existing directory
  --output / -o  Output directory
```

---

## uv run Scripts

Every generated project has `[tool.uv.scripts]` pre-wired:

```bash
uv run dev        # uvicorn --reload
uv run start      # python main.py
uv run test       # pytest --cov
uv run lint       # ruff check
uv run format     # ruff format
uv run typecheck  # mypy
uv run migrate    # alembic upgrade head  (if alembic)
uv run rollback   # alembic downgrade -1  (if alembic)
uv run makemig    # alembic revision --autogenerate  (if alembic)
uv run worker     # celery worker  (if broker)
uv run beat       # celery beat    (if broker)
```

---

## Environment Variables

Individual fields per service — **no URL strings**. URLs are assembled via `@property`:

```env
ENVIRONMENT=dev
SECRET_KEY=super-secret-change-in-production

# PostgreSQL
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=my_api_db

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# AWS S3 (or MinIO — set ENDPOINT_URL for local)
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG
AWS_REGION=us-east-1
AWS_S3_BUCKET=my-api-bucket
AWS_S3_ENDPOINT_URL=http://localhost:9000   # MinIO local

# OpenAI (supports custom base URL for Azure / LM Studio)
OPENAI_API_KEY=sk-placeholder
OPENAI_MODEL=gpt-4o
OPENAI_BASE_URL=

# Sentry
SENTRY_DSN=https://xxx@sentry.io/yyy

# Logging
LOG_LEVEL=INFO
LOG_DIR=logs
LOG_BACKUP_DAYS=30
```

---

## Add Features to Existing Projects

```bash
fastapi-spawn add sentry      # Sentry error tracking setup
fastapi-spawn add openai      # OpenAI async client + env vars
fastapi-spawn add alembic     # Alembic async migrations
fastapi-spawn add s3          # AWS S3 / MinIO storage utils
fastapi-spawn add celery      # Celery worker + tasks/
fastapi-spawn add helm        # Helm chart in infra/helm/
fastapi-spawn add terraform   # Terraform scaffold in infra/terraform/
```

---

## ORM ↔ Database Compatibility

| ORM | Compatible Databases |
|---|---|
| `sqlalchemy` | postgresql, mysql, sqlite |
| `tortoise` | postgresql, mysql, sqlite |
| `beanie` | mongodb |
| `none` | any |

---

## Middleware Stack (always included)

| Middleware | What it does |
|---|---|
| `RequestLoggingMiddleware` | Logs `→ METHOD /path` + `✓ status duration` with request ID |
| `RateLimitMiddleware` | 200 req/min default via slowapi, returns 429 + `Retry-After` |
| `CORSMiddleware` | Configurable via `CORS_ORIGINS` env var |

Every response includes `X-Request-ID` and `X-Response-Time` headers.

---

## Contributing

```bash
git clone https://github.com/Bishwajitgarai/fastapi-spawn
cd fastapi-spawn
uv sync --all-extras
uv run pytest
```

---

## License

MIT © [Bishwajit Garai](https://github.com/Bishwajitgarai)
