fleetpull 0.1.0__py3-none-any.whl

fleetpull/records/__init__.py

@@ -0,0 +1,19 @@
+# src/fleetpull/records/__init__.py
+"""The records layer: validate response records and shape them into typed
+Polars DataFrames. Per-record validation (``validate_records``) and the
+model-to-DataFrame conversion (``models_to_dataframe``) build the frame; the
+frame readers ``latest_event_time`` (the watermark candidate) and
+``extract_roster_members`` (the feeder's fan-out keys) observe it. The driver
+composes validation with the network client."""
+
+from fleetpull.records.convert import models_to_dataframe
+from fleetpull.records.event_time import latest_event_time
+from fleetpull.records.roster_members import extract_roster_members
+from fleetpull.records.validation import validate_records
+
+__all__: list[str] = [
+    'extract_roster_members',
+    'latest_event_time',
+    'models_to_dataframe',
+    'validate_records',
+]

fleetpull/records/convert.py

@@ -0,0 +1,53 @@
+# src/fleetpull/records/convert.py
+"""The records composition: validated model instances to a DataFrame.
+
+Ties the stage's pure steps together -- derive the schema from the model
+class, flatten every instance against the shared field walk, build the
+frame with the explicit schema, and normalize empty strings. Per-record
+validation (raw dict to model) is separate (``records/validation.py``);
+composing it with the network client is the driver's job, since records
+does not import the client.
+"""
+
+from collections.abc import Sequence
+from typing import Any
+
+import polars as pl
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.records.dataframe import build_dataframe, normalize_empty_strings
+from fleetpull.records.fields import iter_flat_fields
+from fleetpull.records.flatten import flatten_record
+from fleetpull.records.schema import derive_schema
+
+__all__: list[str] = ['models_to_dataframe']
+
+
+def models_to_dataframe(
+    records: Sequence[ResponseModel], model_class: type[ResponseModel]
+) -> pl.DataFrame:
+    """Build a typed, flattened DataFrame from validated model instances.
+
+    Args:
+        records: The validated model instances to materialize. An empty
+            sequence yields a zero-row frame with the model's full schema.
+        model_class: The model class whose fields define the schema;
+            passed explicitly so an empty ``records`` still derives the
+            full column set.
+
+    Returns:
+        A DataFrame with one row per record, flattened columns in
+        declaration order, derived dtypes, and empty strings normalized to
+        null.
+
+    Raises:
+        TypeError: If any field annotation cannot be mapped to a dtype.
+    """
+    schema: dict[str, pl.DataType] = derive_schema(model_class)
+    flat_fields = tuple(iter_flat_fields(model_class))
+    # typing-justified: flattened rows carry heterogeneous model-field values
+    rows: list[dict[str, Any]] = [
+        flatten_record(record=record, flat_fields=flat_fields) for record in records
+    ]
+    dataframe: pl.DataFrame = build_dataframe(rows=rows, schema=schema)
+    return normalize_empty_strings(dataframe)

fleetpull/records/dataframe.py

