Metadata-Version: 2.4
Name: fastapi-struct
Version: 0.1.1
Summary: CLI tool to generate standard, production-ready folder structures for FastAPI applications.
License-Expression: MIT
Keywords: fastapi,project-structure,boilerplate,scaffold,cli,template,folder-structure,architecture,rest-api
Classifier: Programming Language :: Python :: 3
Classifier: Framework :: FastAPI
Classifier: Topic :: Software Development :: Code Generators
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://pypi.org/project/fastapi-struct/"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" width="320" alt="fastapi-struct"></a>
</p>
<p align="center">
    <em>CLI tool to generate standard, production-ready, modular folder structures for FastAPI applications in seconds.</em>
</p>
<p align="center">
<a href="https://pypi.org/project/fastapi-struct" target="_blank">
    <img src="https://img.shields.io/pypi/v/fastapi-struct.svg?color=%2334D058" alt="Package version">
</a>
<a href="https://pypi.org/project/fastapi-struct" target="_blank">
    <img src="https://img.shields.io/pypi/pyversions/fastapi-struct.svg?color=%2334D058" alt="Supported Python versions">
</a>
<a href="https://github.com/fastapi/fastapi" target="_blank">
    <img src="https://img.shields.io/badge/FastAPI-0.115+-009688.svg?logo=fastapi&logoColor=white" alt="FastAPI">
</a>
<a href="https://github.com/pydantic/pydantic" target="_blank">
    <img src="https://img.shields.io/badge/Pydantic-v2-E92063.svg?logo=pydantic&logoColor=white" alt="Pydantic v2">
</a>
<a href="https://opensource.org/licenses/MIT" target="_blank">
    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT">
</a>
</p>

---

