Przejdź do treści
Biblioteka skilli
Programowanie · Przegląd i audyt

fastapi-pydantic-patterns

/fastapi-pydantic-patterns

Pilnuje konwencji FastAPI i pydantic v2: modele parametrów zapytania, listy parametrów, typy Annotated, koperty odpowiedzi i czyste błędy 4xx.

Repozytorium
agent-kit ↗
Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Pilnuje konwencji FastAPI i pydantic v2: modele parametrów zapytania, listy parametrów, typy Annotated, koperty odpowiedzi i czyste błędy 4xx.

Wyzwalacze z opisu

add an endpointadd a filter
Oryginalny opis (EN)

Conventions for FastAPI + pydantic v2 services - query-parameter models with a `.make()` factory, list params that accept both `?id=1&id=2` and `?id=1,2`, reusable Annotated types, response envelopes, validators that return clean 4xx errors, settings, and ORM-to-response conversion. Use when adding or reviewing endpoints, request/response models, validators or custom types in a FastAPI app, even if the user only says "add an endpoint" or "add a filter".

Jak działa

  1. 1. Where each parameter goes
  2. 2. Query model with a .make() factory
  3. 3. Endpoint
  4. 4. Reusable Annotated types (core/datatypes.py)
  5. 5. Request and response models
  6. 6. Validators that return a clean 4xx
  7. 7. Settings
  8. 8. Enums and mixins
  9. 9. ORM row → response model
  10. Checklist for a new endpoint
Sekcje z nagłówków SKILL.md, w oryginale · 327 linii, 1 151 słów
Podgląd SKILL.md
---
name: fastapi-pydantic-patterns
description: Conventions for FastAPI + pydantic v2 services - query-parameter models with a `.make()` factory, list params that accept both `?id=1&id=2` and `?id=1,2`, reusable Annotated types, response envelopes, validators that return clean 4xx errors, settings, and ORM-to-response conversion. Use when adding or reviewing endpoints, request/response models, validators or custom types in a FastAPI app, even if the user only says "add an endpoint" or "add a filter".
---

# FastAPI + pydantic v2 patterns

These conventions keep endpoints small and predictable: parsing and validation live in
models, the endpoint only wires dependencies, calls the CRUD layer and wraps the result.
Follow them unless the project already has a different, consistent convention. In that
case follow the project and say so.

## 1. Where each parameter goes

| Parameter | Where |
|---|---|
| Path parameter | Endpoint signature: `order_id: int` |
| One or two simple query params | Endpoint signature: `limit: Annotated[int, Query(ge=1, le=500)] = 100` |
| Several query params, lists, or cross-field rules | A query model (section 2) |
| Request body | A pydantic model in the signature (section 5) |

Don't add list parsing or validators to fields that don't need them.

## 2. Query model with a `.make()` factory

Plain type hints on the model, FastAPI `Query()` metadata in a static factory. Validators
then run on a normal `BaseModel`, and FastAPI still documents every parameter in OpenAPI.

```python
from datetime import datetime
from typing import Annotated, Optional

from fastapi import Query
from pydantic import BaseModel, NonNegativeInt, field_validator, model_validator

from core.validators import check_date_range, split_csv


class OrderQuery(BaseModel):
    warehouse_id: Optional[list[int]] = None
    status: Optional[list[str]] = None
    created_from: Optional[datetime] = None
    created_till: Optional[datetime] = None
    limit: int = 1000
    offset: int = 0

    _split = field_validator("warehouse_id", "status", mode="before")(split_csv)
    _dates = model_validator(mode="after")(check_date_range("created_from", "created_till"))

    @staticmethod
    def make(
        warehouse_id: Annotated[Optional[list[str]], Query(alias="warehouse_ids", description="Filter by warehouse")] = None,
        status: Annotated[Optional[list[str]], Query()] = None,
        created_from: Annotated[Optional[datetime], Query()] = None,
        created_till: Annotated[Optional[datetime], Query()] = None,
        limit: Annotated[NonNegativeInt, Query(le=10_000)] = 1000,
        offset: Annotated[NonNegativeInt, Query()] = 0,
    ) -> "OrderQuery":
        return OrderQuery(
            warehouse_id=warehouse_id, status=status,
            created_from=created_from, created_till=created_till,
            limit=limit, offset=offset,
        )
```

Name the dependency `args` in every endpoint, so handlers read the same way.

