aiomobilitydatabase 0.3.0__tar.gz → 0.4.0__tar.gz

{aiomobilitydatabase-0.3.0 → aiomobilitydatabase-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: aiomobilitydatabase
-Version: 0.3.0
+Version: 0.4.0
 Summary: Async Python client for the Mobility Database catalog API
 Project-URL: Source Code, https://github.com/raman325/aiomobilitydatabase
 Project-URL: Bug Reports, https://github.com/raman325/aiomobilitydatabase/issues
@@ -104,7 +104,7 @@ aiomobilitydatabase[feeds]`.
 ```python
 import asyncio
 
-from aiomobilitydatabase.feeds import Circle, MobilityFeedsClient
+from aiomobilitydatabase.feeds import ArrivalsQuery, Circle, MobilityFeedsClient
 
 
 async def main() -> None:
@@ -137,7 +137,13 @@ async def main() -> None:
 
         # Scheduled arrivals merged with realtime (delays, cancellations,
         # RT-added trips) when the feed publishes GTFS-RT TripUpdates.
-        arrivals = await transit.get_arrivals([nearby_stops[0].id], limit=2)
+        # Pass several ArrivalsQuery objects to get several boards (each
+        # with its own stops, route/headsign filters, and limit) from one
+        # realtime fetch; the result has one list per query, in order.
+        # Delayed trips stay listed until their prediction passes.
+        [arrivals] = await transit.get_arrivals(
+            [ArrivalsQuery([nearby_stops[0].id], limit=2)]
+        )
         for arrival in arrivals:
             when = arrival.predicted_departure or arrival.scheduled_departure
             live = "live" if arrival.realtime else "scheduled"
@@ -174,7 +180,7 @@ catalog methods, so everything above works unchanged:
 ```python
 import asyncio
 
-from aiomobilitydatabase.feeds import MobilityFeedsClient
+from aiomobilitydatabase.feeds import ArrivalsQuery, MobilityFeedsClient
 
 
 async def main() -> None:
@@ -186,7 +192,7 @@ async def main() -> None:
             vehicle_positions_urls=["https://agency.example/gtfs-rt/positions.pb"],
             headers={"Authorization": "Bearer PRODUCER_TOKEN"},  # optional
         )
-        arrivals = await transit.get_arrivals([transit.stops[0].id])
+        [arrivals] = await transit.get_arrivals([ArrivalsQuery([transit.stops[0].id])])
 
         bikes = await client.get_gbfs_feed_from_url(
             "https://bikes.example/gbfs/gbfs.json"
@@ -226,6 +232,15 @@ Notes on direct mode:
   work with or without realtime coverage; GTFS-RT TripUpdates overlay delays,
   cancellations, and added trips when present, with cancellation always
   winning over stale predictions.
+- **Arrivals are batched and delay-aware**: `get_arrivals()` takes a sequence
+  of `ArrivalsQuery` and returns one board per query from a single schedule
+  read and a single realtime fetch, so several stops with different
+  route/headsign filters cost one round trip instead of one each. Each query's
+  filters apply *before* its `limit`, and `limit` caps that board as a whole
+  rather than per GTFS stop — so a narrow filter can never come back empty
+  because busier routes used up the limit. A `grace` window (default one hour)
+  keeps a delayed trip listed past its scheduled time until its prediction
+  passes, while a schedule-only departure still drops at its scheduled time.
 - **frequencies.txt is materialized at build time**: headway-based trips
   (common for metro/BRT) expand into concrete repetitions under synthetic
   `{trip_id}#{start_secs}` ids, so every schedule query — arrivals,
@@ -245,6 +260,14 @@ Notes on direct mode:
   absent-means-exact default, and open vocabularies (`route_type`,
   `direction_id`) stay raw ints. Out-of-vocabulary values degrade to `None` —
   descriptive metadata never fails a build. Consumers decide what to keep.
+- **Numbers are ASCII-strict, and strictness follows the field's role**: a
+  GTFS number must be plain ASCII digits, so a Unicode decimal (`٨`), a sign
+  prefix, or Python's `1_0` underscore grouping is never quietly reinterpreted
+  as a plausible value. A malformed **structural** cell — `stop_times` times,
+  `stop_sequence`, `headway_secs`, `exception_type`, calendar weekday flags —
+  fails the build, because a wrong departure time or a wrong call order is
+  worse than no feed at all. A malformed **descriptive** cell still degrades
+  to `None`.
 - **Static metadata accessors**: `transit.agencies`, `transit.feed_info`
   (publisher, version, validity dates — useful for staleness checks), and
   `headsigns_serving()` alongside the stop/route helpers.
@@ -257,13 +280,22 @@ Notes on direct mode:
   keyed by feed, validated against the dataset ID, so restarts are instant and
   rebuilds only happen when the agency publishes a new dataset
   (`await transit.refresh_static()` — call it daily; it swaps in the new index
-  only after it's built, so lookups never see a half-built database). Without
-  a `cache_dir` the index is built in memory on every startup.
+  only after it's built, so lookups never see a half-built database, and it is
+  safe to call while queries are in flight: the swap waits for in-flight reads
+  to finish, and two overlapping refreshes run back to back rather than
+  double-building). A corrupt or unreadable cache is treated as a cache miss
+  and rebuilt rather than raising. Without a `cache_dir` the index is built in
+  memory on every startup.
 - **Pull, not push**: `TransitFeedHandle`/`GbfsFeedHandle` return snapshots on
   demand — there's no built-in polling loop or scheduler. Bring your own (e.g.
   Home Assistant's `DataUpdateCoordinator`).
 - **`purge_cache()`** deletes a feed's cached static data (or all feeds' when
   called with no argument) — call it on cleanup/removal of a configured feed.
