Skip to content

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
def __init__(
    self,
    message: str,
    *,
    missing: list[str] | None = None,
    present: list[str] | None = None,
    what: str | None = None,
) -> None:
    super().__init__(message)
    self.missing = missing
    self.present = present
    self.what = what

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
def require_columns(df: pd.DataFrame, columns: list[str], *, what: str) -> None:
    """Raise a didactic [`SchemaError`][gbfs_toolkit.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.
    """
    missing = [c for c in columns if c not in df.columns]
    if not missing:
        return
    present = list(df.columns)
    message = (
        f"{what}: missing required column(s) {missing}.\n"
        f"  present columns: {present}\n"
        f"  likely cause: this frame did not come from a to_canonical_* normaliser, or an "
        f"optional GBFS field is absent for this system.\n"
        f"  fix: normalise the raw feed with the matching to_canonical_* function, or add the "
        f"column(s) before calling. Canonical schema: {_DATA_MODEL_URL}"
    )
    raise SchemaError(message, missing=missing, present=present, what=what)

validate_schema

validate_schema(df: DataFrame, schema: str) -> DataFrame

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
def validate_schema(df: pd.DataFrame, schema: str) -> pd.DataFrame:
    """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`][gbfs_toolkit.SchemaError] instead of corrupting the
    dataset. ``schema`` is one of [`SCHEMAS`][gbfs_toolkit.SCHEMAS] (``"station_status"``, ``"vehicle_status"``…).

    See Also
    --------
    [`coerce_schema`][gbfs_toolkit.coerce_schema] : Coerce to the schema instead.
    [`SchemaError`][gbfs_toolkit.SchemaError] : Raised on validation failure.
    """
    require_columns(df, _schema_columns(schema), what=f"validate_schema({schema!r})")
    return df

coerce_schema

coerce_schema(df: DataFrame, schema: str) -> DataFrame

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.

Source code in src/gbfs_toolkit/core/models.py
def coerce_schema(df: pd.DataFrame, schema: str) -> pd.DataFrame:
    """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`][gbfs_toolkit.validate_schema] : Validate without coercing.
    [`SchemaError`][gbfs_toolkit.SchemaError] : Raised on an irreconcilable schema.
    """
    out = df.copy()
    for col in _schema_columns(schema):
        if col not in out.columns:
            continue
        if col in _DATETIME_COLUMNS:
            out[col] = pd.to_datetime(out[col], utc=True, errors="coerce")
        elif col in _CANONICAL_DTYPES:
            dtype = _CANONICAL_DTYPES[col]
            if dtype in ("Int64", "float64"):
                out[col] = pd.to_numeric(out[col], errors="coerce").astype(dtype)
            else:
                out[col] = out[col].astype(dtype)
    return out