@@ -0,0 +1,63 @@
+# src/fleetpull/records/dataframe.py
+"""DataFrame construction and missing-value normalization.
+
+Builds a Polars DataFrame from flat rows using an explicit derived schema
+(construct-with-schema, never infer-then-cast), and normalizes empty
+strings to null at the DataFrame boundary -- the models preserve ``""``
+faithfully from the wire, but the frame uses one uniform missing-value
+representation.
+"""
+
+from collections.abc import Sequence
+from typing import Any
+
+import polars as pl
+
+__all__: list[str] = ['build_dataframe', 'normalize_empty_strings']
+
+
+def build_dataframe(
+    # typing-justified: row values are heterogeneous model-field values
+    rows: Sequence[dict[str, Any]],
+    schema: dict[str, pl.DataType],
+) -> pl.DataFrame:
+    """Construct a typed DataFrame from flat rows and a derived schema.
+
+    Args:
+        rows: The flattened ``{column: value}`` rows. An empty sequence is
+            valid and yields a zero-row frame with the right columns and
+            dtypes.
+        schema: The ``{column: dtype}`` map from ``derive_schema``;
+            supplies both the column set/order and the dtypes.
+
+    Returns:
+        A DataFrame whose columns match the schema in declaration order,
+        each at its derived dtype.
+    """
+    if not rows:
+        return pl.DataFrame(schema=schema)
+    return pl.DataFrame(rows, schema=schema)
+
+
+def normalize_empty_strings(dataframe: pl.DataFrame) -> pl.DataFrame:
+    """Replace ``""`` with null on every String column.
+
+    Args:
+        dataframe: The frame to normalize.
+
+    Returns:
+        The frame with empty strings nulled on String columns; other
+        dtypes are untouched (they cannot hold an empty string).
+    """
+    string_columns: list[str] = [
+        name for name, dtype in dataframe.schema.items() if dtype == pl.String()
+    ]
+    if not string_columns:
+        return dataframe
+    return dataframe.with_columns(
+        pl.when(pl.col(column).str.len_chars() == 0)
+        .then(None)
+        .otherwise(pl.col(column))
+        .alias(column)
+        for column in string_columns
+    )

fleetpull/records/event_time.py

@@ -0,0 +1,70 @@
+# src/fleetpull/records/event_time.py
+"""Event-time observation over a records frame: the latest event timestamp.
+
+The watermark candidate a successful watermark fetch produces -- the maximum
+value of the endpoint's event-time column in the fetched records (DESIGN §5,
+observed-data-only). After a fetch is persisted, the orchestrator reads this
+maximum and, if it advances the stored watermark, commits it; the monotonic guard
+and the wrapping into a ``DateWatermark`` are the orchestrator's and the state
+layer's, not this function's -- it returns the raw ``datetime`` so it stays
+ignorant of the cursor type.
+
+A pure leaf over the records frame -- Polars, stdlib ``datetime``, and the timing
+face's ``ensure_utc``. This is the one place a Python ``datetime`` is
+materialized out of a Polars frame into domain code, so it is a
+canonicalization ingress: Polars tags the extracted value
+``zoneinfo.ZoneInfo('UTC')``, not ``datetime.UTC``, and ``ensure_utc``
+converts it so the interior's strict identity guards hold (the canonical-UTC
+doctrine, ``timing/canon.py``). It reads a finished records frame (records'
+output) rather than building one, which is why it sits beside the construction
+modules rather than in ``incremental`` (a deliberately stdlib-only, Polars-free
+leaf) or ``state`` (which the DESIGN keeps free of frame knowledge -- the
+caller hands it the computed value).
+"""
+
+from datetime import datetime
+
+import polars as pl
+
+from fleetpull.timing import ensure_utc
+
+__all__: list[str] = ['latest_event_time']
+
+
+def latest_event_time(frame: pl.DataFrame, event_time_column: str) -> datetime | None:
+    """The maximum value of a records frame's event-time column, canonical UTC.
+
+    Args:
+        frame: The fetched, validated records frame. ``event_time_column`` must be
+            a UTC datetime column.
+        event_time_column: Name of the UTC datetime column to take the maximum of
+            (e.g. ``'located_at'``).
+
+    Returns:
+        The latest (maximum) timestamp in ``event_time_column`` as canonical UTC
+        (``tzinfo is datetime.UTC``, by construction via ``ensure_utc``), or
+        ``None`` when the frame is empty (no observed events, hence no watermark
+        advance).
+
+    Raises:
+        polars.exceptions.ColumnNotFoundError: ``event_time_column`` is absent
+            from ``frame`` -- a caller bug, surfaced unguarded by Polars.
+        TypeError: ``event_time_column``'s maximum is present but not a
+            ``datetime`` (e.g. the column is a date or numeric), which would make
+            an invalid watermark -- raised loud rather than returned.
+        ValueError: ``event_time_column`` is a naive datetime column (from
+            ``ensure_utc`` -- an unzoned event time is ambiguous, never assumed
+            UTC).
+
+    Side Effects:
+        None -- pure function.
+    """
+    maximum = frame.get_column(event_time_column).max()
+    if maximum is None:
+        return None
+    if not isinstance(maximum, datetime):
+        raise TypeError(
+            f'expected a datetime maximum for column {event_time_column!r}, '
+            f'got {type(maximum).__name__}'
+        )
+    return ensure_utc(maximum)