+  A `feed_id` that is not a bare child name of the cache directory raises
+  `ValueError` instead of deleting anything, so an absolute path, a `..`
+  component, a symlinked entry, or a degenerate `""`/`"."` cannot take out
+  every feed's cache. Purging a feed with no cache directory is a no-op, so
+  repeated calls are idempotent.
   `transit.close()` releases a handle's SQLite connection — call it when you
   are done with a handle; the client's `close()` does not do it for you.
 - **Producer authentication**: pass `api_key=` to `get_transit_feed()`; it is
@@ -290,9 +322,17 @@ each define their own subtree beneath it, so you can catch broadly
 | `MobilityFeedsError` | feeds | Base class for all feeds errors (subclasses `MobilityDatabaseError`) |
 | `SourceConnectionError` | feeds | Producer/GBFS endpoint unreachable or errored (`.status` when HTTP) |
 | `SourceAuthenticationError` | feeds | Producer rejected the feed's `api_key` |
-| `FeedParseError` | feeds | Undecodable protobuf, malformed GBFS JSON, or unreadable GTFS zip |
+| `FeedParseError` | feeds | Undecodable protobuf, malformed GBFS JSON or envelope, unreadable GTFS zip, or a malformed scalar in a structural GTFS column |
 | `StaticDataUnavailableError` | feeds | Feed has no usable hosted static dataset |
 
+The GBFS and GTFS-RT parse paths are **total** with respect to this table:
+any producer document, however malformed, either returns a typed result or
+raises one of the exceptions above — never a bare `KeyError`, `TypeError`,
+`ValueError` or `OverflowError` from inside the library. The one deliberate
+exception is `purge_cache()`, which raises the builtin `ValueError` for a
+`feed_id` it will not accept (see above), because that is a caller mistake
+rather than a feed problem.
+
 Note the two independent auth flows: a `MobilityDatabaseAuthenticationError`
 means your **catalog refresh token** is invalid; a `SourceAuthenticationError`
 means the **producer** rejected the feed-specific `api_key` you passed to
@@ -356,6 +396,22 @@ The suite combines example-based, property-based, and conformance testing:
     and GTFS-RT protobuf parsing, both checked for **totality** — every
     generated input must produce a typed result or a documented
     `MobilityFeedsError` subclass, never an unhandled exception;
