Metadata-Version: 2.4
Name: cookiecutter-fastapi-starter
Version: 0.2.0
Summary: A pragmatic, production-minded FastAPI project generator
Project-URL: Homepage, https://github.com/pratik16102001/cookiecutter-fastapi
Project-URL: Repository, https://github.com/pratik16102001/cookiecutter-fastapi
Project-URL: Issues, https://github.com/pratik16102001/cookiecutter-fastapi/issues
Project-URL: Changelog, https://github.com/pratik16102001/cookiecutter-fastapi/blob/main/CHANGELOG.md
Author-email: Pratik Vaishnani <pratikvaishnani1610@gmail.com>
Maintainer-email: Pratik Vaishnani <pratikvaishnani1610@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: alembic,boilerplate,cookiecutter,fastapi,generator,scaffold,sqlalchemy,template
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
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 :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Code Generators
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: cookiecutter>=2.5.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Requires-Dist: tomli>=2.0.1; (python_version < '3.11') and extra == 'dev'
Requires-Dist: twine>=5.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Cookiecutter FastAPI Starter

[![PyPI version](https://img.shields.io/pypi/v/cookiecutter-fastapi-starter.svg)](https://pypi.org/project/cookiecutter-fastapi-starter/)
[![Python versions](https://img.shields.io/pypi/pyversions/cookiecutter-fastapi-starter.svg)](https://pypi.org/project/cookiecutter-fastapi-starter/)
[![CI](https://github.com/pratik16102001/cookiecutter-fastapi/actions/workflows/ci.yml/badge.svg)](https://github.com/pratik16102001/cookiecutter-fastapi/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A pragmatic, production-minded FastAPI project generator, inspired by
`cookiecutter-django`.

It generates a project with:

- FastAPI application factory
- Versioned API routes (`/api/v1`)
- Settings via `pydantic-settings`
- SQLAlchemy 2.0 session management
- Alembic migrations
- Optional JWT authentication
- A single, consistent API error envelope
- Request ID middleware
- Structured logging
- Health check endpoint
- Pytest test setup
- GitHub Actions CI
- Optional pre-commit hooks
- Optional Docker and Docker Compose files
- Optional Ruff and mypy configuration

## Install

```bash
pip install cookiecutter-fastapi-starter
```

## Usage

```bash
cookiecutter-fastapi-starter
```

Answer the prompts and you get a runnable project. To skip the prompts and
override individual values:

```bash
cookiecutter-fastapi-starter --no-input -o ./projects include_auth=no database=sqlite
```

`--help` lists the flags. If you already use Cookiecutter, you can skip the
install entirely and point it at the repository:

```bash
cookiecutter gh:pratik16102001/cookiecutter-fastapi
```

## Running the generated project

```bash
cd my-fastapi-app
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
alembic upgrade head
uvicorn app.main:app --reload
```

- API: <http://localhost:8000>
- Interactive docs: <http://localhost:8000/docs> (disabled when `ENVIRONMENT=production`)
- Health: <http://localhost:8000/api/v1/health>

## Template options

| Option | Default | Description |
| --- | --- | --- |
| `project_name` | `FastAPI Starter` | Human-readable project name |
| `project_slug` | derived | Kebab-case folder name |
| `package_name` | derived | Python import package name |
| `description` | ... | Short project description |
| `author_name` / `email` | ... | Project metadata |
| `python_version` | `3.12` | Targeted Python version |
| `fastapi_version` | `0.115.0` | Pinned FastAPI version |
| `database` | `postgresql` | `postgresql` or `sqlite` |
| `include_auth` | `yes` | JWT auth, user model, and auth routes |
| `cors_origins` | localhost origins | Comma-separated allowed origins |
| `use_docker` | `yes` | Dockerfile and Compose file |
| `use_ruff` | `yes` | Ruff lint configuration |
| `use_mypy` | `yes` | mypy configuration |
| `use_pre_commit` | `yes` | pre-commit hooks |
| `license` | `MIT` | `MIT`, `Apache-2.0`, or `Proprietary` |

## Generated layout

```
my-fastapi-app/
├── app/
│   ├── api/v1/            # Router and route modules
│   ├── core/              # Config, logging, errors, security
│   ├── db/                # Declarative base and session factory
│   ├── middleware/        # Request ID middleware
│   ├── models/            # SQLAlchemy models
│   ├── schemas/           # Pydantic schemas
│   ├── services/          # Business logic and data access
│   └── main.py            # Application factory
├── alembic/               # Migration environment and versions
├── tests/
└── pyproject.toml
```

Every error response uses one shape, carrying the request ID so that a client
report can be traced to a log line:

```json
{ "error": { "code": "http_error", "message": "Not Found", "request_id": "..." } }
```

## Before you deploy a generated project

The defaults are tuned for local development. Change these first:

- Set a real `SECRET_KEY` in `.env`.
- Set `ENVIRONMENT=production` (this also disables `/docs` and `/redoc`).
- Narrow `allowed_hosts` from `["*"]` to your actual hostnames.
- Narrow `CORS_ORIGINS` to your real front-end origins.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) and our
[Code of Conduct](CODE_OF_CONDUCT.md). To report a security issue, see
[SECURITY.md](SECURITY.md).

## Roadmap

- Role-based access control
- Redis cache option
- Celery/RQ background jobs
- OpenAPI client generation
- Kubernetes deployment examples

## License

MIT — see [LICENSE](LICENSE).