`.make()` lets you use aliases (`warehouse_ids` in the URL, `warehouse_id` in code, or
both singular and plural names) and keep per-parameter OpenAPI metadata next to
model-level validators. Test both `?x=1,2` and `?x=1&x=2`.

### List parameters: accept both spellings

Clients send lists as `?status=new&status=paid` or `?status=new,paid`. Accept both with
one `mode="before"` validator, so neither form silently loses values:

```python
# core/validators.py
def split_csv(value):
    """['1,2', '3'] or '1,2,3' -> ['1', '2', '3']; leaves None and non-strings alone."""
    if value is None:
        return value
    if isinstance(value, (str, int)):
        value = [value]
    out: list[str] = []
    for item in value:
        out += [part.strip() for part in str(item).split(",") if part.strip()]
    return out
```

Then let pydantic coerce the strings to `int` etc. as usual.

## 3. Endpoint

```python
from typing import Annotated

from fastapi import APIRouter, Depends
from sqlalchemy.orm import Session

from core.auth import Credentials, get_credentials
from core.db import get_db
from core.logger import logger

router = APIRouter(prefix="/orders", tags=["Orders"])


@router.get("", response_model=OrderListResponse)
def list_orders(
    db: Annotated[Session, Depends(get_db)],
    args: Annotated[OrderQuery, Depends(OrderQuery.make)],
    credentials: Annotated[Credentials, Depends(get_credentials)],
):
    """Shown in OpenAPI."""
    logger.info(args.model_dump_json())
    args.warehouse_id = restrict_to_allowed(args.warehouse_id, credentials)
    rows, total = crud.list_orders(db, args)
    return OrderListResponse(data=rows, total=total)
```

- Use `Annotated[..., Depends(...)]` for every dependency.
- Authorization filtering happens before the query, not after it.
- No business logic in the endpoint beyond that.

## 4. Reusable Annotated types (`core/datatypes.py`)

```python
from datetime import datetime, time, timezone
from typing import Annotated

from pydantic import AfterValidator, BeforeValidator, Field, PlainSerializer


def _to_utc(x: datetime) -> datetime:
    return x.replace(tzinfo=timezone.utc) if x.tzinfo is None else x.astimezone(timezone.utc)

# input
DatetimeUTC = Annotated[datetime, AfterValidator(_to_utc)]

# output
DatetimeOutUTC = Annotated[datetime, AfterValidator(_to_utc), PlainSerializer(lambda x: x.isoformat())]

# validation
Sku = Annotated[str, Field(pattern=r"^[A-Z0-9]{4,12}$")]
Ratio = Annotated[float, Field(ge=0, le=1)]

# transformation
Rounded3 = Annotated[float, AfterValidator(lambda x: round(x, 3))]
ClampedRatio = Annotated[float, AfterValidator(lambda x: round(max(0.0, min(1.0, x)), 3))]
WholeHour = Annotated[time, AfterValidator(lambda x: x.replace(minute=0, second=0, microsecond=0))]
TruncatedInt = Annotated[int, BeforeValidator(lambda x: int(float(x)))]
```

```python
class StockLevel(BaseModel):
    sku: Sku
    updated_at: Optional[DatetimeOutUTC] = None
    fill_ratio: ClampedRatio
```

## 5. Request and response models

```python
from typing import Any, Optional

from pydantic import BaseModel, ConfigDict


class OrderUpdate(BaseModel):
    note: Optional[str] = None
    status: Optional[str] = None


class OrderOut(BaseModel):
    model_config = ConfigDict(from_attributes=True)

    id: int
    status: str
    created_at: Optional[DatetimeOutUTC] = None


class Envelope(BaseModel):
    reason: str = "ok"
    message: Optional[str] = None
    data: Optional[Any] = None


class OrderListResponse(Envelope):
    total: int
    data: list[OrderOut]
```

In pydantic v2 an `Optional[X]` field without a default is **required**. Every optional
field needs an explicit `= None`. See the `pydantic-v2-migration` skill.

## 6. Validators that return a clean 4xx

Raise a project exception with a status code from validators instead of a bare
`ValueError`, so the exception handler returns the same envelope as every other error.

```python
# core/exceptions.py
from typing import Any

from starlette import status


class RequestValidationFailed(Exception):
    def __init__(self, message: str, *, reason: str = "invalid_field",
                 data: Any = None, status_code: int = status.HTTP_400_BAD_REQUEST):
        self.message, self.reason, self.data, self.status_code = message, reason, data, status_code
```