+  - the batched arrivals contract: that batching is pure query factorization
+    (`get_arrivals([q1, q2])` equals the two single-query calls), that a batch
+    costs exactly one realtime fetch however many queries it carries, that
+    route and headsign filters apply before the limit, and that every returned
+    row's effective departure is still ahead of `now`;
+  - the origin→destination query against an oracle built from the stored
+    stop-call table: the self-join's direction rule (no return-trip rows) and
+    the earliest-destination-call rule for loop trips, neither of which any
+    test asserted before;
+  - window monotonicity — widening `lookahead` yields a prefix and widening
+    `grace` yields a superset — which guards the scan-window regression class
+    directly, without a hand-built oracle;
+  - the cache as a round trip: a built index and the same index reopened from
+    disk answer every query identically, including the stored timezone, and
+    `purge_cache` removes exactly the named feed and nothing else for any
+    generated `feed_id`;
   - error-contract fuzzing for malformed GTFS zips, RT payloads, and GBFS
     documents (garbage bytes, wrong types, out-of-range values) — the
     contract under test is "raises `FeedParseError`/`SourceConnectionError`",

{aiomobilitydatabase-0.3.0 → aiomobilitydatabase-0.4.0}/README.md

@@ -80,7 +80,7 @@ aiomobilitydatabase[feeds]`.
 ```python
 import asyncio
 
-from aiomobilitydatabase.feeds import Circle, MobilityFeedsClient
+from aiomobilitydatabase.feeds import ArrivalsQuery, Circle, MobilityFeedsClient
 
 
 async def main() -> None:
@@ -113,7 +113,13 @@ async def main() -> None:
 
         # Scheduled arrivals merged with realtime (delays, cancellations,
         # RT-added trips) when the feed publishes GTFS-RT TripUpdates.
-        arrivals = await transit.get_arrivals([nearby_stops[0].id], limit=2)
+        # Pass several ArrivalsQuery objects to get several boards (each
+        # with its own stops, route/headsign filters, and limit) from one
+        # realtime fetch; the result has one list per query, in order.
+        # Delayed trips stay listed until their prediction passes.
+        [arrivals] = await transit.get_arrivals(
+            [ArrivalsQuery([nearby_stops[0].id], limit=2)]
+        )
         for arrival in arrivals:
             when = arrival.predicted_departure or arrival.scheduled_departure
             live = "live" if arrival.realtime else "scheduled"
@@ -150,7 +156,7 @@ catalog methods, so everything above works unchanged:
 ```python
 import asyncio
 
-from aiomobilitydatabase.feeds import MobilityFeedsClient
+from aiomobilitydatabase.feeds import ArrivalsQuery, MobilityFeedsClient
 
 
 async def main() -> None:
@@ -162,7 +168,7 @@ async def main() -> None:
             vehicle_positions_urls=["https://agency.example/gtfs-rt/positions.pb"],
             headers={"Authorization": "Bearer PRODUCER_TOKEN"},  # optional
         )
-        arrivals = await transit.get_arrivals([transit.stops[0].id])
+        [arrivals] = await transit.get_arrivals([ArrivalsQuery([transit.stops[0].id])])
 
         bikes = await client.get_gbfs_feed_from_url(
             "https://bikes.example/gbfs/gbfs.json"
@@ -202,6 +208,15 @@ Notes on direct mode:
   work with or without realtime coverage; GTFS-RT TripUpdates overlay delays,
   cancellations, and added trips when present, with cancellation always
   winning over stale predictions.
+- **Arrivals are batched and delay-aware**: `get_arrivals()` takes a sequence
+  of `ArrivalsQuery` and returns one board per query from a single schedule
+  read and a single realtime fetch, so several stops with different
+  route/headsign filters cost one round trip instead of one each. Each query's
+  filters apply *before* its `limit`, and `limit` caps that board as a whole
+  rather than per GTFS stop — so a narrow filter can never come back empty
+  because busier routes used up the limit. A `grace` window (default one hour)
+  keeps a delayed trip listed past its scheduled time until its prediction
+  passes, while a schedule-only departure still drops at its scheduled time.
 - **frequencies.txt is materialized at build time**: headway-based trips
   (common for metro/BRT) expand into concrete repetitions under synthetic
   `{trip_id}#{start_secs}` ids, so every schedule query — arrivals,
@@ -221,6 +236,14 @@ Notes on direct mode:
   absent-means-exact default, and open vocabularies (`route_type`,
   `direction_id`) stay raw ints. Out-of-vocabulary values degrade to `None` —
   descriptive metadata never fails a build. Consumers decide what to keep.
