Boilerplate (#1)

Author: pimuzzo

.gitignore

@@ -85,7 +85,7 @@ ipython_config.py
 # pyenv
 #   For a library or package, you might want to ignore these files since the code is
 #   intended to run in multiple environments; otherwise, check them in:
-# .python-version
+.python-version
 
 # pipenv
 #   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
@@ -173,7 +173,7 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
 
 # Abstra
 # Abstra is an AI-powered process automation framework.

README.md

@@ -1 +1,31 @@
-# python-fastapi-template
+# python-fastapi-template
+
+A simple and idiomatic REST API boilerplate in Python using [FastAPI](https://fastapi.tiangolo.com/), designed for clarity, modularity and extensibility.  
+Built to showcase best practices in Python backend development and serve as a solid foundation for future projects.
+
+## ✨ Features
+
+- 🧱 Modular project structure (`api/`, `models/`, `services/`, etc.)
+- 🔀 Routing with versioned endpoints
+- 📄 OpenAPI docs auto-generated (`/docs`, `/redoc`)
+- ✅ Data validation and typing with Pydantic v2
+- 🧪 Async-ready test setup with `pytest`, `httpx`, `pytest-asyncio` (in progress)
+- 🐳 Minimal Docker support (in progress)
+- 🧰 Designed as a reusable starter template
+
+## 📦 Technologies
+
+- Python 3.11+
+- FastAPI
+- Uvicorn (ASGI server)
+- Pydantic v2
+
+## 🚀 Getting Started
+
+```bash
+# Install dependencies
+poetry install
+
+# Run the development server
+poetry run uvicorn app.main:app --reload
+```

app/__init__.py

@@ -0,0 +1,15 @@
+from fastapi import APIRouter, HTTPException
+from app.models.user import User, UserCreate
+from app.services.user_service import save_user, get_all_users
+
+router = APIRouter()
+
+
+@router.post("/", response_model=User)
+async def create_user(user: UserCreate):
+    return await save_user(user)
+
+
+@router.get("/", response_model=list[User])
+async def get_users():
+    return await get_all_users()

app/api/__init__.py

@@ -0,0 +1,12 @@
+import logging
+import sys
+
+from fastapi import FastAPI
+from app.api import users
+
+log_format = '%(asctime)s | %(levelname)-8s | %(name)-12s - %(message)s'
+logging.basicConfig(stream=sys.stdout, level=logging.DEBUG, format=log_format)
+
+app = FastAPI(title="Python FastAPI Template", version="0.1.0")
+
+app.include_router(users.router, prefix="/api/v1/users", tags=["User"])

app/api/users.py

@@ -0,0 +1,14 @@
+from pydantic import BaseModel, EmailStr
+
+
+class UserBase(BaseModel):
+    email: EmailStr
+
+
+class UserCreate(UserBase):
+    name: str
+
+
+class User(UserBase):
+    id: int
+    name: str

app/main.py

@@ -0,0 +1,14 @@
+from app.models.user import User, UserCreate
+
+_fake_db: list[User] = []
+
+
+async def save_user(user: UserCreate) -> User:
+    user_id = len(_fake_db) + 1
+    new_user = User(id=user_id, **user.model_dump())
+    _fake_db.append(new_user)
+    return new_user
+
+
+async def get_all_users() -> list[User]:
+    return _fake_db