models¶
models
¶
Canonical data model for GBFS feeds: the stable contract every other module (and every downstream research script) builds on.
The whole point of the toolkit is that ingestion (which varies across GBFS 1.x/2.x/3.x) is normalised once into these version-independent frames, and audit / panels then operate purely on the canonical schema. Downstream code should depend on these column names, never on raw GBFS JSON.
SchemaError
¶
SchemaError(message: str, *, missing: list[str] | None = None, present: list[str] | None = None, what: str | None = None)
Bases: GBFSValidationError, ValueError
Raised when a frame does not satisfy the canonical schema.
Subclasses both GBFSValidationError (so
except GBFSError catches it) and ValueError (backward compatibility).
For schema-mismatch cases the exception also carries structured fields, so an
automated pipeline can branch on them without parsing the message: missing (the
absent columns), present (the columns that were supplied), and what (the
operation that required them). They are None for other validation failures.
See Also
validate_schema : Raises this on failure.
GBFSValidationError : The feed-level validation error.
Source code in src/gbfs_toolkit/core/models.py
require_columns
¶
require_columns(df: DataFrame, columns: list[str], *, what: str) -> None
Raise a didactic SchemaError if df is missing any of columns.
The message names the missing columns, lists the columns that were present, gives the
likely cause, and points to a concrete fix, so the most common user error (passing a
frame that did not come from a to_canonical_* normaliser) explains itself.
Source code in src/gbfs_toolkit/core/models.py
validate_schema
¶
Assert a frame still obeys a canonical schema, then return it (for chaining).
Use after slicing/grouping/mutating a canonical frame (e.g. before appending to the
Parquet lake) to fail fast with a clear SchemaError instead of corrupting the
dataset. schema is one of SCHEMAS ("station_status", "vehicle_status"…).
See Also
coerce_schema : Coerce to the schema instead.
SchemaError : Raised on validation failure.
Source code in src/gbfs_toolkit/core/models.py
coerce_schema
¶
Cast a frame's columns to the canonical dtypes for schema (nullable ints/bools, UTC).
Best-effort: only columns present are touched; unparseable values become pd.NA/NaT.
Handy after reading frames from CSV or a third-party source before feeding the toolkit.
See Also
validate_schema : Validate without coercing.
SchemaError : Raised on an irreconcilable schema.