aiomobilitydatabase 0.3.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: aiomobilitydatabase
-Version: 0.3.0
+Version: 0.5.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,11 +137,20 @@ 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"
-            print(f"{arrival.route_name} -> {arrival.headsign}: {when} ({live})")
+            # .stop and .route are the whole static records: platform codes,
+            # coordinates, route_type and route colours all come along.
+            route = arrival.route.display_name if arrival.route else arrival.route_id
+            print(f"{route} -> {arrival.headsign}: {when} ({live})")
 
         # Origin→destination: the next departures from stop A on trips that
         # later reach stop B, with the same realtime overlay. is_first/is_last
@@ -150,7 +159,8 @@ async def main() -> None:
             nearby_stops[0].id, nearby_stops[1].id, limit=2
         )
         for trip in trips:
-            print(trip.route_name, trip.scheduled_departure, trip.is_last)
+            name = trip.route.display_name if trip.route else trip.route_id
+            print(name, trip.scheduled_departure, trip.is_last)
 
         vehicles = await transit.get_vehicles()
         alerts = await transit.get_alerts()
@@ -174,7 +184,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 +196,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 +236,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,
@@ -238,6 +257,19 @@ Notes on direct mode:
   information, `NO_DATA` makes a stop schedule-only, `SKIPPED` suppresses it
   (and any origin→destination row boarding or alighting there), and the
   trip-level delay covers stops no StopTimeUpdate reaches.