fleetpull/records/fields.py

@@ -0,0 +1,190 @@
+# src/fleetpull/records/fields.py
+"""The shared field walk: classify each model field's annotation and
+enumerate the flat leaf columns a model produces.
+
+Schema derivation and record flattening both consume this one walk, so
+the column NAME a field produces (the type side) and the value PULLED for
+it (the value side) can never drift -- they are computed from a single
+traversal. Nested models flatten with double-underscore-joined column
+names; top-level fields keep their bare name.
+"""
+
+import enum
+import types
+from collections.abc import Iterator
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+from typing import Any, Union, get_args, get_origin
+
+from pydantic import BaseModel
+
+__all__: list[str] = [
+    'FieldKind',
+    'FlatField',
+    'classify_annotation',
+    'iter_flat_fields',
+]
+
+# Column-name join between a nested model and its child. Double, not
+# single: field names already contain single underscores, so a single
+# separator is ambiguous about the level boundary and lets a top-level
+# field collide with a nested one. Module-private Final.
+_NESTING_JOIN: str = '__'
+
+# The closed scalar set. datetime resolves to a tz-aware microsecond
+# dtype downstream and timedelta to a microsecond duration; the others
+# to their obvious Polars scalars.
+_SCALAR_TYPES: frozenset[type] = frozenset(
+    {int, float, str, bool, date, datetime, timedelta}
+)
+
+
+class FieldKind(enum.Enum):
+    """How a resolved field annotation maps to a column.
+
+    A closed set the walk and the schema both dispatch over.
+    """
+
+    SCALAR = enum.auto()
+    ENUM = enum.auto()
+    LIST_OF_SCALAR = enum.auto()
+    NESTED_MODEL = enum.auto()
+
+
+@dataclass(frozen=True, slots=True)
+class FlatField:
+    """One leaf column a model produces.
+
+    Attributes:
+        column: The flattened column name (nested levels double-underscore
+            joined; a top-level field keeps its bare name).
+        kind: The leaf's classification (never NESTED_MODEL -- nesting is
+            resolved away into the column path).
+        resolved: The resolved leaf type -- the scalar ``type`` for SCALAR,
+            the ``Enum`` subclass for ENUM, the inner scalar ``type`` for
+            LIST_OF_SCALAR.
+        path: The attribute-access path from the root model to this leaf,
+            used to pull the value.
+    """
+
+    column: str
+    kind: FieldKind
+    resolved: type
+    path: tuple[str, ...]
+
+
+def classify_annotation(
+    # typing-justified: annotation forms (unions, aliases) are not `type` values
+    annotation: Any,
+    owning_model_name: str,
+    field_name: str,
+) -> tuple[FieldKind, type]:
+    """Reduce a field annotation to a kind and its resolved leaf type.
+
+    Unwraps ``Optional`` / ``T | None``; rejects multi-arm unions. A
+    nested ``BaseModel`` is NESTED_MODEL (the walk recurses); an ``Enum``
+    subclass is ENUM; one of the closed scalars is SCALAR; ``list[scalar]``
+    is LIST_OF_SCALAR. Anything else -- ``Any``, ``dict``, ``Literal``,
+    a list of models, an untyped ``list`` -- is a derivation gap and
+    raises (fail fast; there is no override path yet).
+
+    Args:
+        annotation: The Pydantic ``FieldInfo.annotation`` to classify.
+        owning_model_name: The model class name, for error messages.
+        field_name: The field name, for error messages.
+
+    Returns:
+        ``(kind, resolved)`` -- the nested model class for NESTED_MODEL,
+        the enum class for ENUM, the scalar type for SCALAR, the inner
+        scalar type for LIST_OF_SCALAR.
+
+    Raises:
+        TypeError: When the annotation does not resolve to a supported
+            kind.
+    """
+    # typing-justified: union arms are arbitrary annotation forms
+    non_none: list[Any] = _strip_none_from_union(annotation)
+    if len(non_none) != 1:
+        raise TypeError(
+            f'{owning_model_name}.{field_name}: cannot derive a column from '
+            f'{annotation!r} -- a single non-None type is required, '
+            f'found {len(non_none)}.'
+        )
+    candidate: Any = non_none[0]  # typing-justified: an arbitrary annotation form
+
+    if isinstance(candidate, type) and issubclass(candidate, BaseModel):
+        return (FieldKind.NESTED_MODEL, candidate)
+    if isinstance(candidate, type) and issubclass(candidate, enum.Enum):
+        return (FieldKind.ENUM, candidate)
+    if candidate in _SCALAR_TYPES:
+        return (FieldKind.SCALAR, candidate)
+    if get_origin(candidate) is list:
+        # typing-justified: get_args yields arbitrary annotation forms (typeshed)
+        inner: tuple[Any, ...] = get_args(candidate)
+        if len(inner) == 1 and inner[0] in _SCALAR_TYPES:
+            return (FieldKind.LIST_OF_SCALAR, inner[0])
+        raise TypeError(
+            f'{owning_model_name}.{field_name}: cannot derive a column from '
+            f'{annotation!r} -- only list[scalar] is supported, not lists '
+            f'of models or untyped lists.'
+        )
+    raise TypeError(
+        f'{owning_model_name}.{field_name}: cannot derive a column from '
+        f'{annotation!r} -- unsupported annotation (no schema-override path '
+        f'exists yet; model the shape or narrow the type).'
+    )
+
+
+def iter_flat_fields(model_class: type[BaseModel]) -> Iterator[FlatField]:
+    """Yield one ``FlatField`` per leaf column the model produces.
+
+    Recurses into nested models, double-underscore joining each level into
+    the column name and extending the attribute path. Top-level scalar
+    fields keep their bare name and a single-element path.
+
+    Args:
+        model_class: The model class to walk.
+
+    Yields:
+        One ``FlatField`` per leaf, in declaration order (depth-first).
+
+    Raises:
+        TypeError: Propagated from ``classify_annotation`` for any field
+            whose annotation cannot be resolved.
+    """
+    yield from _walk(model_class, name_prefix=(), path_prefix=())
+
+
+def _walk(
+    model_class: type[BaseModel],
+    name_prefix: tuple[str, ...],
+    path_prefix: tuple[str, ...],
+) -> Iterator[FlatField]:
+    """Depth-first leaf walk; see :func:`iter_flat_fields`."""
+    for field_name, field_info in model_class.model_fields.items():
+        kind, resolved = classify_annotation(
+            annotation=field_info.annotation,
+            owning_model_name=model_class.__name__,
+            field_name=field_name,
+        )
+        path: tuple[str, ...] = (*path_prefix, field_name)
+        if kind is FieldKind.NESTED_MODEL:
+            yield from _walk(
+                model_class=resolved,
+                name_prefix=(*name_prefix, field_name),
+                path_prefix=path,
+            )
+        else:
+            column: str = _NESTING_JOIN.join((*name_prefix, field_name))
+            yield FlatField(column=column, kind=kind, resolved=resolved, path=path)
+
+
+# typing-justified: annotation forms (unions, aliases) in, annotation forms out
+def _strip_none_from_union(annotation: Any) -> list[Any]:
+    """Return the non-``NoneType`` arms of a union, else ``[annotation]``."""
+    origin: Any = get_origin(annotation)  # typing-justified: typeshed returns Any
+    if origin is Union or origin is types.UnionType:
+        return [
+            argument for argument in get_args(annotation) if argument is not type(None)
+        ]
+    return [annotation]