**Source Code:** [https://github.com/fastapi/fastapi](https://github.com/fastapi/fastapi)  
**FastAPI Documentation:** [https://fastapi.tiangolo.com](https://fastapi.tiangolo.com)  
**PyPI Package:** [https://pypi.org/project/fastapi-struct/](https://pypi.org/project/fastapi-struct/)

---

## ⚡ What is `fastapi-struct`?

When starting a new FastAPI project, developers often spend hours configuring boilerplate: creating router files, structuring Pydantic schemas, setting up database sessions, writing `.env` configurations, and setting up `pytest`.

**`fastapi-struct`** gives you an instant, production-tested architectural foundation modeled after enterprise best practices—with a single command:

```bash
fastapi-struct my-api
```

Or scaffold directly inside your existing directory:

```bash
fastapi-struct .
```

---

## 🎯 Key Features

- **⚡ Fast to Scaffold:** Spin up a complete, working FastAPI application in under 2 seconds.
- **🏛️ Enterprise Clean Architecture:** Separation of concerns dividing **Routers**, **Schemas**, **Database Models**, **Services**, and **Dependencies**.
- **🛡️ Pydantic v2 & Settings:** Preconfigured with `pydantic-settings` to safely read environment variables from `.env`.
- **🧪 Ready-to-Run Testing:** Complete with `pytest` and `httpx` integration tests verifying `/` and `/health`.
- **📖 Interactive API Documentation:** Instant Swagger UI (`/docs`) and ReDoc (`/redoc`) right out of the box.
- **🪶 Ultra Lightweight:** Zero heavy runtime overhead; purely generates standard Python code.
- **💻 Cross-Platform:** Works seamlessly on Windows PowerShell, CMD, macOS, and Linux.

---

## 📦 Installation & Quick Start

### Option 1: Instant with `uvx` *(No installation required)*

Run it on-demand just like `npx create-react-app`:

```bash
uvx fastapi-struct my-api
```

Or in the current folder:

```bash
uvx fastapi-struct .
```

---

### Option 2: Standard install with `pip`

```bash
pip install fastapi-struct
```

Generate your project:

```bash
fastapi-struct my-api
```
*(Alias command `create-fastapi-app my-api` is also included!)*

---

## 📂 The Generated Architecture

Every generated application follows a clean, decoupled layout:

```text
my-api/
│
├── .env.example              # Sample environment variables
├── .gitignore                # Production Python/venv gitignore rules
├── pyproject.toml            # Project dependencies and Pytest configuration
├── README.md                 # Quickstart guide for your new API
│
├── app/
│   ├── __init__.py
│   ├── main.py               # Application factory & router registration
│   ├── dependencies.py       # Shared dependencies (Auth, DB session, etc.)
│   │
│   ├── core/
│   │   ├── __init__.py
│   │   └── config.py         # App configuration & BaseSettings (.env loader)
│   │
│   ├── routers/              # API endpoints organized by domain
│   │   ├── __init__.py
│   │   ├── health.py         # System health check (/health)
│   │   └── users.py          # Sample CRUD user endpoints
│   │
│   ├── schemas/              # Pydantic data validation & serialization
│   │   ├── __init__.py
│   │   └── user.py           # UserCreate & UserResponse models
│   │
│   ├── models/               # ORM & Database models (SQLAlchemy / SQLModel)
│   │   └── __init__.py
│   │
│   ├── services/             # Pure business logic layer
│   │   └── __init__.py
│   │
│   └── db/                   # Database engine & session management
│       ├── __init__.py
│       └── database.py
│
└── tests/                    # Automated testing suite
    ├── __init__.py
    └── test_main.py          # Pytest integration tests using TestClient
```

---

## 🚀 Running Your Generated Application

### 1. Step into your project directory
```bash
cd my-api
```
*(Skip if generated with `fastapi-struct .`)*

### 2. Create and activate a virtual environment

**On Windows (PowerShell):**
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

**On Windows (Command Prompt):**
```cmd
python -m venv .venv
call .venv\Scripts\activate.bat
```

**On macOS & Linux:**
```bash
python3 -m venv .venv
source .venv/bin/activate
```

### 3. Install dependencies in editable mode
```bash
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
```

### 4. Start the development server
```bash
python -m uvicorn app.main:app --reload
```

---

## 🔍 Explore Your API

Once your server is running:

| Service | URL | Description |
| :--- | :--- | :--- |
| **Root Endpoint** | [http://127.0.0.1:8000/](http://127.0.0.1:8000/) | Welcome JSON response |
| **Health Check** | [http://127.0.0.1:8000/health](http://127.0.0.1:8000/health) | Uptime monitoring endpoint |
| **Interactive Docs (Swagger UI)** | [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) | Test endpoints directly in browser |
| **Alternative Docs (ReDoc)** | [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) | Clean API reference docs |

---

## 🧪 Running Automated Tests

Run the included Pytest suite with:

```bash
python -m pytest
```

Output:
```text
tests\test_main.py ..                                                    [100%]
============================== 2 passed in 0.45s ==============================
```

---

## 🧩 Adding a New Feature

Adding new capabilities to your generated app takes just 3 clean steps:

### 1. Define your Pydantic Schema (`app/schemas/item.py`)
```python
from pydantic import BaseModel, Field

class ItemCreate(BaseModel):
    title: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0)

class ItemResponse(ItemCreate):
    id: int
```

### 2. Create your Router (`app/routers/items.py`)
```python
from fastapi import APIRouter
from app.schemas.item import ItemCreate, ItemResponse

router = APIRouter(prefix="/items", tags=["Items"])

@router.post("/", response_model=ItemResponse)
async def create_item(item: ItemCreate):
    return {"id": 1, **item.model_dump()}
```

### 3. Register in `app/main.py`
```python
from app.routers.items import router as items_router

app.include_router(items_router)
```

The server automatically reloads, and the new `/items` endpoint is instantly testable at `http://127.0.0.1:8000/docs`!

---

## 📜 License

This project is open-source software licensed under the [MIT License](https://opensource.org/licenses/MIT).
