Skip to content

load_example

load_example

load_example(name: str = 'paris', *, fetched_at: Timestamp | str | None = None) -> tuple[DataFrame, DataFrame]

Return a small canonical (station_info, station_status) pair for examples.

import gbfs_toolkit as gb info, status = gb.load_example() len(info), len(status) (8, 8)

Parameters:

Name Type Description Default
name str

Dataset id (see DATASETS).

"paris"
fetched_at optional

Fetch timestamp stamped on the status frame (default: a fixed 2026-01-05 08:00 UTC, so results are deterministic for doctests).

None
See Also

show_versions : Report installed optional dependencies.

Source code in src/gbfs_toolkit/interfaces/datasets.py
def load_example(
    name: str = "paris", *, fetched_at: pd.Timestamp | str | None = None
) -> tuple[pd.DataFrame, pd.DataFrame]:
    """Return a small canonical ``(station_info, station_status)`` pair for examples.

    >>> import gbfs_toolkit as gb
    >>> info, status = gb.load_example()
    >>> len(info), len(status)
    (8, 8)

    Parameters
    ----------
    name : str, default "paris"
        Dataset id (see `DATASETS`).
    fetched_at : optional
        Fetch timestamp stamped on the status frame (default: a fixed 2026-01-05 08:00 UTC, so
        results are deterministic for doctests).

    See Also
    --------
    [`show_versions`][gbfs_toolkit.show_versions] : Report installed optional dependencies.
    """
    if name not in DATASETS:
        raise ValueError(
            f"unknown dataset {name!r}; choose from {list(DATASETS)}. "
            f"Call load_example() with no argument for the default sample."
        )
    ts = (
        pd.Timestamp(fetched_at) if fetched_at is not None else pd.Timestamp("2026-01-05T08:00:00Z")
    )
    if ts.tzinfo is None:
        ts = ts.tz_localize("UTC")
    info = to_canonical_station_info(_INFO_DOC, system_id=name)
    status = to_canonical_station_status(_STATUS_DOC, system_id=name, fetched_at=ts)
    return info, status