Metadata-Version: 2.4
Name: fastapi-initializer
Version: 1.0.2
Summary: An interactive CLI tool that scaffolds production-ready FastAPI projects with sensible defaults.
Project-URL: Homepage, https://github.com/DasunNethsara-04/fastapi-initializer
Project-URL: Repository, https://github.com/DasunNethsara-04/fastapi-initializer
Project-URL: Issues, https://github.com/DasunNethsara-04/fastapi-initializer/issues
Author-email: Dasun Nethsara <techsaralk.pro@gmail.com>
License: MIT
License-File: LICENSE
Keywords: boilerplate,cli,fastapi,initializer,pipx,project-generator,scaffold,template,uv
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
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 :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: inquirerpy>=0.3.4
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

# FastAPI Initializer

[![PyPI version](https://img.shields.io/pypi/v/fastapi-initializer)](https://pypi.org/project/fastapi-initializer/)
[![Python](https://img.shields.io/pypi/pyversions/fastapi-initializer)](https://pypi.org/project/fastapi-initializer/)
[![License](https://img.shields.io/pypi/l/fastapi-initializer)](https://pypi.org/project/fastapi-initializer/)

An interactive CLI tool that scaffolds **production-ready FastAPI projects** with sensible defaults - so you can skip the boilerplate and start building right away.

---

## ✨ What Does It Do?

Run a single command, answer a few prompts, and get a fully structured FastAPI project with:

- 🗂️ **Clean project layout** - `api/`, `core/`, `models/`, `schemas/`, `services/`
- 🗃️ **Database support** - SQLite, MySQL, or PostgreSQL
- 🔧 **ORM of your choice** - SQLAlchemy or SQLModel
- 🧪 **Testing setup** - pytest / pytest-asyncio with httpx, ready to go
- 🧹 **Linter config** - Black or Ruff
- 🐳 **Docker ready** - optional `Dockerfile` & `docker-compose.yml`
- ⚙️ **Environment config** - pydantic-settings with `.env` support
- 📖 **Documentation** - every folder gets a README explaining its purpose

---

## 📦 Installation

### Recommended: Install Globally

Install `fastapi-initializer` as a global CLI tool — no virtual environment needed. Just install once and use the `fastapi-init` command from anywhere, just like `uv`, `pip`, or `ruff`.

Using [pipx](https://pipx.pypa.io/):

```bash
pipx install fastapi-initializer
```

Or using [uv](https://docs.astral.sh/uv/):

```bash
uv tool install fastapi-initializer
```

### Alternative: Install with pip

If you prefer a traditional install inside a virtual environment:

```bash
pip install fastapi-initializer
```

### Install from Source (for development)

```bash
# Clone the repository
git clone https://github.com/DasunNethsara-04/fastapi-initializer.git
cd fastapi-initializer

# Create a virtual environment and install dependencies
uv sync

# Run the CLI directly
uv run fastapi-init my-project
```

---

## 🚀 Usage

```bash
fastapi-init my-project
```

You'll be guided through interactive prompts:

```
❯ FastAPI Initializer
Creating project: my-project

❯ What kind of database do you want to use?
  > SQLite / MySQL / PostgreSQL / None

❯ Which ORM do you want to use?
  > SQLAlchemy / SQLModel / None

❯ What linter do you want to use?
  > Ruff / Black / None

❯ What testing framework do you like to use?
  > PyTest / pytest-async-io / None

❯ Do you want to create a Docker file for this project?
  > Yes / No

✔ FastAPI project 'my-project' created successfully!
```

Then get started in seconds:

```bash
cd my-project
uv sync
uv run uvicorn app.main:app --reload
```

Open **http://127.0.0.1:8000/docs** to see the interactive API docs.

---

## Screenshorts
<img width="1115" height="626" alt="Screenshot 2026-02-27 163615" src="https://github.com/user-attachments/assets/2fea7d48-470f-4056-9ebf-d84b9bc3b259" />
<img width="1119" height="628" alt="Screenshot 2026-02-27 163832" src="https://github.com/user-attachments/assets/ec137440-6a73-49aa-8d24-651652724742" />
<img width="1107" height="618" alt="Screenshot 2026-02-27 163848" src="https://github.com/user-attachments/assets/b8500d30-f745-4a6d-8a15-04d33aef3bcd" />
<img width="1110" height="623" alt="Screenshot 2026-02-27 163910" src="https://github.com/user-attachments/assets/3bd33d4b-8ce1-4daa-accf-f5b2b0b5c66d" />
<img width="1916" height="1028" alt="Screenshot 2026-02-27 164031" src="https://github.com/user-attachments/assets/7414babe-42b5-42e7-ace2-c00d4b55e21b" />
<img width="302" height="988" alt="Screenshot 2026-02-27 164114" src="https://github.com/user-attachments/assets/3cbfbeba-fbb7-4445-ac2d-ea5a86c248fc" />

---

## 📁 Generated Project Structure

The generated project follows a modular, production-style layout:

```
my-project/
├── app/
│   ├── api/
│   │   ├── v1/
│   │   │   └── users.py            # User endpoints
│   │   ├── __init__.py              # Mounts versioned routers
│   │   └── deps.py                  # Shared dependencies (e.g. auth)
│   ├── core/
│   │   ├── config.py                # App settings via pydantic-settings
│   │   └── security.py              # OAuth2 / auth utilities
│   ├── models/
│   │   └── user.py                  # ORM model (SQLAlchemy / SQLModel)
│   ├── schemas/
│   │   └── user.py                  # Pydantic request / response models
│   ├── services/
│   │   └── user_service.py          # Business logic layer
│   ├── db/
│   │   ├── base.py                  # ORM Base class
│   │   └── session.py               # Engine & get_session() dependency
│   └── main.py                      # FastAPI app entry-point
├── tests/
│   └── test_users.py                # Smoke test with httpx
├── .env                             # Environment variables
├── .gitignore
├── pyproject.toml
├── Dockerfile                       # (optional)
├── docker-compose.yml               # (optional)
└── README.md                        # Auto-generated project docs
```

> **Note:** Folders like `models/`, `db/`, `tests/`, and Docker files are only generated when you select the corresponding options.

### What Each Folder Does

| Folder | Purpose |
|--------|---------|
| `app/api/` | HTTP route definitions, versioned (`v1/`, `v2/`, …). |
| `app/core/` | App-wide settings (`Settings` class) and security helpers. |
| `app/models/` | ORM model classes mapped to database tables. |
| `app/schemas/` | Pydantic models for request validation and response serialisation. |
| `app/services/` | Business-logic layer — keeps route handlers thin and testable. |
| `app/db/` | Database engine, session factory, and `get_session()` dependency. |
| `tests/` | Automated test suite using pytest + httpx. |

---

## 🛠️ Configuration Options

| Prompt | Choices | What It Generates |
|--------|---------|-------------------|
| **Database** | SQLite, MySQL, PostgreSQL, None | `app/db/session.py` with connection URL and driver dependency |
| **ORM** | SQLAlchemy, SQLModel, None | `app/models/` with model classes and `app/db/base.py` |
| **Linter** | Ruff, Black, None | Adds the linter to `pyproject.toml` dependencies |
| **Test framework** | pytest, pytest-asyncio, None | `tests/` directory with async smoke test |
| **Docker** | Yes, No | `Dockerfile`, `docker-compose.yml`, `.dockerignore` |

---

## 🤝 Contributing

Contributions are welcome! Here's how to get started:

```bash
# 1. Fork and clone
git clone https://github.com/DasunNethsara-04/fastapi-initializer.git
cd fastapi-initializer

# 2. Install dependencies
uv sync

# 3. Make your changes, then test
uv run fastapi-init test-project

# 4. Submit a pull request
```

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).

---

## 🙏 Acknowledgements

Built with:

- [FastAPI](https://fastapi.tiangolo.com/) - the framework this tool scaffolds
- [Typer](https://typer.tiangolo.com/) - CLI framework
- [InquirerPy](https://inquirerpy.readthedocs.io/) - interactive prompts