+- **Numbers are ASCII-strict, and strictness follows the field's role**: a
+  GTFS number must be plain ASCII digits, so a Unicode decimal (`٨`), a sign
+  prefix, or Python's `1_0` underscore grouping is never quietly reinterpreted
+  as a plausible value. A malformed **structural** cell — `stop_times` times,
+  `stop_sequence`, `headway_secs`, `exception_type`, calendar weekday flags —
+  fails the build, because a wrong departure time or a wrong call order is
+  worse than no feed at all. A malformed **descriptive** cell still degrades
+  to `None`.
 - **Static metadata accessors**: `transit.agencies`, `transit.feed_info`
   (publisher, version, validity dates — useful for staleness checks), and
   `headsigns_serving()` alongside the stop/route helpers.
@@ -233,13 +256,22 @@ Notes on direct mode:
   keyed by feed, validated against the dataset ID, so restarts are instant and
   rebuilds only happen when the agency publishes a new dataset
   (`await transit.refresh_static()` — call it daily; it swaps in the new index
-  only after it's built, so lookups never see a half-built database). Without
-  a `cache_dir` the index is built in memory on every startup.
+  only after it's built, so lookups never see a half-built database, and it is
+  safe to call while queries are in flight: the swap waits for in-flight reads
+  to finish, and two overlapping refreshes run back to back rather than
+  double-building). A corrupt or unreadable cache is treated as a cache miss
+  and rebuilt rather than raising. Without a `cache_dir` the index is built in
+  memory on every startup.
 - **Pull, not push**: `TransitFeedHandle`/`GbfsFeedHandle` return snapshots on
   demand — there's no built-in polling loop or scheduler. Bring your own (e.g.
   Home Assistant's `DataUpdateCoordinator`).
 - **`purge_cache()`** deletes a feed's cached static data (or all feeds' when
   called with no argument) — call it on cleanup/removal of a configured feed.
+  A `feed_id` that is not a bare child name of the cache directory raises
+  `ValueError` instead of deleting anything, so an absolute path, a `..`
+  component, a symlinked entry, or a degenerate `""`/`"."` cannot take out
+  every feed's cache. Purging a feed with no cache directory is a no-op, so
+  repeated calls are idempotent.
   `transit.close()` releases a handle's SQLite connection — call it when you
   are done with a handle; the client's `close()` does not do it for you.
 - **Producer authentication**: pass `api_key=` to `get_transit_feed()`; it is
@@ -266,9 +298,17 @@ each define their own subtree beneath it, so you can catch broadly
 | `MobilityFeedsError` | feeds | Base class for all feeds errors (subclasses `MobilityDatabaseError`) |
 | `SourceConnectionError` | feeds | Producer/GBFS endpoint unreachable or errored (`.status` when HTTP) |
 | `SourceAuthenticationError` | feeds | Producer rejected the feed's `api_key` |
-| `FeedParseError` | feeds | Undecodable protobuf, malformed GBFS JSON, or unreadable GTFS zip |
+| `FeedParseError` | feeds | Undecodable protobuf, malformed GBFS JSON or envelope, unreadable GTFS zip, or a malformed scalar in a structural GTFS column |
 | `StaticDataUnavailableError` | feeds | Feed has no usable hosted static dataset |
 
+The GBFS and GTFS-RT parse paths are **total** with respect to this table:
+any producer document, however malformed, either returns a typed result or
+raises one of the exceptions above — never a bare `KeyError`, `TypeError`,
+`ValueError` or `OverflowError` from inside the library. The one deliberate
+exception is `purge_cache()`, which raises the builtin `ValueError` for a
+`feed_id` it will not accept (see above), because that is a caller mistake
+rather than a feed problem.
+
 Note the two independent auth flows: a `MobilityDatabaseAuthenticationError`
 means your **catalog refresh token** is invalid; a `SourceAuthenticationError`
 means the **producer** rejected the feed-specific `api_key` you passed to
@@ -332,6 +372,22 @@ The suite combines example-based, property-based, and conformance testing:
     and GTFS-RT protobuf parsing, both checked for **totality** — every
     generated input must produce a typed result or a documented
     `MobilityFeedsError` subclass, never an unhandled exception;