fleetpull/records/flatten.py

@@ -0,0 +1,54 @@
+# src/fleetpull/records/flatten.py
+"""Record flattening: a model instance to a flat ``{column: value}`` row.
+
+The value side of the shared field walk -- it pulls each leaf's value by
+the attribute path the same walk produced, so column names and values are
+guaranteed aligned. A ``None`` nested block yields ``None`` for all of its
+leaf columns; an enum value is reduced to its plain string.
+"""
+
+from collections.abc import Iterable
+from typing import Any
+
+from pydantic import BaseModel
+
+from fleetpull.records.fields import FieldKind, FlatField
+
+__all__: list[str] = ['flatten_record']
+
+
+def flatten_record(
+    record: BaseModel, flat_fields: Iterable[FlatField]
+) -> dict[str, Any]:  # typing-justified: model-field values are heterogeneous
+    """Pull one flat row of values from a model instance.
+
+    Args:
+        record: The validated model instance to flatten.
+        flat_fields: The leaf fields (from ``iter_flat_fields`` on the
+            record's class), reused across every record of a batch.
+
+    Returns:
+        A ``{column: value}`` row. A missing (``None``) nested block
+        yields ``None`` for each of its columns; enum values reduce to
+        ``str``; scalars, datetimes, and list values pass through.
+    """
+    row: dict[str, Any] = {}  # typing-justified: heterogeneous model-field values
+    for flat_field in flat_fields:
+        value: Any = _pull(record, flat_field.path)  # typing-justified: see _pull
+        if value is not None and flat_field.kind is FieldKind.ENUM:
+            # All current enums are StrEnum, so str(member) is the wire
+            # value ('active'), not 'VehicleStatus.ACTIVE'.
+            value = str(value)
+        row[flat_field.column] = value
+    return row
+
+
+# typing-justified: getattr walks arbitrary model fields; the value is untyped
+def _pull(record: BaseModel, path: tuple[str, ...]) -> Any:
+    """Walk the attribute path; short-circuit to ``None`` on a null block."""
+    current: Any = record  # typing-justified: intermediate attribute-walk value
+    for attribute in path:
+        if current is None:
+            return None
+        current = getattr(current, attribute)
+    return current