+- **Rows carry whole records, not copied columns**: `StopArrival`,
+  `UpcomingTrip`, and `VehiclePosition` each expose the full `Stop` and
+  `Route` they refer to, so platform codes, coordinates, route colours and
+  `route_type` are reachable without a second lookup — use
+  `route.display_name` / `stop.name` for the human-readable strings. The raw
+  `stop_id`/`route_id` stay alongside, since those are what feeds reference
+  and what filters key on; a `route_id` naming a route absent from
+  `routes.txt` leaves `route` as `None` rather than inventing one.
+- **Vehicle positions name their trip instance**: `VehiclePosition` carries
+  the parsed `trip_start_date`/`trip_start_secs`, the pair a GTFS-RT
+  `TripDescriptor` uses to address one run. That is what lets two buses out
+  on the same headway-based trip be told apart — without it, concurrent
+  repetitions of one template trip are indistinguishable.
 - **The full descriptive surface is exposed, typed by shape**: closed GTFS
   vocabularies are enums (`WheelchairAccess`, `BikesAllowed`,
   `PickupDropOffType`, `StopLocationType`, alert cause/effect/severity,
@@ -245,25 +277,72 @@ 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`.
+- **Detours are applied, not annotated**: a GTFS-RT `TripModifications`
+  entity REPLACES a span of a trip's calls, so a board that ignored it
+  would keep showing departures at stops the vehicle no longer serves, and
+  would miss `propagated_modification_delay` on every stop after the
+  detour. Replacement times are measured from the reference stop the spec
+  names, a replacement stop may be defined only by an RT `Stop` entity, and
+  a detour that routes a trip through a stop its static schedule never
+  served shows up there.
+- **Schedule over a range**: `scheduled_departures(stops, start, end)` is
+  the calendar query — every departure between two instants, schedule only,
+  no limit and no grace, rather than `get_arrivals` stretched to days.
+- **Service calendars are answerable**: `services_on(date)` returns the
+  service ids running on a GTFS service date — `calendar.txt` resolved
+  against `calendar_dates` exceptions, removals winning when a producer
+  lists both types for one date — and every row carries its `service_id`,
+  so "does this trip run next Tuesday" needs no second arrivals query.
+- **GBFS ids resolve**: `get_vehicle_types()`, `get_pricing_plans()`,
+  `get_regions()`, and `get_system_alerts()` turn the `vehicle_type_id`,
+  `pricing_plan_id`, and `region_id` on stations and vehicles into records.
+  All four documents are optional in GBFS, so an unpublished one is `[]`
+  rather than an error.
 - **Static metadata accessors**: `transit.agencies`, `transit.feed_info`
   (publisher, version, validity dates — useful for staleness checks), and
   `headsigns_serving()` alongside the stop/route helpers.
-- **Alert scoping**: `ServiceAlert` carries `route_ids`, `stop_ids`, and
-  `trip_ids`; an alert is agency-wide only when all three are empty.
-  `is_active(at)` evaluates its active periods.
-- **GBFS extras**: `rental_uris` deep links on stations and vehicles,
-  `get_system_info()`, and TTL-based document caching.
+- **Alert scoping covers every selector GTFS-RT offers**: `ServiceAlert`
+  carries `agency_ids`, `route_ids`, `route_types`, `direction_ids`,
+  `stop_ids`, and `trip_ids` — an alert is feed-wide only when *all* of them
+  are empty. Collecting a subset is not a missing nicety but a correctness
+  bug: an alert scoped to one agency, or to a whole mode, would otherwise
+  read as applying everywhere. `is_active(at)` evaluates its active periods.
+- **GBFS exposes what the documents carry**: the full station surface
+  (`is_installed` alongside `is_renting`/`is_returning` — a station removed
+  from the street is not "operational"; disabled counts, address, region,
+  virtual-station flag), free-floating vehicle docking and fuel state, and a
+  `SystemInfo` with the operator's contact, licensing, and terms URLs.
+  `last_reported` is exposed on both stations and vehicles so you can tell
+  fresh data from stale, and is parsed from either GBFS 2.x POSIX seconds or
+  3.0 RFC3339. Plus `rental_uris` deep links and TTL-based document caching.
 - **`cache_dir` strongly recommended**: the static index is cached on disk
   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
@@ -274,6 +353,45 @@ Notes on direct mode:
   design, with no server-side geo-query.
 - **Timestamps are tz-aware UTC** throughout the feeds layer.
 
+## What this does not expose
+
+Deliberate omissions, so you can tell "not supported" from "not found yet".
+
+**GTFS files not ingested.** The static index reads `agency.txt`, `stops.txt`,
+`routes.txt`, `trips.txt`, `stop_times.txt`, `calendar.txt`,
+`calendar_dates.txt`, `frequencies.txt`, and `feed_info.txt`. Everything else
+in the zip is ignored:
+
+- `shapes.txt` — route geometry. Nothing here draws a line on a map, so trips
+  carry no `shape_id`.
+- `transfers.txt` — no transfer rules, minimum transfer times, or
+  trip-to-trip continuations, and no journey planning across a transfer.
+- `pathways.txt` / `levels.txt` — no in-station walking graph.
+- `fare_attributes.txt` / `fare_rules.txt` and all GTFS-Fares v2 files — no
+  fares, zone pricing, or rider categories. (`Stop.zone_id` is exposed as a
+  raw cell, but nothing interprets it.)
+- `translations.txt` — text is returned as the feed wrote it.
+
+Service calendars **are** answerable — `services_on(date)` resolves
+`calendar.txt` against `calendar_dates` exceptions, and rows carry their
+`service_id` — but the raw weekday pattern and validity range behind a
+service are not exposed as a model. `scheduled_departures(stops, start, end)`
+covers the range query a calendar view needs.
+
+**GTFS-RT: trip shapes.** The RT `shape` entity (a detour's new geometry) is
+not read, for the same reason `shapes.txt` is not: nothing here draws a line
+on a map. Detours themselves ARE applied — see *Detours are applied, not
+annotated* — and the `stop` entities they define are read.
+
+**GBFS endpoints not fetched.** `geofencing_zones`, because it is GeoJSON
+polygon geometry while zones here are deliberately circles — supporting it
+means polygon containment, which is a geometry feature rather than another
+document. And `system_hours`, which GBFS 3.0 removed in favour of
+`system_information.opening_hours` (exposed as `SystemInfo.opening_hours`).
+
+**Behaviour, not data.** There is no polling loop or scheduler (see *Pull, not
+push*), no write access of any kind, and no cross-feed journey planning.
+
 ## Error handling
 
 All errors derive from `MobilityDatabaseError`. The catalog and feeds layers
@@ -290,9 +408,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
@@ -351,11 +477,27 @@ The suite combines example-based, property-based, and conformance testing:
     resolver at volume), and `start_date`/`start_time` instance matching over
     windows containing two service-day instances of the same trip;
   - the circular-zone geometry (`in_circle`'s bbox prefilter is checked
-    against the exact haversine distance at generated boundary points);
+    against the exact great-circle distance at generated boundary points);
   - GBFS field parsing (`_localized`, `_version_key`, station/vehicle merging)
     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.5.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,11 +113,20 @@ 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"
-            print(f"{arrival.route_name} -> {arrival.headsign}: {when} ({live})")
+            # .stop and .route are the whole static records: platform codes,
+            # coordinates, route_type and route colours all come along.
+            route = arrival.route.display_name if arrival.route else arrival.route_id
+            print(f"{route} -> {arrival.headsign}: {when} ({live})")
 
         # Origin→destination: the next departures from stop A on trips that
         # later reach stop B, with the same realtime overlay. is_first/is_last
@@ -126,7 +135,8 @@ async def main() -> None:
             nearby_stops[0].id, nearby_stops[1].id, limit=2
         )
         for trip in trips:
-            print(trip.route_name, trip.scheduled_departure, trip.is_last)
+            name = trip.route.display_name if trip.route else trip.route_id
+            print(name, trip.scheduled_departure, trip.is_last)
 
         vehicles = await transit.get_vehicles()
         alerts = await transit.get_alerts()
@@ -150,7 +160,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 +172,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 +212,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,
@@ -214,6 +233,19 @@ Notes on direct mode:
   information, `NO_DATA` makes a stop schedule-only, `SKIPPED` suppresses it
   (and any origin→destination row boarding or alighting there), and the
   trip-level delay covers stops no StopTimeUpdate reaches.
+- **Rows carry whole records, not copied columns**: `StopArrival`,
+  `UpcomingTrip`, and `VehiclePosition` each expose the full `Stop` and
+  `Route` they refer to, so platform codes, coordinates, route colours and
+  `route_type` are reachable without a second lookup — use
+  `route.display_name` / `stop.name` for the human-readable strings. The raw
+  `stop_id`/`route_id` stay alongside, since those are what feeds reference
+  and what filters key on; a `route_id` naming a route absent from
+  `routes.txt` leaves `route` as `None` rather than inventing one.
+- **Vehicle positions name their trip instance**: `VehiclePosition` carries
+  the parsed `trip_start_date`/`trip_start_secs`, the pair a GTFS-RT
+  `TripDescriptor` uses to address one run. That is what lets two buses out
+  on the same headway-based trip be told apart — without it, concurrent
+  repetitions of one template trip are indistinguishable.
 - **The full descriptive surface is exposed, typed by shape**: closed GTFS
   vocabularies are enums (`WheelchairAccess`, `BikesAllowed`,
   `PickupDropOffType`, `StopLocationType`, alert cause/effect/severity,
@@ -221,25 +253,72 @@ 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`.
+- **Detours are applied, not annotated**: a GTFS-RT `TripModifications`
+  entity REPLACES a span of a trip's calls, so a board that ignored it
+  would keep showing departures at stops the vehicle no longer serves, and
+  would miss `propagated_modification_delay` on every stop after the
+  detour. Replacement times are measured from the reference stop the spec
+  names, a replacement stop may be defined only by an RT `Stop` entity, and
+  a detour that routes a trip through a stop its static schedule never
+  served shows up there.
+- **Schedule over a range**: `scheduled_departures(stops, start, end)` is
+  the calendar query — every departure between two instants, schedule only,
+  no limit and no grace, rather than `get_arrivals` stretched to days.
+- **Service calendars are answerable**: `services_on(date)` returns the
+  service ids running on a GTFS service date — `calendar.txt` resolved
+  against `calendar_dates` exceptions, removals winning when a producer
+  lists both types for one date — and every row carries its `service_id`,
+  so "does this trip run next Tuesday" needs no second arrivals query.
+- **GBFS ids resolve**: `get_vehicle_types()`, `get_pricing_plans()`,
+  `get_regions()`, and `get_system_alerts()` turn the `vehicle_type_id`,
+  `pricing_plan_id`, and `region_id` on stations and vehicles into records.
+  All four documents are optional in GBFS, so an unpublished one is `[]`
+  rather than an error.
 - **Static metadata accessors**: `transit.agencies`, `transit.feed_info`
   (publisher, version, validity dates — useful for staleness checks), and
   `headsigns_serving()` alongside the stop/route helpers.
-- **Alert scoping**: `ServiceAlert` carries `route_ids`, `stop_ids`, and
-  `trip_ids`; an alert is agency-wide only when all three are empty.
-  `is_active(at)` evaluates its active periods.
-- **GBFS extras**: `rental_uris` deep links on stations and vehicles,
-  `get_system_info()`, and TTL-based document caching.
+- **Alert scoping covers every selector GTFS-RT offers**: `ServiceAlert`
+  carries `agency_ids`, `route_ids`, `route_types`, `direction_ids`,
+  `stop_ids`, and `trip_ids` — an alert is feed-wide only when *all* of them
+  are empty. Collecting a subset is not a missing nicety but a correctness
+  bug: an alert scoped to one agency, or to a whole mode, would otherwise
+  read as applying everywhere. `is_active(at)` evaluates its active periods.
+- **GBFS exposes what the documents carry**: the full station surface
+  (`is_installed` alongside `is_renting`/`is_returning` — a station removed
+  from the street is not "operational"; disabled counts, address, region,
+  virtual-station flag), free-floating vehicle docking and fuel state, and a
+  `SystemInfo` with the operator's contact, licensing, and terms URLs.
+  `last_reported` is exposed on both stations and vehicles so you can tell
+  fresh data from stale, and is parsed from either GBFS 2.x POSIX seconds or
+  3.0 RFC3339. Plus `rental_uris` deep links and TTL-based document caching.
 - **`cache_dir` strongly recommended**: the static index is cached on disk
   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
@@ -250,6 +329,45 @@ Notes on direct mode:
   design, with no server-side geo-query.
 - **Timestamps are tz-aware UTC** throughout the feeds layer.
 
+## What this does not expose
+
+Deliberate omissions, so you can tell "not supported" from "not found yet".
+
+**GTFS files not ingested.** The static index reads `agency.txt`, `stops.txt`,
+`routes.txt`, `trips.txt`, `stop_times.txt`, `calendar.txt`,
+`calendar_dates.txt`, `frequencies.txt`, and `feed_info.txt`. Everything else
+in the zip is ignored:
+
+- `shapes.txt` — route geometry. Nothing here draws a line on a map, so trips
+  carry no `shape_id`.
+- `transfers.txt` — no transfer rules, minimum transfer times, or
+  trip-to-trip continuations, and no journey planning across a transfer.
+- `pathways.txt` / `levels.txt` — no in-station walking graph.
+- `fare_attributes.txt` / `fare_rules.txt` and all GTFS-Fares v2 files — no
+  fares, zone pricing, or rider categories. (`Stop.zone_id` is exposed as a
+  raw cell, but nothing interprets it.)
+- `translations.txt` — text is returned as the feed wrote it.
+
+Service calendars **are** answerable — `services_on(date)` resolves
+`calendar.txt` against `calendar_dates` exceptions, and rows carry their
+`service_id` — but the raw weekday pattern and validity range behind a
+service are not exposed as a model. `scheduled_departures(stops, start, end)`
+covers the range query a calendar view needs.
+
+**GTFS-RT: trip shapes.** The RT `shape` entity (a detour's new geometry) is
+not read, for the same reason `shapes.txt` is not: nothing here draws a line
+on a map. Detours themselves ARE applied — see *Detours are applied, not
+annotated* — and the `stop` entities they define are read.
+
+**GBFS endpoints not fetched.** `geofencing_zones`, because it is GeoJSON
+polygon geometry while zones here are deliberately circles — supporting it
+means polygon containment, which is a geometry feature rather than another
+document. And `system_hours`, which GBFS 3.0 removed in favour of
+`system_information.opening_hours` (exposed as `SystemInfo.opening_hours`).
+
+**Behaviour, not data.** There is no polling loop or scheduler (see *Pull, not
+push*), no write access of any kind, and no cross-feed journey planning.
+
 ## Error handling
 
 All errors derive from `MobilityDatabaseError`. The catalog and feeds layers
@@ -266,9 +384,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
@@ -327,11 +453,27 @@ The suite combines example-based, property-based, and conformance testing:
     resolver at volume), and `start_date`/`start_time` instance matching over
     windows containing two service-day instances of the same trip;
   - the circular-zone geometry (`in_circle`'s bbox prefilter is checked
-    against the exact haversine distance at generated boundary points);
+    against the exact great-circle distance at generated boundary points);
   - GBFS field parsing (`_localized`, `_version_key`, station/vehicle merging)
     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.5.0}/src/aiomobilitydatabase/const.py

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

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