+  - the batched arrivals contract: that batching is pure query factorization
+    (`get_arrivals([q1, q2])` equals the two single-query calls), that a batch
+    costs exactly one realtime fetch however many queries it carries, that
+    route and headsign filters apply before the limit, and that every returned
+    row's effective departure is still ahead of `now`;
+  - the origin→destination query against an oracle built from the stored
+    stop-call table: the self-join's direction rule (no return-trip rows) and
+    the earliest-destination-call rule for loop trips, neither of which any
+    test asserted before;
+  - window monotonicity — widening `lookahead` yields a prefix and widening
+    `grace` yields a superset — which guards the scan-window regression class
+    directly, without a hand-built oracle;
+  - the cache as a round trip: a built index and the same index reopened from
+    disk answer every query identically, including the stored timezone, and
+    `purge_cache` removes exactly the named feed and nothing else for any
+    generated `feed_id`;
   - error-contract fuzzing for malformed GTFS zips, RT payloads, and GBFS
     documents (garbage bytes, wrong types, out-of-range values) — the
     contract under test is "raises `FeedParseError`/`SourceConnectionError`",

{aiomobilitydatabase-0.3.0 → aiomobilitydatabase-0.4.0}/src/aiomobilitydatabase/const.py

@@ -1,6 +1,6 @@
 """Constants for aiomobilitydatabase."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 PROD_BASE_URL = "https://api.mobilitydatabase.org"
 QA_BASE_URL = "https://api-qa.mobilitydatabase.org"

{aiomobilitydatabase-0.3.0 → aiomobilitydatabase-0.4.0}/src/aiomobilitydatabase/feeds/__init__.py

@@ -27,6 +27,7 @@ from .models import (
     AlertCause,
     AlertEffect,
     AlertSeverity,
+    ArrivalsQuery,
     BikesAllowed,
     CongestionLevel,
     FeedInfo,
@@ -54,6 +55,7 @@ __all__ = [
     "AlertCause",
     "AlertEffect",
     "AlertSeverity",
+    "ArrivalsQuery",
     "BikesAllowed",
     "Circle",
     "CongestionLevel",

{aiomobilitydatabase-0.3.0 → aiomobilitydatabase-0.4.0}/src/aiomobilitydatabase/feeds/client.py

@@ -124,18 +124,42 @@ class MobilityFeedsClient:
         storage at a different feed). ``feed_id`` is either a catalog feed
         ID or a direct handle's url-derived ``url-<sha256(url)[:16]>`` key
         — exactly what :attr:`TransitFeedHandle.static_feed_id` returns in
-        both cases. No-op without a cache_dir. Raises ``ValueError`` if
-        ``feed_id`` would resolve outside the cache directory (e.g. an
-        absolute path or one containing ``..`` components). Missing
-        targets are silently skipped; other filesystem errors (e.g.
-        permissions) propagate to the caller.
+        both cases. No-op without a cache_dir. Purging a feed that has no
+        cache directory is a silent no-op, so repeated calls are
+        idempotent; other filesystem errors (e.g. permissions) propagate
+        to the caller.
+
+        Raises ``ValueError`` unless ``feed_id`` resolves to a direct
+        child of the cache directory. That rejects absolute paths, ``..``
+        components and symlinked entries, but also the degenerate ids
+        (``""``, ``"."``) that resolve to the cache root itself — a
+        containment-only check accepts those, because every path is
+        relative to itself, and would delete every feed's cache.
         """
         if self.cache_dir is None:
             return
         if feed_id is not None:
+            candidate = Path(feed_id)
             target = self.cache_dir / feed_id
-            if not target.resolve().is_relative_to(self.cache_dir.resolve()):
-                raise ValueError(f"feed_id {feed_id!r} escapes the cache directory")
+            root = self.cache_dir.resolve()
+            # The input itself must be a bare child name. Resolving first
+            # and checking only the destination accepts ids that reach a
+            # feed the caller cannot name directly (an absolute path, or
+            # one routed through ``..``), and hands symlinked entries to
+            # rmtree, which rejects them with OSError.
+            invalid = (
+                candidate.is_absolute()
+                or candidate.name != feed_id
+                or target.is_symlink()
+            )
+            if not invalid:
+                resolved = target.resolve()
+                invalid = resolved == root or resolved.parent != root
+            if invalid:
+                raise ValueError(
+                    f"feed_id {feed_id!r} escapes the cache directory: "
+                    "it does not name a direct child"
+                )
             targets = [target]
         else:
             targets = [path for path in self.cache_dir.iterdir() if path.is_dir()]

