Module

data._mapping

Row-to-dataclass mapping with type coercion.

Converts raw database rows (tuples or dicts) into typed frozen dataclasses. Uses dataclass field introspection — no metaclass magic, no descriptors.

Type coercion handles the mismatch between database drivers (SQLite returns strings for some column types) and Python dataclass annotations. Fields annotated asint will coerce string values like "45" to 45, and empty strings to0.

4Functions

Functions

_build_coercion_map 1 dict[str, type | None] ▼
Build a {field_name: target_type} map for coercible fields. Returns ``None`` f…
def _build_coercion_map(cls: type) -> dict[str, type | None]

Build a {field_name: target_type} map for coercible fields.

ReturnsNonefor fields that don't need coercion (complex types, generics, etc.).

Parameters
Name Type Description
cls type
Returns
dict[str, type | None]
_coerce 2 Any ▼
Coerce a single value to the target type, if needed.
def _coerce(value: Any, target: type | None) -> Any
Parameters
Name Type Description
value Any
target type | None
Returns
Any
map_row 2 T ▼
Map a dict-like row to a frozen dataclass instance. Only passes keys that matc…
def map_row(cls: type[T], row: dict[str, Any]) -> T

Map a dict-like row to a frozen dataclass instance.

Only passes keys that match dataclass fields. Extra columns are silently ignored (SELECT * is fine even if the dataclass has fewer fields).

Values are coerced to match field annotations:int, float, bool, and strfields handle driver type mismatches automatically. Empty strings inint/float columns coerce to 0/0.0.

RaisesTypeErrorif required fields are missing from the row.

Parameters
Name Type Description
cls type[T]
row dict[str, Any]
Returns
T
map_rows 2 list[T] ▼
Map a list of dict-like rows to frozen dataclass instances.
def map_rows(cls: type[T], rows: list[dict[str, Any]]) -> list[T]
Parameters
Name Type Description
cls type[T]
rows list[dict[str, Any]]
Returns
list[T]