FastAPI-fastkit 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/pyproject.toml-tpl

@@ -0,0 +1,70 @@
+[project]
+name = "<project_name>"
+version = "0.1.0"
+description = "[FastAPI-fastkit templated] <description>"
+authors = [
+    {name = "<author>", email = "<author_email>"},
+]
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115.8",
+    "uvicorn[standard]>=0.34.0",
+    "pydantic>=2.10.6",
+    "pydantic-settings>=2.7.1",
+    "python-dotenv>=1.0.1",
+    "fastapi-fastkit>=1.1.5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.4",
+    "httpx>=0.28.1",
+    "black>=25.1.0",
+    "isort>=6.0.0",
+    "mypy>=1.15.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "httpx>=0.28.1",
+    "black>=25.1.0",
+    "isort>=6.0.0",
+    "mypy>=1.15.0",
+]
+
+[tool.fastapi-fastkit]
+managed = true
+template = "fastapi-domain-starter"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+
+[tool.black]
+line-length = 88
+target-version = ["py312"]
+
+[tool.isort]
+profile = "black"
+line_length = 88
+known_first_party = ["src"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/requirements.txt-tpl

@@ -0,0 +1,11 @@
+fastapi==0.115.8
+uvicorn[standard]==0.34.0
+pydantic==2.10.6
+pydantic-settings==2.7.1
+python-dotenv==1.0.1
+pytest==8.3.4
+httpx==0.28.1
+black==25.1.0
+isort==6.0.0
+mypy==1.15.0
+FastAPI-fastkit==1.1.5

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/scripts/format.sh-tpl

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -x
+
+black .
+isort .

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/scripts/lint.sh-tpl

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -x
+
+black . --check
+isort . --check-only
+mypy src

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/scripts/run-server.sh-tpl

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+set -e
+set -x
+
+source .venv/bin/activate
+
+uvicorn src.app.main:app --reload

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/scripts/test.sh-tpl

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+set -e
+set -x
+
+pytest

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/src/app/api/health.py-tpl

@@ -0,0 +1,11 @@
+# --------------------------------------------------------------------------
+# Health endpoint — small, side-effect-free probe for liveness checks.
+# --------------------------------------------------------------------------
+from fastapi import APIRouter
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/src/app/api/router.py-tpl

@@ -0,0 +1,12 @@
+# --------------------------------------------------------------------------
+# Top-level API router — aggregates the health probe with every domain
+# module under ``src/app/domains/``.
+# --------------------------------------------------------------------------
+from fastapi import APIRouter
+
+from src.app.api import health
+from src.app.domains.items import router as items_router
+
+api_router = APIRouter()
+api_router.include_router(health.router)
+api_router.include_router(items_router.router)

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/src/app/core/config.py-tpl

@@ -0,0 +1,49 @@
+# --------------------------------------------------------------------------
+# Application settings (pydantic-settings).
+# --------------------------------------------------------------------------
+import secrets
+from typing import Annotated, Any, List, Literal, Union
+
+from pydantic import AnyUrl, BeforeValidator, computed_field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _parse_cors(v: Any) -> Union[List[str], str]:
+    if isinstance(v, str) and not v.startswith("["):
+        return [item.strip() for item in v.split(",") if item.strip()]
+    if isinstance(v, (list, str)):
+        return v
+    raise ValueError(v)
+
+
+class Settings(BaseSettings):
+    """Centralized configuration for the application.
+
+    Values are populated from environment variables (or a local ``.env``
+    file) so the same image / build can run in development, staging, and
+    production without code changes.
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_ignore_empty=True,
+        extra="ignore",
+    )
+
+    PROJECT_NAME: str = "<project_name>"
+    ENVIRONMENT: Literal["development", "staging", "production"] = "development"
+    SECRET_KEY: str = secrets.token_urlsafe(32)
+
+    API_V1_PREFIX: str = "/api/v1"
+
+    BACKEND_CORS_ORIGINS: Annotated[
+        Union[List[AnyUrl], str], BeforeValidator(_parse_cors)
+    ] = []
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def all_cors_origins(self) -> List[str]:
+        return [str(origin).rstrip("/") for origin in self.BACKEND_CORS_ORIGINS]
+
+
+settings = Settings()  # type: ignore[call-arg]

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/src/app/db/memory.py-tpl

@@ -0,0 +1,48 @@
+# --------------------------------------------------------------------------
+# Process-local in-memory store used as a placeholder for a real database.
+#
+# Domain repositories sit on top of this store, so swapping the store for
+# SQLAlchemy / async drivers later is a contained change — only the
+# repositories need to be rewritten.
+# --------------------------------------------------------------------------
+from typing import Dict, Generic, Iterable, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+class InMemoryStore(Generic[T]):
+    """Tiny ID-keyed collection backed by a dict.
+
+    Not thread-safe and not suitable for production — but lets the rest of
+    the application code stay realistic (repository / service / router) while
+    keeping the starter self-contained.
+    """
+
+    def __init__(self) -> None:
+        self._data: Dict[int, T] = {}
+        self._next_id: int = 1
+
+    def list(self) -> Iterable[T]:
+        return list(self._data.values())
+
+    def get(self, id_: int) -> Optional[T]:
+        return self._data.get(id_)
+
+    def add(self, item: T) -> int:
+        new_id = self._next_id
+        self._data[new_id] = item
+        self._next_id += 1
+        return new_id
+
+    def replace(self, id_: int, item: T) -> bool:
+        if id_ not in self._data:
+            return False
+        self._data[id_] = item
+        return True
+
+    def delete(self, id_: int) -> bool:
+        return self._data.pop(id_, None) is not None
+
+    def clear(self) -> None:
+        self._data.clear()
+        self._next_id = 1

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/src/app/domains/items/__init__.py-tpl

@@ -0,0 +1,9 @@
+# Re-exports for the items domain so callers can write:
+#   from src.app.domains.items import service
+from src.app.domains.items import (  # noqa: F401
+    models,
+    repository,
+    router,
+    schemas,
+    service,
+)

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/src/app/domains/items/models.py-tpl

@@ -0,0 +1,17 @@
+# --------------------------------------------------------------------------
+# Items domain — internal entity model.
+#
+# Kept separate from the API schemas in ``schemas.py`` so the wire format
+# can evolve without touching domain logic, and vice versa.
+# --------------------------------------------------------------------------
+from dataclasses import dataclass
+
+
+@dataclass
+class Item:
+    """Domain entity: an item tracked by the application."""
+
+    id: int
+    name: str
+    price: float
+    in_stock: bool = True

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/src/app/domains/items/repository.py-tpl

@@ -0,0 +1,48 @@
+# --------------------------------------------------------------------------
+# Items domain — repository (data access boundary).
+#
+# Wraps the in-memory store with item-typed methods so the service layer
+# stays decoupled from how items are persisted.
+# --------------------------------------------------------------------------
+from typing import List, Optional
+
+from src.app.db.memory import InMemoryStore
+from src.app.domains.items.models import Item
+
+_store: InMemoryStore[Item] = InMemoryStore()
+
+
+class ItemRepository:
+    """Data access for ``Item`` entities."""
+
+    def __init__(self, store: Optional[InMemoryStore[Item]] = None) -> None:
+        self._store = store if store is not None else _store
+
+    def list_all(self) -> List[Item]:
+        return list(self._store.list())
+
+    def get(self, item_id: int) -> Optional[Item]:
+        return self._store.get(item_id)
+
+    def add(self, name: str, price: float, in_stock: bool = True) -> Item:
+        # Reserve the next id from the store, then back-fill it on the
+        # entity so the repository is the single source of identity.
+        item = Item(id=0, name=name, price=price, in_stock=in_stock)
+        new_id = self._store.add(item)
+        item.id = new_id
+        return item
+
+    def replace(self, item_id: int, name: str, price: float, in_stock: bool) -> Optional[Item]:
+        existing = self._store.get(item_id)
+        if existing is None:
+            return None
+        updated = Item(id=item_id, name=name, price=price, in_stock=in_stock)
+        self._store.replace(item_id, updated)
+        return updated
+
+    def delete(self, item_id: int) -> bool:
+        return self._store.delete(item_id)
+
+    def reset(self) -> None:
+        # Convenience for tests / local development; not exposed via the API.
+        self._store.clear()

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/src/app/domains/items/router.py-tpl

@@ -0,0 +1,59 @@
+# --------------------------------------------------------------------------
+# Items domain — HTTP transport (FastAPI router).
+# --------------------------------------------------------------------------
+from typing import List
+
+from fastapi import APIRouter, Depends, HTTPException, Response, status
+
+from src.app.domains.items.schemas import ItemCreate, ItemRead
+from src.app.domains.items.service import ItemNotFoundError, ItemService
+
+router = APIRouter(prefix="/items", tags=["items"])
+
+
+def get_item_service() -> ItemService:
+    """Default dependency — overridable in tests."""
+    return ItemService()
+
+
+@router.get("", response_model=List[ItemRead])
+def list_items(service: ItemService = Depends(get_item_service)) -> List[ItemRead]:
+    return [ItemRead.model_validate(item) for item in service.list_items()]
+
+
+@router.get("/{item_id}", response_model=ItemRead)
+def get_item(item_id: int, service: ItemService = Depends(get_item_service)) -> ItemRead:
+    try:
+        return ItemRead.model_validate(service.get_item(item_id))
+    except ItemNotFoundError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc))
+
+
+@router.post("", response_model=ItemRead, status_code=status.HTTP_201_CREATED)
+def create_item(
+    payload: ItemCreate, service: ItemService = Depends(get_item_service)
+) -> ItemRead:
+    return ItemRead.model_validate(service.create_item(payload))
+
+
+@router.put("/{item_id}", response_model=ItemRead)
+def replace_item(
+    item_id: int,
+    payload: ItemCreate,
+    service: ItemService = Depends(get_item_service),
+) -> ItemRead:
+    try:
+        return ItemRead.model_validate(service.replace_item(item_id, payload))
+    except ItemNotFoundError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc))
+
+
+@router.delete("/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_item(
+    item_id: int, service: ItemService = Depends(get_item_service)
+) -> Response:
+    try:
+        service.delete_item(item_id)
+    except ItemNotFoundError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc))
+    return Response(status_code=status.HTTP_204_NO_CONTENT)

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/src/app/domains/items/schemas.py-tpl

@@ -0,0 +1,23 @@
+# --------------------------------------------------------------------------
+# Items domain — API I/O schemas (pydantic).
+# --------------------------------------------------------------------------
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ItemCreate(BaseModel):
+    """Payload accepted on POST /items."""
+
+    name: str = Field(min_length=1, max_length=120)
+    price: float = Field(ge=0)
+    in_stock: bool = True
+
+
+class ItemRead(BaseModel):
+    """Outgoing representation of an item."""
+
+    id: int
+    name: str
+    price: float
+    in_stock: bool
+
+    model_config = ConfigDict(from_attributes=True)

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/src/app/domains/items/service.py-tpl

@@ -0,0 +1,52 @@
+# --------------------------------------------------------------------------
+# Items domain — service layer (business logic).
+#
+# Routers should call into the service rather than the repository directly,
+# so policy and validation rules can grow here without touching transport
+# code or persistence.
+# --------------------------------------------------------------------------
+from typing import List, Optional
+
+from src.app.domains.items.models import Item
+from src.app.domains.items.repository import ItemRepository
+from src.app.domains.items.schemas import ItemCreate
+
+
+class ItemNotFoundError(Exception):
+    """Raised when an item lookup misses."""
+
+
+class ItemService:
+    def __init__(self, repository: Optional[ItemRepository] = None) -> None:
+        self._repository = repository if repository is not None else ItemRepository()
+
+    def list_items(self) -> List[Item]:
+        return self._repository.list_all()
+
+    def get_item(self, item_id: int) -> Item:
+        item = self._repository.get(item_id)
+        if item is None:
+            raise ItemNotFoundError(f"Item {item_id} does not exist")
+        return item
+
+    def create_item(self, payload: ItemCreate) -> Item:
+        return self._repository.add(
+            name=payload.name,
+            price=payload.price,
+            in_stock=payload.in_stock,
+        )
+
+    def replace_item(self, item_id: int, payload: ItemCreate) -> Item:
+        updated = self._repository.replace(
+            item_id,
+            name=payload.name,
+            price=payload.price,
+            in_stock=payload.in_stock,
+        )
+        if updated is None:
+            raise ItemNotFoundError(f"Item {item_id} does not exist")
+        return updated
+
+    def delete_item(self, item_id: int) -> None:
+        if not self._repository.delete(item_id):
+            raise ItemNotFoundError(f"Item {item_id} does not exist")

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/src/app/main.py-tpl

@@ -0,0 +1,25 @@
+# --------------------------------------------------------------------------
+# FastAPI application entry point for <project_name>.
+# --------------------------------------------------------------------------
+from fastapi import FastAPI
+from starlette.middleware.cors import CORSMiddleware
+
+from src.app.api.router import api_router
+from src.app.core.config import settings
+
+app = FastAPI(
+    title=settings.PROJECT_NAME,
+    description="<description>",
+    version="0.1.0",
+)
+
+if settings.all_cors_origins:
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.all_cors_origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+app.include_router(api_router, prefix=settings.API_V1_PREFIX)

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/tests/conftest.py-tpl

@@ -0,0 +1,24 @@
+# --------------------------------------------------------------------------
+# pytest fixtures for <project_name>.
+# --------------------------------------------------------------------------
+from collections.abc import Generator
+
+import pytest
+from fastapi.testclient import TestClient
+
+from src.app.domains.items.repository import ItemRepository
+from src.app.main import app
+
+
+@pytest.fixture(autouse=True)
+def reset_items_store() -> Generator[None, None, None]:
+    """Each test starts with an empty items store."""
+    ItemRepository().reset()
+    yield
+    ItemRepository().reset()
+
+
+@pytest.fixture
+def client() -> Generator[TestClient, None, None]:
+    with TestClient(app) as c:
+        yield c

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/tests/test_health.py-tpl

@@ -0,0 +1,11 @@
+# --------------------------------------------------------------------------
+# Health endpoint smoke test.
+# --------------------------------------------------------------------------
+from src.app.core.config import settings
+
+
+def test_health_endpoint_returns_ok(client):
+    response = client.get(f"{settings.API_V1_PREFIX}/health")
+
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/tests/test_items.py-tpl

@@ -0,0 +1,77 @@
+# --------------------------------------------------------------------------
+# Items domain — end-to-end coverage of the CRUD endpoints.
+# --------------------------------------------------------------------------
+from src.app.core.config import settings
+
+ITEMS_URL = f"{settings.API_V1_PREFIX}/items"
+
+
+def test_list_items_starts_empty(client):
+    response = client.get(ITEMS_URL)
+
+    assert response.status_code == 200
+    assert response.json() == []
+
+
+def test_create_then_read_item(client):
+    create_response = client.post(
+        ITEMS_URL,
+        json={"name": "Sticker", "price": 2.5, "in_stock": True},
+    )
+
+    assert create_response.status_code == 201
+    created = create_response.json()
+    assert created["id"] == 1
+    assert created["name"] == "Sticker"
+
+    read_response = client.get(f"{ITEMS_URL}/{created['id']}")
+
+    assert read_response.status_code == 200
+    assert read_response.json() == created
+
+
+def test_get_unknown_item_returns_404(client):
+    response = client.get(f"{ITEMS_URL}/999")
+
+    assert response.status_code == 404
+
+
+def test_replace_item(client):
+    created = client.post(
+        ITEMS_URL,
+        json={"name": "Mug", "price": 9.0, "in_stock": True},
+    ).json()
+
+    response = client.put(
+        f"{ITEMS_URL}/{created['id']}",
+        json={"name": "Mug v2", "price": 11.0, "in_stock": False},
+    )
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["id"] == created["id"]
+    assert body["name"] == "Mug v2"
+    assert body["price"] == 11.0
+    assert body["in_stock"] is False
+
+
+def test_delete_item(client):
+    created = client.post(
+        ITEMS_URL,
+        json={"name": "Keychain", "price": 4.0, "in_stock": True},
+    ).json()
+
+    delete_response = client.delete(f"{ITEMS_URL}/{created['id']}")
+    assert delete_response.status_code == 204
+
+    follow_up = client.get(f"{ITEMS_URL}/{created['id']}")
+    assert follow_up.status_code == 404
+
+
+def test_create_item_validates_payload(client):
+    response = client.post(
+        ITEMS_URL,
+        json={"name": "", "price": -1.0},
+    )
+
+    assert response.status_code == 422

fastapi_fastkit/fastapi_project_template/fastapi-empty/README.md-tpl

@@ -1,6 +1,6 @@
-# <project_name>
+# Minimal FastAPI Template
 
-> Minimal FastAPI template for rapid prototyping
+> Generated project: **<project_name>** — minimal FastAPI scaffold for rapid prototyping
 
 A minimal FastAPI template that provides the basic structure for building FastAPI applications. Perfect for getting started quickly or as a foundation for more complex projects.
 

fastapi_fastkit/fastapi_project_template/fastapi-empty/pyproject.toml-tpl

@@ -1,7 +1,7 @@
 [project]
 name = "<project_name>"
 version = "0.1.0"
-description = "<description>"
+description = "[FastAPI-fastkit templated] <description>"
 authors = [
     {name = "<author>", email = "<author_email>"},
 ]
@@ -34,6 +34,9 @@ dev = [
     "mypy>=1.15.0",
 ]
 
+[tool.fastapi-fastkit]
+managed = true
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

fastapi_fastkit/fastapi_project_template/fastapi-mcp/pyproject.toml-tpl

@@ -1,7 +1,7 @@
 [project]
 name = "<project_name>"
 version = "0.1.0"
-description = "<description>"
+description = "[FastAPI-fastkit templated] <description>"
 authors = [
     {name = "<author>", email = "<author_email>"},
 ]
@@ -45,6 +45,9 @@ dev = [
     "PyYAML>=6.0.2",
 ]
 
+[tool.fastapi-fastkit]
+managed = true
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"