@@ -26,13 +26,18 @@ from .models import (
     Agency,
     AlertCause,
     AlertEffect,
+    AlertImage,
     AlertSeverity,
+    ArrivalsQuery,
     BikesAllowed,
+    CarriageDetail,
     CongestionLevel,
     FeedInfo,
+    GbfsAlert,
     GbfsVehicle,
     OccupancyStatus,
     PickupDropOffType,
+    PricingPlan,
     Route,
     ServiceAlert,
     StaticBuildProgress,
@@ -42,9 +47,11 @@ from .models import (
     StopArrival,
     StopLocationType,
     SystemInfo,
+    SystemRegion,
     UpcomingTrip,
     VehiclePosition,
     VehicleStopStatus,
+    VehicleType,
     WheelchairAccess,
 )
 from .transit import TransitFeedHandle
@@ -53,18 +60,23 @@ __all__ = [
     "Agency",
     "AlertCause",
     "AlertEffect",
+    "AlertImage",
     "AlertSeverity",
+    "ArrivalsQuery",
     "BikesAllowed",
+    "CarriageDetail",
     "Circle",
     "CongestionLevel",
     "FeedInfo",
     "FeedParseError",
+    "GbfsAlert",
     "GbfsFeedHandle",
     "GbfsVehicle",
     "MobilityFeedsClient",
     "MobilityFeedsError",
     "OccupancyStatus",
     "PickupDropOffType",
+    "PricingPlan",
     "Route",
     "ServiceAlert",
     "SourceAuthenticationError",
@@ -77,9 +89,11 @@ __all__ = [
     "StopArrival",
     "StopLocationType",
     "SystemInfo",
+    "SystemRegion",
     "TransitFeedHandle",
     "UpcomingTrip",
     "VehiclePosition",
     "VehicleStopStatus",
+    "VehicleType",
     "WheelchairAccess",
 ]