{aiomobilitydatabase-0.3.0 → aiomobilitydatabase-0.4.0}/src/aiomobilitydatabase/feeds/gbfs.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import math
 import time
 from collections.abc import Mapping
 from http import HTTPStatus
@@ -31,6 +32,20 @@ def _entry_text(entry: dict[str, Any]) -> str | None:
     return None if text is None else str(text)
 
 
+def _record_id(value: Any) -> str | None:
+    """One record's own id as a string, or None when it has none.
+
+    ``str(value)`` would synthesize the literal id ``"None"`` for an
+    id-less record — and those synthetic ids COLLIDE across records,
+    corrupting any consumer that keys on them (an entity registry, say).
+    A blank id collides identically, so it is None too. Same motivation
+    as :func:`_entry_text`: never surface a stringified None.
+    """
+    if value is None:
+        return None
+    return str(value) or None
+
+
 def _localized(value: Any) -> str | None:
     """Normalize GBFS text: 3.x localized lists vs 2.x plain strings."""
     if value is None or isinstance(value, str):
@@ -69,6 +84,63 @@ def _rental_uris(value: Any) -> dict[str, str] | None:
     return uris or None
 
 
+def _coordinate(value: Any) -> float | None:
+    """Normalize one ``lat``/``lon`` cell to a finite float, else None (unknown).
+
+    :func:`~.geo.in_circle` compares the value and takes its cosine, so a
+    string coordinate would raise and a NaN would answer every comparison
+    False; both are UNKNOWN instead. Numeric strings are accepted because
+    producers ship them, and an integer literal too large for a float
+    (JSON allows one of any size) is UNKNOWN rather than an OverflowError.
+    """
+    if isinstance(value, bool) or not isinstance(value, int | float | str):
+        return None
+    try:
+        coordinate = float(value)
+    except (OverflowError, ValueError):
+        return None
+    return coordinate if math.isfinite(coordinate) else None
+
+
+def _vehicle_types(value: Any) -> dict[str, int] | None:
+    """Normalize a station's ``vehicle_types_available`` to id -> count.
+
+    Entries without a usable type id, and counts that aren't parseable as
+    an int (``int(None)`` used to raise), are dropped rather than
+    coerced; an absent count is the spec's 0. Anything that isn't a list
+    with at least one usable entry is None, i.e. "not published". A count
+    of ``1e999`` parses as inf, which int() refuses, so it is dropped too.
+    """
+    if not isinstance(value, list):
+        return None
+    types: dict[str, int] = {}
+    for entry in value:
+        if not isinstance(entry, Mapping):
+            continue
+        type_id = _record_id(entry.get("vehicle_type_id"))
+        try:
+            count = int(entry.get("count", 0))
+        except (OverflowError, TypeError, ValueError):
+            continue
+        if type_id is not None:
+            types[type_id] = count
+    return types or None
+
+
+def _rows(document: Mapping[str, Any], key: str) -> list[Mapping[str, Any]]:
+    """Extract the ``data.<key>`` row list, keeping object-shaped rows only.
+
+    A GBFS document's envelope is producer data: ``data`` may be a list,
+    the row list a string, a row an int. Every non-conforming shape
+    degrades to "no rows" so the snapshot methods stay total.
+    """
+    data = document.get("data")
+    rows = data.get(key) if isinstance(data, Mapping) else None
+    if not isinstance(rows, list):
+        return []
+    return [row for row in rows if isinstance(row, Mapping)]
+
+
 def _as_bool(value: Any) -> bool | None:
     """Coerce a GBFS status flag to bool without lying on ambiguous input.
 
@@ -81,7 +153,26 @@ def _as_bool(value: Any) -> bool | None:
     return None
 
 
-def _endpoints_from_discovery(document: dict[str, Any]) -> dict[str, str]:
+def _ttl_seconds(value: Any) -> float:
+    """Micro-cache lifetime from a document's ``ttl``, leniently.
+
+    A ttl that isn't a usable, finite, non-negative number degrades to 0
+    (no caching) like every other malformed scalar at this boundary: a
+    bad cache HINT must not fail a document that otherwise parsed. Plain
+    numeric strings are accepted because producers do ship them, and an
+    integer literal too large for a float degrades like any other
+    unusable ttl.
+    """
+    if isinstance(value, bool) or not isinstance(value, int | float | str):
+        return 0.0
+    try:
+        ttl = float(value)
+    except (OverflowError, ValueError):
+        return 0.0
+    return ttl if math.isfinite(ttl) and ttl > 0 else 0.0
+
+
+def _endpoints_from_discovery(document: Any) -> dict[str, str]:
     """Resolve the name->url endpoint table from a GBFS discovery document.
 
     GBFS 3.x publishes ``data.feeds`` directly; 2.x nests the feed list