fleetpull/records/roster_members.py

@@ -0,0 +1,74 @@
+# src/fleetpull/records/roster_members.py
+"""Roster-member extraction over a records frame: a column's distinct values as
+strings.
+
+The roster members a feeder listing produces -- the distinct values of one column of
+the feeder's validated frame, stringified for use as roster members and URL-path
+fan-out values. The refresh path reads this off the listed-and-validated feeder frame
+and hands the members to ``reconcile``; mapping a member to anything else (a VIN) is
+never needed -- the value is opaque.
+
+A pure-ish leaf over the records frame -- Polars, stdlib logging, nothing internal;
+it reads a finished records frame rather than building one, so it sits with the
+records-layer extractors. A missing column raises ``ValueError`` -- a wiring bug
+(the roster definition names a column the feeder frame lacks) the exception
+hierarchy leaves to stdlib. Null and empty-string values are *filtered, loudly*
+rather than raised: both are unfetchable members by construction (a null carries
+no id; an empty string renders an unbuildable URL path), and excluding one garbage
+record beats converting it into an outage for every other member's fan-out. The
+filter logs a warning with the column and counts, so a provider emitting garbage
+ids is visible without being fatal.
+"""
+
+import logging
+
+import polars as pl
+
+__all__: list[str] = ['extract_roster_members']
+
+logger = logging.getLogger(__name__)
+
+
+def extract_roster_members(frame: pl.DataFrame, column: str) -> set[str]:
+    """The distinct fetchable values of a frame column, as strings.
+
+    Reads ``column`` and returns its distinct values stringified (a numeric id
+    becomes its decimal string, ready for a roster member and a URL-path value).
+    A roster is an unordered set, so the result is a ``set`` and extraction order
+    is not preserved. Null and empty-string values are filtered with a warning --
+    unfetchable by construction, excluded rather than fatal -- so the returned
+    members are exactly the fan-out-usable ones.
+
+    Args:
+        frame: The fetched, validated feeder frame.
+        column: Name of the column whose distinct values are the members (e.g.
+            ``'vehicle_id'``).
+
+    Returns:
+        The distinct non-null, non-empty values of ``column`` as a set of
+        strings; an empty set when the frame is empty or holds no usable value.
+
+    Raises:
+        ValueError: ``column`` is absent from ``frame`` -- a wiring bug (the
+            roster definition names a column the feeder frame lacks), left to
+            stdlib rather than the operational hierarchy, which this leaf cannot
+            give provider context.
+
+    Side Effects:
+        Logs a warning when null or empty-string values were filtered.
+    """
+    if column not in frame.columns:
+        raise ValueError(f'roster source column {column!r} is not in the frame')
+    series = frame.get_column(column)
+    null_row_count = series.null_count()
+    stringified = series.drop_nulls().cast(pl.String)
+    empty_row_count = int((stringified.str.len_chars() == 0).sum())
+    if null_row_count or empty_row_count:
+        logger.warning(
+            'filtered unfetchable members from roster source column %r: '
+            '%d null and %d empty-string value(s) excluded',
+            column,
+            null_row_count,
+            empty_row_count,
+        )
+    return {value for value in stringified.unique().to_list() if value != ''}

