Skip to content

systems_catalog

systems_catalog

systems_catalog(source: str | None = None, *, timeout: int = 30, use_cache: bool = True, refresh: bool = False) -> DataFrame

Load the MobilityData systems catalogue, cached in-process and on disk.

The parsed catalogue is memoised for the life of the process, so resolving many systems in a loop hits the network once. On a successful download it is also cached to CACHE_PATH; if a later download fails (network down, registry outage) the disk copy is used with a warning, so a long-running study never breaks on a transient outage. A fresh copy is returned each call (safe to mutate).

Parameters:

Name Type Description Default
source str

URL or local path to a systems.csv. Defaults to DEFAULT_CATALOG_URL (requires the optional [fetch] extra).

None
timeout int

HTTP timeout in seconds (only when fetching a URL).

30
use_cache bool

Use the in-process / disk caches.

True
refresh bool

Force a re-download, ignoring (and replacing) the in-process cache.

False

Returns:

Type Description
DataFrame

The catalogue with normalised lowercase column names.

See Also

filter_catalog : Narrow the catalogue. resolve : Resolve one system's discovery URL. fetch_multiple : Fetch the resolved systems.

Source code in src/gbfs_toolkit/io/catalog.py
def systems_catalog(
    source: str | None = None,
    *,
    timeout: int = 30,
    use_cache: bool = True,
    refresh: bool = False,
) -> pd.DataFrame:
    """Load the MobilityData systems catalogue, cached in-process and on disk.

    The parsed catalogue is memoised for the life of the process, so resolving many systems in
    a loop hits the network once. On a successful download it is also cached to
    `CACHE_PATH`; if a later download fails (network down, registry outage) the disk copy
    is used with a warning, so a long-running study never breaks on a transient outage. A fresh
    copy is returned each call (safe to mutate).

    Parameters
    ----------
    source : str, optional
        URL or local path to a ``systems.csv``. Defaults to `DEFAULT_CATALOG_URL`
        (requires the optional ``[fetch]`` extra).
    timeout : int, default 30
        HTTP timeout in seconds (only when fetching a URL).
    use_cache : bool, default True
        Use the in-process / disk caches.
    refresh : bool, default False
        Force a re-download, ignoring (and replacing) the in-process cache.

    Returns
    -------
    pandas.DataFrame
        The catalogue with normalised lowercase column names.

    See Also
    --------
    [`filter_catalog`][gbfs_toolkit.filter_catalog] : Narrow the catalogue.
    [`resolve`][gbfs_toolkit.resolve] : Resolve one system's discovery URL.
    [`fetch_multiple`][gbfs_toolkit.fetch_multiple] : Fetch the resolved systems.
    """
    key = source or DEFAULT_CATALOG_URL
    if use_cache and not refresh and key in _MEMO:
        return _MEMO[key].copy()
    df = _load_catalog(key, timeout=timeout, disk_cache=use_cache)
    if use_cache:
        _MEMO[key] = df
    return df.copy()