@@ -90,26 +181,33 @@ def _endpoints_from_discovery(document: dict[str, Any]) -> dict[str, str]:
     carries feeds, mirroring the fallback order of :func:`_localized`.
     The result feeds the same endpoint table the catalog path builds from
     version metadata, so every handle method works identically after this.
+
+    Total over arbitrary JSON: any document that yields no usable
+    name/url pair raises :class:`FeedParseError` — including an absent or
+    wrongly typed ``data``, so a malformed discovery document can never
+    surface as a KeyError/TypeError to a caller.
     """
-    data = document["data"]
+    data = document.get("data") if isinstance(document, Mapping) else None
     feeds: Any = None
-    if isinstance(data, dict):
+    if isinstance(data, Mapping):
         feeds = data.get("feeds")
-        if feeds is None:  # 2.x language-keyed layout
+        if not isinstance(feeds, list):  # 2.x language-keyed layout
             candidates = [
                 block
                 for block in data.values()
-                if isinstance(block, dict) and isinstance(block.get("feeds"), list)
+                if isinstance(block, Mapping) and isinstance(block.get("feeds"), list)
             ]
             preferred = data.get(GBFS_LANGUAGE_PREFERENCE)
-            if isinstance(preferred, dict) and isinstance(preferred.get("feeds"), list):
+            if isinstance(preferred, Mapping) and isinstance(
+                preferred.get("feeds"), list
+            ):
                 candidates.insert(0, preferred)
             if candidates:
                 feeds = candidates[0]["feeds"]
     endpoints = {
         str(feed["name"]): str(feed["url"])
         for feed in (feeds if isinstance(feeds, list) else [])
-        if isinstance(feed, dict) and feed.get("name") and feed.get("url")
+        if isinstance(feed, Mapping) and feed.get("name") and feed.get("url")
     }
     if not endpoints:
         raise FeedParseError("GBFS discovery document lists no usable feeds")
@@ -219,15 +317,25 @@ class GbfsFeedHandle:
         document = await self._fetch_json_document(
             self._client, url, self._headers, f"GBFS {name} endpoint URL"
         )
-        ttl = float(document.get("ttl") or 0)
+        ttl = _ttl_seconds(document.get("ttl"))
         self._doc_cache[name] = (time.monotonic(), ttl, document)
         return document
 
     async def get_system_info(self) -> SystemInfo:
-        """GBFS system information."""
+        """GBFS system information.
+
+        A document without a usable ``system_id`` raises
+        :class:`FeedParseError`: the id is this system's identity, and a
+        synthesized one would silently key consumer state to nothing.
+        """
         data = (await self._document("system_information"))["data"]
+        system_id = _record_id(
+            data.get("system_id") if isinstance(data, Mapping) else None
+        )
+        if system_id is None:
+            raise FeedParseError("GBFS system_information document has no system_id")
         return SystemInfo(
-            system_id=str(data.get("system_id")),
+            system_id=system_id,
             name=_localized(data.get("name")),
             operator=_localized(data.get("operator")),
             timezone=data.get("timezone"),
@@ -239,37 +347,32 @@ class GbfsFeedHandle:
         With ``zone``, only stations inside the circle are returned (stations
         without coordinates are excluded when filtering) — this powers both
         the config-flow station multi-select and zone-scoped station sensors.
+        Information rows without a usable ``station_id`` are skipped: the
+        merge and the returned ``id`` both key on it.
         """
