fastapi-struct 0.1.1__tar.gz → 0.2.1__tar.gz

fastapi_struct-0.2.1/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: fastapi-struct
+Version: 0.2.1
+Summary: CLI tool to generate standard, layered enterprise folder structures for FastAPI applications.
+License-Expression: MIT
+Keywords: fastapi,project-structure,boilerplate,scaffold,cli,template,folder-structure,architecture,repository-pattern,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 FastAPI folder structures in seconds — with dedicated templates for Enterprise Web APIs and AI/ML Inference Services.</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>
+
+---
+
+**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`?
+
+**`fastapi-struct`** generates clean, modular, and production-tested architectures for FastAPI applications. Rather than spending hours writing repetitive boilerplate, you get an instantly runnable codebase tailored to your exact project type:
+
+1. **`basic` (Default)**: Layered enterprise web API architecture (Routes &rarr; Services &rarr; Repositories &rarr; Database & Models).
+2. **`ml`**: Lean, specialized AI/ML inference microservice (Lifespan Model Loader &rarr; Inference Pipeline &rarr; Predictions & Latency Tracking).
+
+---
+
+## 📦 Quick Start & CLI Usage
+
+### 1. Enterprise Web API (Default)
+
+```bash
+# With uvx (instant, no install needed)
+uvx fastapi-struct my_api
+
+# Or with pip:
+pip install fastapi-struct
+fastapi-struct my_api
+```
+
+### 2. AI / ML Inference Service (`--template ml`)
+
+```bash
+# Generate a dedicated AI/ML service:
+fastapi-struct my_ml_service --template ml
+
+# Or shorthand:
+fastapi-struct my_ml_service -t ml
+```
+
+### 3. Scaffold in the Current Directory (`.`)
+
+```bash
+fastapi-struct . --template ml
+```
+
+---
+
+## 📂 Template 1: AI / ML Inference Architecture (`-t ml`)
+
+Specially designed for AI/ML and GenAI engineers. Removes database CRUD overhead and optimizes for model loading, tensor preprocessing, inference, and latency benchmarking.
+
+```text
+my_ml_service/
+│
+├── app/
+│   ├── __init__.py
+│   ├── main.py                 # FastAPI app + lifespan model loader (loads weights once at startup)
+│   │
+│   ├── api/
+│   │   ├── __init__.py
+│   │   └── v1/                 # API Versioning
+│   │       ├── __init__.py
+│   │       ├── api.py          # Central router aggregating endpoints
+│   │       └── routes/
+│   │           ├── __init__.py
+│   │           ├── health.py   # /health probe (readiness check + GPU/device info)
+│   │           └── predict.py  # /predict endpoint (input validation, inference, latency)
+│   │
+│   ├── core/
+│   │   ├── __init__.py
+│   │   └── config.py           # MODEL_NAME, MODEL_PATH, DEVICE ("cpu"/"cuda"), API_KEYS
+│   │
+│   ├── ml/                     # Machine learning logic
+│   │   ├── __init__.py
+│   │   ├── model.py            # Model wrapper (PyTorch / ONNX / HuggingFace)
+│   │   └── pipeline.py         # Tokenizer, preprocessing & postprocessing
+│   │
+│   ├── schemas/                # Request & Response Pydantic models
+│   │   ├── __init__.py
+│   │   └── predict.py          # PredictionRequest, PredictionResponse, HealthResponse
+│   │
+│   └── services/               # Orchestration layer
+│       ├── __init__.py
+│       └── inference.py        # Validates payload, executes pipeline, measures latency
+│
+├── tests/                      # Automated test suite
+│   ├── __init__.py
+│   ├── conftest.py             # TestClient fixtures + mock model
+│   └── test_predict.py         # Pytest test cases for /health & /predict
+│
+├── .gitignore
+├── .env                        # Local model configuration
+├── .env.example
+├── requirements.txt            # Ready for pip install -r requirements.txt
+├── pyproject.toml              # Build & pytest configuration
+└── README.md
+```
+
+---
+
+## 📂 Template 2: Layered Enterprise Web Architecture (`-t basic`)
+
+Designed for full-stack and backend services that require domain-driven separation of concerns.
+
+```text
+my_fastapi_project/
+│
+├── app/
+│   ├── __init__.py
+│   ├── main.py                 # Application factory & router registration
+│   │
+│   ├── api/v1/routes/          # HTTP route endpoints (items.py, users.py)
+│   ├── core/                   # config.py, database.py, security.py
+│   ├── models/                 # Database ORM models (item.py, user.py)
+│   ├── schemas/                # Pydantic serialization schemas (item.py, user.py)
+│   ├── services/               # Pure business logic layer
+│   ├── repositories/           # Database CRUD queries layer
+│   └── utils/                  # Utility helpers (email.py)
+│
+├── tests/                      # conftest.py, test_items.py, test_users.py
+├── requirements.txt
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## 🚀 Running Your Generated Project
+
+### 1. Step into your project directory
+```bash
+cd my_ml_service
+```
+
+### 2. Create and activate a virtual environment
+
+**Windows PowerShell:**
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+```
+
+**Windows CMD:**
+```cmd
+python -m venv .venv
+call .venv\Scripts\activate.bat
+```
+
+**macOS / Linux:**
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+### 3. Install dependencies
+```bash
+pip install -r requirements.txt
+```
+
+### 4. Start the server
+```bash
+python -m uvicorn app.main:app --reload
+```
+
+---
+
+## 🔍 Interactive API Documentation
+
+Once running, visit:
+
+- **Swagger UI**: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)
+- **ReDoc**: [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)
+
+---
+
+## 🧪 Running Automated Tests
+
+Run the included Pytest suite:
+
+```bash
+python -m pytest
+```
+
+Output:
+```text
+tests\test_predict.py ..                                                 [100%]
+============================== 2 passed in 0.15s ==============================
+```
+
+---
+
+## 📜 License
+
+This project is licensed under the terms of the [MIT License](https://opensource.org/licenses/MIT).

fastapi_struct-0.2.1/README.md

@@ -0,0 +1,218 @@
+<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 FastAPI folder structures in seconds — with dedicated templates for Enterprise Web APIs and AI/ML Inference Services.</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>
+
+---
+
+**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`?
+
+**`fastapi-struct`** generates clean, modular, and production-tested architectures for FastAPI applications. Rather than spending hours writing repetitive boilerplate, you get an instantly runnable codebase tailored to your exact project type:
+
+1. **`basic` (Default)**: Layered enterprise web API architecture (Routes &rarr; Services &rarr; Repositories &rarr; Database & Models).
+2. **`ml`**: Lean, specialized AI/ML inference microservice (Lifespan Model Loader &rarr; Inference Pipeline &rarr; Predictions & Latency Tracking).
+
+---
+
+## 📦 Quick Start & CLI Usage
+
+### 1. Enterprise Web API (Default)
+
+```bash
+# With uvx (instant, no install needed)
+uvx fastapi-struct my_api
+
+# Or with pip:
+pip install fastapi-struct
+fastapi-struct my_api
+```
+
+### 2. AI / ML Inference Service (`--template ml`)
+
+```bash
+# Generate a dedicated AI/ML service:
+fastapi-struct my_ml_service --template ml
+
+# Or shorthand:
+fastapi-struct my_ml_service -t ml
+```
+
+### 3. Scaffold in the Current Directory (`.`)
+
+```bash
+fastapi-struct . --template ml
+```
+
+---
+
+## 📂 Template 1: AI / ML Inference Architecture (`-t ml`)
+
+Specially designed for AI/ML and GenAI engineers. Removes database CRUD overhead and optimizes for model loading, tensor preprocessing, inference, and latency benchmarking.
+
+```text
+my_ml_service/
+│
+├── app/
+│   ├── __init__.py
+│   ├── main.py                 # FastAPI app + lifespan model loader (loads weights once at startup)
+│   │
+│   ├── api/
+│   │   ├── __init__.py
+│   │   └── v1/                 # API Versioning
+│   │       ├── __init__.py
+│   │       ├── api.py          # Central router aggregating endpoints
+│   │       └── routes/
+│   │           ├── __init__.py
+│   │           ├── health.py   # /health probe (readiness check + GPU/device info)
+│   │           └── predict.py  # /predict endpoint (input validation, inference, latency)
+│   │
+│   ├── core/
+│   │   ├── __init__.py
+│   │   └── config.py           # MODEL_NAME, MODEL_PATH, DEVICE ("cpu"/"cuda"), API_KEYS
+│   │
+│   ├── ml/                     # Machine learning logic
+│   │   ├── __init__.py
+│   │   ├── model.py            # Model wrapper (PyTorch / ONNX / HuggingFace)
+│   │   └── pipeline.py         # Tokenizer, preprocessing & postprocessing
+│   │
+│   ├── schemas/                # Request & Response Pydantic models
+│   │   ├── __init__.py
+│   │   └── predict.py          # PredictionRequest, PredictionResponse, HealthResponse
+│   │
+│   └── services/               # Orchestration layer
+│       ├── __init__.py
+│       └── inference.py        # Validates payload, executes pipeline, measures latency
+│
+├── tests/                      # Automated test suite
+│   ├── __init__.py
+│   ├── conftest.py             # TestClient fixtures + mock model
+│   └── test_predict.py         # Pytest test cases for /health & /predict
+│
+├── .gitignore
+├── .env                        # Local model configuration
+├── .env.example
+├── requirements.txt            # Ready for pip install -r requirements.txt
+├── pyproject.toml              # Build & pytest configuration
+└── README.md
+```
+
+---
+
+## 📂 Template 2: Layered Enterprise Web Architecture (`-t basic`)
+
+Designed for full-stack and backend services that require domain-driven separation of concerns.
+
+```text
+my_fastapi_project/
+│
+├── app/
+│   ├── __init__.py
+│   ├── main.py                 # Application factory & router registration
+│   │
+│   ├── api/v1/routes/          # HTTP route endpoints (items.py, users.py)
+│   ├── core/                   # config.py, database.py, security.py
+│   ├── models/                 # Database ORM models (item.py, user.py)
+│   ├── schemas/                # Pydantic serialization schemas (item.py, user.py)
+│   ├── services/               # Pure business logic layer
+│   ├── repositories/           # Database CRUD queries layer
+│   └── utils/                  # Utility helpers (email.py)
+│
+├── tests/                      # conftest.py, test_items.py, test_users.py
+├── requirements.txt
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## 🚀 Running Your Generated Project
+
+### 1. Step into your project directory
+```bash
+cd my_ml_service
+```
+
+### 2. Create and activate a virtual environment
+
+**Windows PowerShell:**
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+```
+
+**Windows CMD:**
+```cmd
+python -m venv .venv
+call .venv\Scripts\activate.bat
+```
+
+**macOS / Linux:**
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+### 3. Install dependencies
+```bash
+pip install -r requirements.txt
+```
+
+### 4. Start the server
+```bash
+python -m uvicorn app.main:app --reload
+```
+
+---
+
+## 🔍 Interactive API Documentation
+
+Once running, visit:
+
+- **Swagger UI**: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)
+- **ReDoc**: [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)
+
+---
+
+## 🧪 Running Automated Tests
+
+Run the included Pytest suite:
+
+```bash
+python -m pytest
+```
+
+Output:
+```text
+tests\test_predict.py ..                                                 [100%]
+============================== 2 passed in 0.15s ==============================
+```
+
+---
+
+## 📜 License
+
+This project is licensed under the terms of the [MIT License](https://opensource.org/licenses/MIT).

{fastapi_struct-0.1.1 → fastapi_struct-0.2.1}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-struct"
-version = "0.1.1"
-description = "CLI tool to generate standard, production-ready folder structures for FastAPI applications."
+version = "0.2.1"
+description = "CLI tool to generate standard, layered enterprise folder structures for FastAPI applications."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
@@ -18,6 +18,7 @@ keywords = [
     "template",
     "folder-structure",
     "architecture",
+    "repository-pattern",
     "rest-api",
 ]
 classifiers = [

fastapi_struct-0.2.1/src/create_fastapi_app/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.1"

{fastapi_struct-0.1.1 → fastapi_struct-0.2.1}/src/create_fastapi_app/cli.py

@@ -7,14 +7,21 @@ from create_fastapi_app.generator import create_project
 
 def main():
     parser = argparse.ArgumentParser(
-        prog="create-fastapi-app",
-        description="Create a new FastAPI project.",
+        prog="fastapi-struct",
+        description="Create a production-ready FastAPI project.",
     )
     parser.add_argument(
         "name",
         nargs="?",
         help="Name of the project to generate (or . for current directory)",
     )
+    parser.add_argument(
+        "-t",
+        "--template",
+        choices=["basic", "ml"],
+        default="basic",
+        help="Architecture template to use: 'basic' (layered enterprise web API) or 'ml' (AI/ML inference service). Default: basic",
+    )
     parser.add_argument(
         "--version",
         action="version",
@@ -28,17 +35,19 @@ def main():
         sys.exit(2)
 
     try:
-        path = create_project(args.name)
+        path = create_project(args.name, template=args.template)
     except (ValueError, FileExistsError, FileNotFoundError) as exc:
         parser.error(str(exc))
 
-    print(f"\nSuccess! Created project at: {path}")
+    template_desc = "AI/ML Inference Service" if args.template == "ml" else "Enterprise Layered Web API"
+    print(f"\nSuccess! Created {template_desc} at: {path}")
     print("\nNext steps:")
     if args.name != ".":
         print(f"  cd {args.name}")
     print("  python -m venv .venv")
-    print(r"  .\.venv\Scripts\Activate.ps1")
-    print('  python -m pip install -e ".[dev]"')
+    print(r"  .\.venv\Scripts\Activate.ps1   # Windows PowerShell")
+    print("  # or: source .venv/bin/activate  # macOS / Linux")
+    print("  pip install -r requirements.txt")
     print("  python -m uvicorn app.main:app --reload")
 
 

fastapi_struct-0.2.1/src/create_fastapi_app/generator.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+import re
+import shutil
+
+PACKAGE_DIR = Path(__file__).parent
+TEMPLATES_DIR = PACKAGE_DIR / "templates"
+
+
+def create_project(name: str, template: str = "basic") -> Path:
+    if name == ".":
+        project_path = Path.cwd()
+        project_name = project_path.name
+    else:
+        if not re.fullmatch(r"[A-Za-z][A-Za-z0-9_-]*", name):
+            raise ValueError(
+                "Project name must start with a letter and contain "
+                "only letters, numbers, underscores, or hyphens."
+            )
+        project_path = Path.cwd() / name
+        project_name = name
+
+        if project_path.exists():
+            raise FileExistsError(
+                f"Destination directory already exists: {project_path}"
+            )
+
+    selected_template_dir = TEMPLATES_DIR / template
+    if not selected_template_dir.is_dir():
+        available = [p.name for p in TEMPLATES_DIR.iterdir() if p.is_dir()]
+        raise FileNotFoundError(
+            f"Template '{template}' not found. Available templates: {', '.join(available)}"
+        )
+
+    # Copy files allowing existing directory (useful when name is '.')
+    shutil.copytree(selected_template_dir, project_path, dirs_exist_ok=True)
+
+    config_path = project_path / "pyproject.toml"
+    if config_path.exists():
+        config = config_path.read_text(encoding="utf-8")
+        config = config.replace(
+            'name = "my-api"',
+            f'name = "{project_name.lower().replace("_", "-")}"',
+        ).replace(
+            'name = "my-ml-api"',
+            f'name = "{project_name.lower().replace("_", "-")}"',
+        )
+        config_path.write_text(config, encoding="utf-8")
+
+    return project_path

fastapi_struct-0.2.1/src/create_fastapi_app/templates/basic/.env

@@ -0,0 +1,4 @@
+PROJECT_NAME="FastAPI Enterprise Application"
+API_V1_STR="/api/v1"
+DEBUG=true
+SECRET_KEY="supersecretkeyforproductiondevelopmentchangeinprod"

fastapi_struct-0.2.1/src/create_fastapi_app/templates/basic/.env.example

@@ -0,0 +1,4 @@
+PROJECT_NAME="FastAPI Enterprise Application"
+API_V1_STR="/api/v1"
+DEBUG=true
+SECRET_KEY="your_secret_key_here"

{fastapi_struct-0.1.1 → fastapi_struct-0.2.1}/src/create_fastapi_app/templates/basic/.gitignore

@@ -4,3 +4,6 @@ __pycache__/
 .pytest_cache/
 *.py[cod]
 *.db
+dist/
+build/
+*.egg-info/

fastapi_struct-0.2.1/src/create_fastapi_app/templates/basic/README.md

@@ -0,0 +1,35 @@
+# FastAPI Application
+
+Enterprise-grade modular FastAPI application generated with `fastapi-struct`.
+
+## Quick Start
+
+### 1. Create Virtual Environment
+```bash
+python -m venv .venv
+```
+
+Activate:
+- Windows PowerShell: `.\.venv\Scripts\Activate.ps1`
+- Windows CMD: `call .venv\Scripts\activate.bat`
+- Linux/macOS: `source .venv/bin/activate`
+
+### 2. Install Dependencies
+```bash
+pip install -r requirements.txt
+```
+*(or `pip install -e ".[dev]"`)*
+
+### 3. Run Development Server
+```bash
+python -m uvicorn app.main:app --reload
+```
+
+Interactive API docs available at:
+- Swagger UI: http://127.0.0.1:8000/docs
+- ReDoc: http://127.0.0.1:8000/redoc
+
+### 4. Run Tests
+```bash
+python -m pytest
+```

fastapi_struct-0.2.1/src/create_fastapi_app/templates/basic/app/api/v1/api.py

@@ -0,0 +1,6 @@
+from fastapi import APIRouter
+from app.api.v1.routes import items, users
+
+api_router = APIRouter()
+api_router.include_router(items.router)
+api_router.include_router(users.router)

fastapi_struct-0.2.1/src/create_fastapi_app/templates/basic/app/api/v1/routes/items.py

@@ -0,0 +1,23 @@
+from fastapi import APIRouter, HTTPException, status
+from app.schemas.item import ItemCreate, ItemResponse
+from app.services.item_service import item_service
+
+router = APIRouter(prefix="/items", tags=["Items"])
+
+
+@router.get("/", response_model=list[ItemResponse])
+async def read_items():
+    return item_service.list_items()
+
+
+@router.post("/", response_model=ItemResponse, status_code=status.HTTP_201_CREATED)
+async def create_item(item_in: ItemCreate):
+    return item_service.create_item(item_in)
+
+
+@router.get("/{item_id}", response_model=ItemResponse)
+async def read_item(item_id: int):
+    item = item_service.get_item(item_id)
+    if not item:
+        raise HTTPException(status_code=404, detail="Item not found")
+    return item

fastapi_struct-0.2.1/src/create_fastapi_app/templates/basic/app/api/v1/routes/users.py

@@ -0,0 +1,26 @@
+from fastapi import APIRouter, HTTPException, status
+from app.schemas.user import UserCreate, UserResponse
+from app.services.user_service import user_service
+
+router = APIRouter(prefix="/users", tags=["Users"])
+
+
+@router.get("/", response_model=list[UserResponse])
+async def read_users():
+    return user_service.list_users()
+
+
+@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def create_user(user_in: UserCreate):
+    try:
+        return user_service.create_user(user_in)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/{user_id}", response_model=UserResponse)
+async def read_user(user_id: int):
+    user = user_service.get_user(user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user