fleetpull/records/schema.py

@@ -0,0 +1,73 @@
+# src/fleetpull/records/schema.py
+"""Polars schema derivation: a model class to a ``{column: dtype}`` map.
+
+Walks the shared field enumeration (``records/fields.py``) and maps each
+leaf to a Polars dtype: ``int``/``float``/``str``/``bool`` to their
+obvious scalars, ``date`` to a calendar-date column (a DATE-ONLY wire
+value carries no instant to recover -- the Motive users ``joined_at``
+precedent), ``datetime`` to tz-aware microsecond UTC, ``timedelta``
+to a microsecond ``Duration``, enums to ``String``, ``list[scalar]`` to
+``List`` of the inner dtype. Depends only on the model class, not on any
+data, so the schema is computable before a record is fetched. A leaf the
+map cannot place raises (fail fast); there is no override path yet.
+"""
+
+from datetime import date, datetime, timedelta
+
+import polars as pl
+from pydantic import BaseModel
+
+from fleetpull.records.fields import FieldKind, FlatField, iter_flat_fields
+
+__all__: list[str] = ['derive_schema']
+
+# The closed scalar -> Polars dtype map. datetime is tz-aware microsecond
+# UTC and timedelta a microsecond Duration, so every temporal column
+# carries a uniform, parquet-friendly type.
+_SCALAR_TO_POLARS: dict[type, pl.DataType] = {
+    int: pl.Int64(),
+    float: pl.Float64(),
+    str: pl.String(),
+    bool: pl.Boolean(),
+    date: pl.Date(),
+    datetime: pl.Datetime(time_unit='us', time_zone='UTC'),
+    timedelta: pl.Duration(time_unit='us'),
+}
+
+
+def derive_schema(model_class: type[BaseModel]) -> dict[str, pl.DataType]:
+    """Derive the Polars schema for a model's flattened columns.
+
+    Args:
+        model_class: The model whose flattened leaves define the columns.
+
+    Returns:
+        An insertion-ordered ``{column: dtype}`` map in field declaration
+        order. Scalars, datetimes, and timedeltas map directly; enums map
+        to ``pl.String``; ``list[scalar]`` maps to ``pl.List`` of the
+        inner scalar's dtype.
+
+    Raises:
+        TypeError: If a leaf annotation has no dtype mapping.
+        ValueError: If two leaves resolve to one column name -- a
+            structural impossibility the double-underscore join prevents,
+            raised as a guard that should never fire.
+    """
+    schema: dict[str, pl.DataType] = {}
+    for flat_field in iter_flat_fields(model_class):
+        if flat_field.column in schema:
+            raise ValueError(
+                f'{model_class.__name__}: duplicate flattened column '
+                f'{flat_field.column!r} -- two fields resolve to one name.'
+            )
+        schema[flat_field.column] = _leaf_to_dtype(flat_field)
+    return schema
+
+
+def _leaf_to_dtype(flat_field: FlatField) -> pl.DataType:
+    """Map one resolved leaf to its Polars dtype."""
+    if flat_field.kind is FieldKind.ENUM:
+        return pl.String()
+    if flat_field.kind is FieldKind.LIST_OF_SCALAR:
+        return pl.List(_SCALAR_TO_POLARS[flat_field.resolved])
+    return _SCALAR_TO_POLARS[flat_field.resolved]