-        info_rows = (await self._document("station_information"))["data"].get(
-            "stations", []
-        )
-        status_rows = (await self._document("station_status"))["data"].get(
-            "stations", []
-        )
-        status_by_id = {row.get("station_id"): row for row in status_rows}
+        info_rows = _rows(await self._document("station_information"), "stations")
+        status_rows = _rows(await self._document("station_status"), "stations")
+        status_by_id = {_record_id(row.get("station_id")): row for row in status_rows}
         stations: list[Station] = []
         for info in info_rows:
-            if zone is not None:
-                lat, lon = info.get("lat"), info.get("lon")
-                if lat is None or lon is None or not in_circle(zone, lat, lon):
-                    continue
-            station_id = info.get("station_id")
-            status = status_by_id.get(station_id, {})
-            types_list = status.get("vehicle_types_available")
-            types = (
-                {
-                    str(entry.get("vehicle_type_id")): int(entry.get("count", 0))
-                    for entry in types_list
-                }
-                if types_list
-                else None
-            )
+            latitude = _coordinate(info.get("lat"))
+            longitude = _coordinate(info.get("lon"))
+            if zone is not None and (
+                latitude is None
+                or longitude is None
+                or not in_circle(zone, latitude, longitude)
+            ):
+                continue
+            station_id = _record_id(info.get("station_id"))
+            if station_id is None:
+                continue
+            status: Mapping[str, Any] = status_by_id.get(station_id, {})
             stations.append(
                 Station(
-                    id=str(station_id),
+                    id=station_id,
                     name=_localized(info.get("name")),
-                    latitude=info.get("lat"),
-                    longitude=info.get("lon"),
+                    latitude=latitude,
+                    longitude=longitude,
                     capacity=info.get("capacity"),
                     bikes_available=status.get(
                         "num_bikes_available", status.get("num_vehicles_available")
@@ -277,7 +380,9 @@ class GbfsFeedHandle:
                     docks_available=status.get("num_docks_available"),
                     is_renting=_as_bool(status.get("is_renting")),
                     is_returning=_as_bool(status.get("is_returning")),
-                    vehicle_types_available=types,
+                    vehicle_types_available=_vehicle_types(
+                        status.get("vehicle_types_available")
+                    ),
                     rental_uris=_rental_uris(info.get("rental_uris")),
                 )
             )
@@ -289,29 +394,33 @@ class GbfsFeedHandle:
         Uses ``vehicle_status`` (GBFS 3.x) when published, else falls back to
         ``free_bike_status`` (2.x). Returns [] for docked-only systems.
         Filtering is client-side: GBFS has no server-side geo-query.
+        Rows without a usable id are skipped, as are rows without
+        coordinates (a free-floating vehicle IS its position).
         """
         if "vehicle_status" in self._endpoints:
-            rows = (await self._document("vehicle_status"))["data"].get("vehicles", [])
+            rows = _rows(await self._document("vehicle_status"), "vehicles")
             id_key = "vehicle_id"
         elif "free_bike_status" in self._endpoints:
-            rows = (await self._document("free_bike_status"))["data"].get("bikes", [])
+            rows = _rows(await self._document("free_bike_status"), "bikes")
             id_key = "bike_id"
         else:
             return []
         vehicles: list[GbfsVehicle] = []
         for row in rows:
-            latitude, longitude = row.get("lat"), row.get("lon")
-            if latitude is None or longitude is None:
+            vehicle_id = _record_id(row.get(id_key))
+            latitude = _coordinate(row.get("lat"))
+            longitude = _coordinate(row.get("lon"))
+            if vehicle_id is None or latitude is None or longitude is None:
                 continue
             if zone is not None and not in_circle(zone, latitude, longitude):
                 continue
             vehicles.append(
                 GbfsVehicle(
-                    id=str(row.get(id_key)),
+                    id=vehicle_id,
                     latitude=latitude,
                     longitude=longitude,
-                    is_reserved=row.get("is_reserved"),
-                    is_disabled=row.get("is_disabled"),
+                    is_reserved=_as_bool(row.get("is_reserved")),
+                    is_disabled=_as_bool(row.get("is_disabled")),
                     vehicle_type_id=row.get("vehicle_type_id"),
                     current_range_m=row.get("current_range_meters"),
                     rental_uris=_rental_uris(row.get("rental_uris")),