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

fastapi_fastkit/fastapi_project_template/fastapi-dockerized/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>"},
 ]
@@ -41,6 +41,9 @@ dev = [
     "setuptools-scm>=8.1.0",
 ]
 
+[tool.fastapi-fastkit]
+managed = true
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/.env-tpl

@@ -0,0 +1,2 @@
+SECRET_KEY=changethis
+ENVIRONMENT=development

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/.gitignore-tpl

@@ -0,0 +1,31 @@
+.idea
+.ipynb_checkpoints
+.mypy_cache
+.vscode
+__pycache__
+.pytest_cache
+htmlcov
+dist
+site
+.coverage*
+coverage.xml
+.netlify
+test.db
+log.txt
+Pipfile.lock
+env3.*
+env
+docs_build
+site_build
+venv
+.venv
+docs.zip
+archive.zip
+
+# vim temporary files
+*~
+.*.sw?
+.cache
+
+# macOS
+.DS_Store

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/README.md-tpl

@@ -0,0 +1,128 @@
+# FastAPI Domain Starter
+
+Modern, domain-oriented FastAPI starter — the recommended default for
+medium-sized API projects.
+
+> Generated project: **<project_name>** — <description>
+
+## When to choose this starter
+
+Pick this template when you want:
+
+- A **domain-oriented layout** (one folder per business concept under
+  `src/app/domains/`) rather than the layered `routes/ + crud/ + schemas/`
+  split. Domains scale better as the API grows.
+- A clear separation between **transport** (`router.py`), **business
+  logic** (`service.py`), and **data access** (`repository.py`) so each
+  layer can evolve independently.
+- A **`pyproject.toml`-first** project (PEP 621) compatible with `uv`,
+  `pdm`, or `poetry` out of the box — no `setup.py` to maintain.
+- Sensible defaults for settings, testing, formatting, and a built-in
+  `/health` probe.
+
+If you only need a quick CRUD demo, start with `fastapi-default`. If you
+need PostgreSQL, start with `fastapi-psql-orm`. If you want a single-file
+sandbox, use `fastapi-single-module`.
+
+## Project structure
+
+```
+.
+├── README.md
+├── pyproject.toml
+├── .env
+├── .gitignore
+├── scripts/
+│   ├── format.sh
+│   ├── lint.sh
+│   ├── run-server.sh
+│   └── test.sh
+├── src/
+│   └── app/
+│       ├── main.py             # FastAPI app entry point
+│       ├── core/
+│       │   └── config.py       # pydantic-settings configuration
+│       ├── db/
+│       │   └── memory.py       # in-memory store stand-in for a real DB
+│       ├── api/
+│       │   ├── router.py       # aggregates health + every domain router
+│       │   └── health.py       # GET /health
+│       └── domains/
+│           └── items/          # example domain (CRUD over an item entity)
+│               ├── models.py       # entity dataclass
+│               ├── schemas.py      # API I/O schemas (pydantic)
+│               ├── repository.py   # data access layer
+│               ├── service.py      # business logic
+│               └── router.py       # FastAPI router for the domain
+└── tests/
+    ├── conftest.py
+    ├── test_health.py
+    └── test_items.py
+```
+
+The recipe for adding a new domain is:
+
+1. Create `src/app/domains/<your_domain>/`.
+2. Mirror the `items` layout (`models.py`, `schemas.py`, `repository.py`,
+   `service.py`, `router.py`).
+3. Register the router in `src/app/api/router.py`.
+4. Add tests under `tests/test_<your_domain>.py`.
+
+## Running the app
+
+```bash
+# create a virtualenv and install dependencies
+$ uv sync   # or: pip install -e ".[dev]"
+
+# launch the dev server
+$ bash scripts/run-server.sh
+# or directly:
+$ uvicorn src.app.main:app --reload
+```
+
+API docs are then served at:
+
+- Swagger UI: <http://127.0.0.1:8000/docs>
+- ReDoc:      <http://127.0.0.1:8000/redoc>
+
+## API endpoints
+
+| Method | Endpoint                  | Description                  |
+|--------|---------------------------|------------------------------|
+| GET    | `/api/v1/health`          | Liveness probe               |
+| GET    | `/api/v1/items`           | List items                   |
+| GET    | `/api/v1/items/{item_id}` | Read a single item           |
+| POST   | `/api/v1/items`           | Create an item               |
+| PUT    | `/api/v1/items/{item_id}` | Replace an item              |
+| DELETE | `/api/v1/items/{item_id}` | Delete an item               |
+
+## Running tests
+
+```bash
+$ bash scripts/test.sh
+# or directly:
+$ pytest
+```
+
+## Configuration
+
+`src/app/core/config.py` reads settings from environment variables (or a
+local `.env` file). The provided `.env` only sets a placeholder
+`SECRET_KEY` — replace it before deploying.
+
+## Project Origin
+
+This project was created from the **`fastapi-domain-starter`** template
+shipped with [FastAPI-fastkit](https://github.com/bnbong/FastAPI-fastkit).
+
+The `FastAPI-fastkit` is an open-source project that helps Python and
+FastAPI beginners quickly set up a FastAPI-based application development
+environment in a framework-like structure.
+
+For an end-to-end walkthrough of this template — the generated tree,
+the bundled `items` example, and how to add your next domain — see the
+[**Domain-oriented Project tutorial**](https://bnbong.github.io/FastAPI-fastkit/tutorial/domain-starter/).
+
+### Template Information
+- Template creator: [bnbong](mailto:bbbong9@gmail.com)
+- FastAPI-fastkit project maintainer: [bnbong](mailto:bbbong9@gmail.com)

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)