```python
# core/validators.py
def check_date_range(start: str, end: str):
    """Model-level 'after' validator factory: end must not be before start."""
    def validator(model):
        a, b = getattr(model, start), getattr(model, end)
        if a and b and b < a:
            raise RequestValidationFailed(f"{end} < {start}", status_code=422)
        return model
    return validator
```

In pydantic v2 an `after` model validator receives the **model instance** and must return
it. Don't use the v1-style `(cls, values)` signature.

For a JSON string stored in a column, parse it in a `mode="before"` field validator:

```python
class ShipmentOut(BaseModel):
    items: list[ItemOut]

    @field_validator("items", mode="before")
    @classmethod
    def parse_json(cls, v):
        return json.loads(v) if isinstance(v, str) else v
```

## 7. Settings

```python
from typing import Optional

from pydantic import model_validator
from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    database_dsn: Optional[str] = None
    database_host: Optional[str] = None
    database_user: Optional[str] = None
    database_password: Optional[str] = None
    database_name: Optional[str] = None
    database_port: int = 5432
    log_level: str = "INFO"

    @model_validator(mode="after")
    def build_dsn(self):
        if self.database_dsn is None:
            self.database_dsn = (
                f"postgresql://{self.database_user}:{self.database_password}"
                f"@{self.database_host}:{self.database_port}/{self.database_name}"
            )
        return self


settings = Settings()  # once, at module level
```

Fill missing parts from your secret store, for example a parameter store, inside the
validator when the environment variables are absent.

## 8. Enums and mixins

```python
class SortDirection(str, Enum):
    asc = "asc"
    desc = "desc"

sort: Annotated[SortDirection, Query()] = SortDirection.asc
```

Compose response models from small mixins instead of copying fields:

```python
class WithWarehouse(BaseModel):
    warehouse: WarehouseRef

class WithCapacity(BaseModel):
    capacity: Optional[int] = None

class ZoneOut(ZoneBase, WithWarehouse, WithCapacity):
    pass
```

## 9. ORM row → response model

Keep the database shape and the API shape separate. Load the row into an ORM-shaped model,
then convert it explicitly:

```python
class OrderRow(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: int
    status: str
    payload: dict

    @field_validator("payload", mode="before")
    @classmethod
    def parse_json(cls, v):
        return json.loads(v) if isinstance(v, str) else v

    def to_out(self) -> OrderOut:
        return OrderOut(id=self.id, status=self.status, **self.payload)


def list_orders(db: Session, args: OrderQuery) -> list[OrderOut]:
    return [OrderRow.model_validate(r).to_out() for r in query(db, args).all()]
```

## Checklist for a new endpoint

- Parameters placed per section 1. Lists accept both spellings.
- Every `Optional` field has `= None`.
- Validators raise the project exception with a 4xx, not `HTTPException` and not a bare `ValueError`.
- `response_model` is set, and the response uses the envelope.
- Authorization filtering happens before the query.
- There is a test for each new validator and for both list spellings.

Wersje

W bazie nie ma innych skilli o nazwie fastapi-pydantic-patterns.

Migawka bazy z 13.11.2026 · wersja paczki 71a153ae9ae5 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100pydantic-v2
    Pomaga pisać, refaktoryzować i migrować z v1 modele Pydantic v2: walidatory, serializację, pola Decimal dla kwot i schematy żądań oraz odpowiedzi FastAPI w Pythonie 3.10+.
  • 100pydantic-v2
    Pomaga pisać, refaktoryzować i migrować z v1 modele Pydantic v2: walidatory, serializację, pola Decimal dla kwot i schematy żądań oraz odpowiedzi FastAPI w Pythonie 3.10+.
  • 95fastapi-validation
    Opisuje walidację w FastAPI z modelami Pydantic, do budowy typobezpiecznych API z solidną walidacją żądań i odpowiedzi.
  • 100fastapi-patterns
    Buduje i przegląda usługi FastAPI: układ projektu, konfigurację, schematy, zależności, uwierzytelnianie 401 i 403 oraz testy.
  • 100fastapi
    Daje wytyczne i wzorce dla projektów FastAPI w pracy z AI: wzorce asynchroniczne, modele Pydantic, wstrzykiwanie zależności i zasady OpenAPI.
  • 100python-fastapi-pydantic
    Buduje asynchroniczne REST API w FastAPI z walidacją Pydantic i dokumentacją OpenAPI.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.