fleetpull/records/validation.py

@@ -0,0 +1,62 @@
+# src/fleetpull/records/validation.py
+"""Per-record validation: raw response dicts to typed model instances.
+
+Validates each record dict into the endpoint's response model. Pydantic's
+lax coercion (the model is non-strict) lands wire types; field-level
+wire-cleaning, when an endpoint needs it, lives on the model as a
+``field_validator(mode='before')``, not here. Validation fails fast and
+loud on the first bad record, with safe-to-log context.
+"""
+
+from collections.abc import Sequence
+
+from pydantic import ValidationError
+
+from fleetpull.exceptions import ProviderResponseError
+from fleetpull.model_contract import ResponseModel
+from fleetpull.vocabulary import JsonObject
+
+__all__: list[str] = ['validate_records']
+
+
+def validate_records[ModelT: ResponseModel](
+    records: Sequence[JsonObject], model_class: type[ModelT]
+) -> list[ModelT]:
+    """Validate raw record dicts into typed model instances.
+
+    Args:
+        records: The raw record objects (a page's ``records``).
+        model_class: The response model to validate each record into --
+            bound to ``ResponseModel`` so every validated record carries the
+            package's response-model config policy.
+
+    Returns:
+        The validated model instances, one per input record, in order.
+
+    Raises:
+        ProviderResponseError: On the first record that fails validation,
+            naming the model, the record's position, and which fields
+            failed and how -- never the raw field values, so the error is
+            safe to log.
+    """
+    validated: list[ModelT] = []
+    for index, record in enumerate(records):
+        try:
+            validated.append(model_class.model_validate(record))
+        except ValidationError as error:
+            raise ProviderResponseError(
+                detail=(
+                    f'{model_class.__name__} record {index} failed '
+                    f'validation: {_safe_summary(error)}'
+                )
+            ) from None
+    return validated
+
+
+def _safe_summary(error: ValidationError) -> str:
+    """Summarize a ValidationError without exposing raw field values."""
+    parts: list[str] = [
+        f'{".".join(str(item) for item in entry["loc"])} ({entry["type"]})'
+        for entry in error.errors()
+    ]
+    return '; '.join(parts)

fleetpull/resources/__init__.py

@@ -0,0 +1,10 @@
+# src/fleetpull/resources/__init__.py
+"""Packaged data resources shipped inside the wheel.
+
+Holds ``config.example.yaml`` -- the annotated starter configuration a
+user materializes with ``fleetpull init-config`` (read through
+``importlib.resources`` so it resolves in both a wheel and an editable
+install). This package carries data, not code; it exports nothing.
+"""
+
+__all__: list[str] = []