aiomobilitydatabase 0.4.0__tar.gz → 0.6.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/.github/workflows/ci.yml +14 -0
  2. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/PKG-INFO +106 -19
  3. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/README.md +104 -17
  4. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/pyproject.toml +2 -2
  5. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/const.py +1 -1
  6. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/feeds/__init__.py +31 -10
  7. aiomobilitydatabase-0.6.0/src/aiomobilitydatabase/feeds/_extra.py +24 -0
  8. aiomobilitydatabase-0.6.0/src/aiomobilitydatabase/feeds/_urls.py +28 -0
  9. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/feeds/client.py +7 -4
  10. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/feeds/gbfs.py +229 -10
  11. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/feeds/geo.py +24 -11
  12. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/feeds/models.py +191 -9
  13. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/feeds/rt.py +307 -32
  14. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/feeds/static_index.py +186 -18
  15. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/feeds/transit.py +563 -34
  16. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/catalog/gbfs_feed.json +16 -0
  17. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/gbfs/discovery_23.json +16 -0
  18. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/gbfs/free_bike_status_23.json +6 -1
  19. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/gbfs/station_info_23.json +7 -1
  20. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/gbfs/station_status_23.json +7 -2
  21. aiomobilitydatabase-0.6.0/tests/feeds/data/gbfs/system_alerts.json +33 -0
  22. aiomobilitydatabase-0.6.0/tests/feeds/data/gbfs/system_info_23.json +22 -0
  23. aiomobilitydatabase-0.6.0/tests/feeds/data/gbfs/system_pricing_plans.json +19 -0
  24. aiomobilitydatabase-0.6.0/tests/feeds/data/gbfs/system_regions.json +15 -0
  25. aiomobilitydatabase-0.6.0/tests/feeds/data/gbfs/vehicle_types.json +24 -0
  26. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/fixtures.py +4 -0
  27. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_descriptive_attributes.py +16 -5
  28. aiomobilitydatabase-0.6.0/tests/feeds/test_extra_import_guard.py +97 -0
  29. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_gbfs_stations.py +255 -1
  30. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_gbfs_vehicles.py +68 -0
  31. aiomobilitydatabase-0.6.0/tests/feeds/test_geo.py +90 -0
  32. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_models.py +69 -4
  33. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_properties.py +35 -16
  34. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_rt.py +178 -6
  35. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_sample_feed.py +14 -3
  36. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_static_build.py +153 -0
  37. aiomobilitydatabase-0.6.0/tests/feeds/test_transit_arrivals.py +1039 -0
  38. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_transit_frequencies.py +75 -0
  39. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_transit_trips.py +90 -2
  40. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_transit_vehicles_alerts.py +147 -1
  41. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/mock_server.py +16 -3
  42. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/test_client_token.py +6 -2
  43. aiomobilitydatabase-0.4.0/tests/feeds/data/gbfs/system_info_23.json +0 -10
  44. aiomobilitydatabase-0.4.0/tests/feeds/test_extra_import_guard.py +0 -38
  45. aiomobilitydatabase-0.4.0/tests/feeds/test_geo.py +0 -38
  46. aiomobilitydatabase-0.4.0/tests/feeds/test_transit_arrivals.py +0 -482
  47. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/.github/workflows/publish.yml +0 -0
  48. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/.gitignore +0 -0
  49. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/.pre-commit-config.yaml +0 -0
  50. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/LICENSE +0 -0
  51. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/scripts/generate_rt_fixtures.py +0 -0
  52. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/__init__.py +0 -0
  53. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/client.py +0 -0
  54. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/exceptions.py +0 -0
  55. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/feeds/const.py +0 -0
  56. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/feeds/exceptions.py +0 -0
  57. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/models.py +0 -0
  58. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/src/aiomobilitydatabase/py.typed +0 -0
  59. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/__init__.py +0 -0
  60. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/conftest.py +0 -0
  61. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/__init__.py +0 -0
  62. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/conftest.py +0 -0
  63. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/catalog/gtfs_feed.json +0 -0
  64. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/catalog/gtfs_rt_feed.json +0 -0
  65. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/catalog/token_response.json +0 -0
  66. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/gbfs/discovery_30.json +0 -0
  67. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/gbfs/system_info_30.json +0 -0
  68. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/gbfs/vehicle_status_30.json +0 -0
  69. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/gtfs/agency.txt +0 -0
  70. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/gtfs/calendar.txt +0 -0
  71. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/gtfs/calendar_dates.txt +0 -0
  72. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/gtfs/routes.txt +0 -0
  73. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/gtfs/stop_times.txt +0 -0
  74. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/gtfs/stops.txt +0 -0
  75. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/gtfs/trips.txt +0 -0
  76. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/added_trips_s1.pb +0 -0
  77. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/alerts.pb +0 -0
  78. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/alerts_trip_scoped.pb +0 -0
  79. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_baseline.pb +0 -0
  80. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_freq_bare_cancel.pb +0 -0
  81. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_freq_canceled_tomorrow.pb +0 -0
  82. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_freq_matched.pb +0 -0
  83. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_freq_unmatched.pb +0 -0
  84. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_t1_both_ends.pb +0 -0
  85. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_t1_canceled.pb +0 -0
  86. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_t1_canceled_tomorrow.pb +0 -0
  87. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_t1_dated_tomorrow_delay.pb +0 -0
  88. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_t1_delayed.pb +0 -0
  89. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_t1_dest_arrival.pb +0 -0
  90. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_t1_no_data_cut.pb +0 -0
  91. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_t1_skip_s1.pb +0 -0
  92. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_t1_skip_s2.pb +0 -0
  93. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_t1_skip_s3.pb +0 -0
  94. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/trip_updates_t1_trip_delay.pb +0 -0
  95. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/vehicle_positions.pb +0 -0
  96. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/rt/vehicle_positions_status.pb +0 -0
  97. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/README.md +0 -0
  98. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/agency.txt +0 -0
  99. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/calendar.txt +0 -0
  100. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/calendar_dates.txt +0 -0
  101. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/fare_attributes.txt +0 -0
  102. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/fare_rules.txt +0 -0
  103. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/feed_info.txt +0 -0
  104. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/frequencies.txt +0 -0
  105. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/routes.txt +0 -0
  106. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/shapes.txt +0 -0
  107. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/stop_times.txt +0 -0
  108. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/stops.txt +0 -0
  109. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/transfers.txt +0 -0
  110. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/translations.txt +0 -0
  111. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/data/sample_feed/trips.txt +0 -0
  112. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_client.py +0 -0
  113. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_direct_urls.py +0 -0
  114. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_exceptions.py +0 -0
  115. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_static_arrivals.py +0 -0
  116. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_static_frequencies.py +0 -0
  117. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_static_trips.py +0 -0
  118. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_station_grouping.py +0 -0
  119. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/feeds/test_transit_resolution.py +0 -0
  120. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/fixtures.py +0 -0
  121. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/test_catalog_properties.py +0 -0
  122. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/test_client_request.py +0 -0
  123. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/test_client_session.py +0 -0
  124. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/test_endpoints.py +0 -0
  125. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/test_exceptions.py +0 -0
  126. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/test_models.py +0 -0
  127. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/test_params.py +0 -0
  128. {aiomobilitydatabase-0.4.0 → aiomobilitydatabase-0.6.0}/tests/test_public_api.py +0 -0
@@ -27,3 +27,17 @@ jobs:
27
27
  run: uv run mypy src
28
28
  - name: Test
29
29
  run: uv run pytest --cov=aiomobilitydatabase --cov-report=term-missing
30
+
31
+ test-lowest:
32
+ # Consumers such as Home Assistant can pin a dependency to its declared
33
+ # floor, so the floors must actually work.
34
+ runs-on: ubuntu-latest
35
+ steps:
36
+ - uses: actions/checkout@v4
37
+ - uses: astral-sh/setup-uv@v5
38
+ with:
39
+ python-version: "3.12"
40
+ - name: Install lowest direct dependencies
41
+ run: uv sync --dev --resolution lowest-direct
42
+ - name: Test
43
+ run: uv run --no-sync pytest
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: aiomobilitydatabase
3
- Version: 0.4.0
3
+ Version: 0.6.0
4
4
  Summary: Async Python client for the Mobility Database catalog API
5
5
  Project-URL: Source Code, https://github.com/raman325/aiomobilitydatabase
6
6
  Project-URL: Bug Reports, https://github.com/raman325/aiomobilitydatabase/issues
@@ -19,7 +19,7 @@ Requires-Python: >=3.12
19
19
  Requires-Dist: aiohttp>=3.9
20
20
  Requires-Dist: mashumaro>=3.13
21
21
  Provides-Extra: feeds
22
- Requires-Dist: gtfs-realtime-bindings>=1.0.0; extra == 'feeds'
22
+ Requires-Dist: gtfs-realtime-bindings>=3.0.0; extra == 'feeds'
23
23
  Description-Content-Type: text/markdown
24
24
 
25
25
  # aiomobilitydatabase
@@ -31,7 +31,7 @@ agencies and bike/scooter share systems around the world.
31
31
  The core package wraps the catalog's
32
32
  [REST API](https://mobilitydata.github.io/mobility-feed-api/SwaggerUI/index.html)
33
33
  with a fully typed asyncio client: search feeds, look up their metadata, find the
34
- hosted dataset URL. An optional `feeds` layer goes one step further and consumes
34
+ hosted dataset URL. The `feeds` layer goes one step further and consumes
35
35
  the actual transit/bike-share data those feeds point to — scheduled and live
36
36
  arrivals, origin→destination trip queries, vehicle positions, service alerts,
37
37
  GBFS stations and vehicles — giving you a feed ID (or a plain feed URL) in and
@@ -43,8 +43,8 @@ typed snapshots out.
43
43
  pip install aiomobilitydatabase
44
44
  ```
45
45
 
46
- That installs the catalog client only. To also consume feed data (schedules,
47
- GTFS-RT, GBFS), install the `feeds` extra, which pulls in
46
+ That installs the catalog client and GBFS feeds. To also consume GTFS
47
+ schedules and GTFS-RT, install the `feeds` extra, which pulls in
48
48
  [`gtfs-realtime-bindings`](https://pypi.org/project/gtfs-realtime-bindings/) for
49
49
  protobuf parsing:
50
50
 
@@ -52,9 +52,10 @@ protobuf parsing:
52
52
  pip install aiomobilitydatabase[feeds]
53
53
  ```
54
54
 
55
- Importing `aiomobilitydatabase.feeds` without the extra installed raises an
56
- `ImportError` telling you to install it — there is no silent partial-functionality
57
- mode.
55
+ Using `TransitFeedHandle` or `MobilityFeedsClient.get_transit_feed*` without
56
+ the extra raises an `ImportError` telling you to install it. This is fail-loud
57
+ by design: without the extra, `from aiomobilitydatabase.feeds import *` and
58
+ `hasattr(feeds, "TransitFeedHandle")` raise that `ImportError` too.
58
59
 
59
60
  Requires Python 3.12+.
60
61
 
@@ -95,11 +96,11 @@ async def main() -> None:
95
96
  asyncio.run(main())
96
97
  ```
97
98
 
98
- ## Quick start — feeds (optional extra)
99
+ ## Quick start — feeds
99
100
 
100
101
  `MobilityFeedsClient` resolves a feed ID (GTFS, GTFS-RT, or GBFS) into a handle
101
- that fetches and caches the actual data. Requires `pip install
102
- aiomobilitydatabase[feeds]`.
102
+ that fetches and caches the actual data. GBFS needs no extra; GTFS and GTFS-RT
103
+ (`get_transit_feed*`) require `pip install aiomobilitydatabase[feeds]`.
103
104
 
104
105
  ```python
105
106
  import asyncio
@@ -147,7 +148,10 @@ async def main() -> None:
147
148
  for arrival in arrivals:
148
149
  when = arrival.predicted_departure or arrival.scheduled_departure
149
150
  live = "live" if arrival.realtime else "scheduled"
150
- print(f"{arrival.route_name} -> {arrival.headsign}: {when} ({live})")
151
+ # .stop and .route are the whole static records: platform codes,
152
+ # coordinates, route_type and route colours all come along.
153
+ route = arrival.route.display_name if arrival.route else arrival.route_id
154
+ print(f"{route} -> {arrival.headsign}: {when} ({live})")
151
155
 
152
156
  # Origin→destination: the next departures from stop A on trips that
153
157
  # later reach stop B, with the same realtime overlay. is_first/is_last
@@ -156,7 +160,8 @@ async def main() -> None:
156
160
  nearby_stops[0].id, nearby_stops[1].id, limit=2
157
161
  )
158
162
  for trip in trips:
159
- print(trip.route_name, trip.scheduled_departure, trip.is_last)
163
+ name = trip.route.display_name if trip.route else trip.route_id
164
+ print(name, trip.scheduled_departure, trip.is_last)
160
165
 
161
166
  vehicles = await transit.get_vehicles()
162
167
  alerts = await transit.get_alerts()
@@ -253,6 +258,19 @@ Notes on direct mode:
253
258
  information, `NO_DATA` makes a stop schedule-only, `SKIPPED` suppresses it
254
259
  (and any origin→destination row boarding or alighting there), and the
255
260
  trip-level delay covers stops no StopTimeUpdate reaches.
261
+ - **Rows carry whole records, not copied columns**: `StopArrival`,
262
+ `UpcomingTrip`, and `VehiclePosition` each expose the full `Stop` and
263
+ `Route` they refer to, so platform codes, coordinates, route colours and
264
+ `route_type` are reachable without a second lookup — use
265
+ `route.display_name` / `stop.name` for the human-readable strings. The raw
266
+ `stop_id`/`route_id` stay alongside, since those are what feeds reference
267
+ and what filters key on; a `route_id` naming a route absent from
268
+ `routes.txt` leaves `route` as `None` rather than inventing one.
269
+ - **Vehicle positions name their trip instance**: `VehiclePosition` carries
270
+ the parsed `trip_start_date`/`trip_start_secs`, the pair a GTFS-RT
271
+ `TripDescriptor` uses to address one run. That is what lets two buses out
272
+ on the same headway-based trip be told apart — without it, concurrent
273
+ repetitions of one template trip are indistinguishable.
256
274
  - **The full descriptive surface is exposed, typed by shape**: closed GTFS
257
275
  vocabularies are enums (`WheelchairAccess`, `BikesAllowed`,
258
276
  `PickupDropOffType`, `StopLocationType`, alert cause/effect/severity,
@@ -268,14 +286,44 @@ Notes on direct mode:
268
286
  fails the build, because a wrong departure time or a wrong call order is
269
287
  worse than no feed at all. A malformed **descriptive** cell still degrades
270
288
  to `None`.
289
+ - **Detours are applied, not annotated**: a GTFS-RT `TripModifications`
290
+ entity REPLACES a span of a trip's calls, so a board that ignored it
291
+ would keep showing departures at stops the vehicle no longer serves, and
292
+ would miss `propagated_modification_delay` on every stop after the
293
+ detour. Replacement times are measured from the reference stop the spec
294
+ names, a replacement stop may be defined only by an RT `Stop` entity, and
295
+ a detour that routes a trip through a stop its static schedule never
296
+ served shows up there.
297
+ - **Schedule over a range**: `scheduled_departures(stops, start, end)` is
298
+ the calendar query — every departure between two instants, schedule only,
299
+ no limit and no grace, rather than `get_arrivals` stretched to days.
300
+ - **Service calendars are answerable**: `services_on(date)` returns the
301
+ service ids running on a GTFS service date — `calendar.txt` resolved
302
+ against `calendar_dates` exceptions, removals winning when a producer
303
+ lists both types for one date — and every row carries its `service_id`,
304
+ so "does this trip run next Tuesday" needs no second arrivals query.
305
+ - **GBFS ids resolve**: `get_vehicle_types()`, `get_pricing_plans()`,
306
+ `get_regions()`, and `get_system_alerts()` turn the `vehicle_type_id`,
307
+ `pricing_plan_id`, and `region_id` on stations and vehicles into records.
308
+ All four documents are optional in GBFS, so an unpublished one is `[]`
309
+ rather than an error.
271
310
  - **Static metadata accessors**: `transit.agencies`, `transit.feed_info`
272
311
  (publisher, version, validity dates — useful for staleness checks), and
273
312
  `headsigns_serving()` alongside the stop/route helpers.
274
- - **Alert scoping**: `ServiceAlert` carries `route_ids`, `stop_ids`, and
275
- `trip_ids`; an alert is agency-wide only when all three are empty.
276
- `is_active(at)` evaluates its active periods.
277
- - **GBFS extras**: `rental_uris` deep links on stations and vehicles,
278
- `get_system_info()`, and TTL-based document caching.
313
+ - **Alert scoping covers every selector GTFS-RT offers**: `ServiceAlert`
314
+ carries `agency_ids`, `route_ids`, `route_types`, `direction_ids`,
315
+ `stop_ids`, and `trip_ids` — an alert is feed-wide only when *all* of them
316
+ are empty. Collecting a subset is not a missing nicety but a correctness
317
+ bug: an alert scoped to one agency, or to a whole mode, would otherwise
318
+ read as applying everywhere. `is_active(at)` evaluates its active periods.
319
+ - **GBFS exposes what the documents carry**: the full station surface
320
+ (`is_installed` alongside `is_renting`/`is_returning` — a station removed
321
+ from the street is not "operational"; disabled counts, address, region,
322
+ virtual-station flag), free-floating vehicle docking and fuel state, and a
323
+ `SystemInfo` with the operator's contact, licensing, and terms URLs.
324
+ `last_reported` is exposed on both stations and vehicles so you can tell
325
+ fresh data from stale, and is parsed from either GBFS 2.x POSIX seconds or
326
+ 3.0 RFC3339. Plus `rental_uris` deep links and TTL-based document caching.
279
327
  - **`cache_dir` strongly recommended**: the static index is cached on disk
280
328
  keyed by feed, validated against the dataset ID, so restarts are instant and
281
329
  rebuilds only happen when the agency publishes a new dataset
@@ -306,6 +354,45 @@ Notes on direct mode:
306
354
  design, with no server-side geo-query.
307
355
  - **Timestamps are tz-aware UTC** throughout the feeds layer.
308
356
 
357
+ ## What this does not expose
358
+
359
+ Deliberate omissions, so you can tell "not supported" from "not found yet".
360
+
361
+ **GTFS files not ingested.** The static index reads `agency.txt`, `stops.txt`,
362
+ `routes.txt`, `trips.txt`, `stop_times.txt`, `calendar.txt`,
363
+ `calendar_dates.txt`, `frequencies.txt`, and `feed_info.txt`. Everything else
364
+ in the zip is ignored:
365
+
366
+ - `shapes.txt` — route geometry. Nothing here draws a line on a map, so trips
367
+ carry no `shape_id`.
368
+ - `transfers.txt` — no transfer rules, minimum transfer times, or
369
+ trip-to-trip continuations, and no journey planning across a transfer.
370
+ - `pathways.txt` / `levels.txt` — no in-station walking graph.
371
+ - `fare_attributes.txt` / `fare_rules.txt` and all GTFS-Fares v2 files — no
372
+ fares, zone pricing, or rider categories. (`Stop.zone_id` is exposed as a
373
+ raw cell, but nothing interprets it.)
374
+ - `translations.txt` — text is returned as the feed wrote it.
375
+
376
+ Service calendars **are** answerable — `services_on(date)` resolves
377
+ `calendar.txt` against `calendar_dates` exceptions, and rows carry their
378
+ `service_id` — but the raw weekday pattern and validity range behind a
379
+ service are not exposed as a model. `scheduled_departures(stops, start, end)`
380
+ covers the range query a calendar view needs.
381
+
382
+ **GTFS-RT: trip shapes.** The RT `shape` entity (a detour's new geometry) is
383
+ not read, for the same reason `shapes.txt` is not: nothing here draws a line
384
+ on a map. Detours themselves ARE applied — see *Detours are applied, not
385
+ annotated* — and the `stop` entities they define are read.
386
+
387
+ **GBFS endpoints not fetched.** `geofencing_zones`, because it is GeoJSON
388
+ polygon geometry while zones here are deliberately circles — supporting it
389
+ means polygon containment, which is a geometry feature rather than another
390
+ document. And `system_hours`, which GBFS 3.0 removed in favour of
391
+ `system_information.opening_hours` (exposed as `SystemInfo.opening_hours`).
392
+
393
+ **Behaviour, not data.** There is no polling loop or scheduler (see *Pull, not
394
+ push*), no write access of any kind, and no cross-feed journey planning.
395
+
309
396
  ## Error handling
310
397
 
311
398
  All errors derive from `MobilityDatabaseError`. The catalog and feeds layers
@@ -391,7 +478,7 @@ The suite combines example-based, property-based, and conformance testing:
391
478
  resolver at volume), and `start_date`/`start_time` instance matching over
392
479
  windows containing two service-day instances of the same trip;
393
480
  - the circular-zone geometry (`in_circle`'s bbox prefilter is checked
394
- against the exact haversine distance at generated boundary points);
481
+ against the exact great-circle distance at generated boundary points);
395
482
  - GBFS field parsing (`_localized`, `_version_key`, station/vehicle merging)
396
483
  and GTFS-RT protobuf parsing, both checked for **totality** — every
397
484
  generated input must produce a typed result or a documented
@@ -7,7 +7,7 @@ agencies and bike/scooter share systems around the world.
7
7
  The core package wraps the catalog's
8
8
  [REST API](https://mobilitydata.github.io/mobility-feed-api/SwaggerUI/index.html)
9
9
  with a fully typed asyncio client: search feeds, look up their metadata, find the
10
- hosted dataset URL. An optional `feeds` layer goes one step further and consumes
10
+ hosted dataset URL. The `feeds` layer goes one step further and consumes
11
11
  the actual transit/bike-share data those feeds point to — scheduled and live
12
12
  arrivals, origin→destination trip queries, vehicle positions, service alerts,
13
13
  GBFS stations and vehicles — giving you a feed ID (or a plain feed URL) in and
@@ -19,8 +19,8 @@ typed snapshots out.
19
19
  pip install aiomobilitydatabase
20
20
  ```
21
21
 
22
- That installs the catalog client only. To also consume feed data (schedules,
23
- GTFS-RT, GBFS), install the `feeds` extra, which pulls in
22
+ That installs the catalog client and GBFS feeds. To also consume GTFS
23
+ schedules and GTFS-RT, install the `feeds` extra, which pulls in
24
24
  [`gtfs-realtime-bindings`](https://pypi.org/project/gtfs-realtime-bindings/) for
25
25
  protobuf parsing:
26
26
 
@@ -28,9 +28,10 @@ protobuf parsing:
28
28
  pip install aiomobilitydatabase[feeds]
29
29
  ```
30
30
 
31
- Importing `aiomobilitydatabase.feeds` without the extra installed raises an
32
- `ImportError` telling you to install it — there is no silent partial-functionality
33
- mode.
31
+ Using `TransitFeedHandle` or `MobilityFeedsClient.get_transit_feed*` without
32
+ the extra raises an `ImportError` telling you to install it. This is fail-loud
33
+ by design: without the extra, `from aiomobilitydatabase.feeds import *` and
34
+ `hasattr(feeds, "TransitFeedHandle")` raise that `ImportError` too.
34
35
 
35
36
  Requires Python 3.12+.
36
37
 
@@ -71,11 +72,11 @@ async def main() -> None:
71
72
  asyncio.run(main())
72
73
  ```
73
74
 
74
- ## Quick start — feeds (optional extra)
75
+ ## Quick start — feeds
75
76
 
76
77
  `MobilityFeedsClient` resolves a feed ID (GTFS, GTFS-RT, or GBFS) into a handle
77
- that fetches and caches the actual data. Requires `pip install
78
- aiomobilitydatabase[feeds]`.
78
+ that fetches and caches the actual data. GBFS needs no extra; GTFS and GTFS-RT
79
+ (`get_transit_feed*`) require `pip install aiomobilitydatabase[feeds]`.
79
80
 
80
81
  ```python
81
82
  import asyncio
@@ -123,7 +124,10 @@ async def main() -> None:
123
124
  for arrival in arrivals:
124
125
  when = arrival.predicted_departure or arrival.scheduled_departure
125
126
  live = "live" if arrival.realtime else "scheduled"
126
- print(f"{arrival.route_name} -> {arrival.headsign}: {when} ({live})")
127
+ # .stop and .route are the whole static records: platform codes,
128
+ # coordinates, route_type and route colours all come along.
129
+ route = arrival.route.display_name if arrival.route else arrival.route_id
130
+ print(f"{route} -> {arrival.headsign}: {when} ({live})")
127
131
 
128
132
  # Origin→destination: the next departures from stop A on trips that
129
133
  # later reach stop B, with the same realtime overlay. is_first/is_last
@@ -132,7 +136,8 @@ async def main() -> None:
132
136
  nearby_stops[0].id, nearby_stops[1].id, limit=2
133
137
  )
134
138
  for trip in trips:
135
- print(trip.route_name, trip.scheduled_departure, trip.is_last)
139
+ name = trip.route.display_name if trip.route else trip.route_id
140
+ print(name, trip.scheduled_departure, trip.is_last)
136
141
 
137
142
  vehicles = await transit.get_vehicles()
138
143
  alerts = await transit.get_alerts()
@@ -229,6 +234,19 @@ Notes on direct mode:
229
234
  information, `NO_DATA` makes a stop schedule-only, `SKIPPED` suppresses it
230
235
  (and any origin→destination row boarding or alighting there), and the
231
236
  trip-level delay covers stops no StopTimeUpdate reaches.
237
+ - **Rows carry whole records, not copied columns**: `StopArrival`,
238
+ `UpcomingTrip`, and `VehiclePosition` each expose the full `Stop` and
239
+ `Route` they refer to, so platform codes, coordinates, route colours and
240
+ `route_type` are reachable without a second lookup — use
241
+ `route.display_name` / `stop.name` for the human-readable strings. The raw
242
+ `stop_id`/`route_id` stay alongside, since those are what feeds reference
243
+ and what filters key on; a `route_id` naming a route absent from
244
+ `routes.txt` leaves `route` as `None` rather than inventing one.
245
+ - **Vehicle positions name their trip instance**: `VehiclePosition` carries
246
+ the parsed `trip_start_date`/`trip_start_secs`, the pair a GTFS-RT
247
+ `TripDescriptor` uses to address one run. That is what lets two buses out
248
+ on the same headway-based trip be told apart — without it, concurrent
249
+ repetitions of one template trip are indistinguishable.
232
250
  - **The full descriptive surface is exposed, typed by shape**: closed GTFS
233
251
  vocabularies are enums (`WheelchairAccess`, `BikesAllowed`,
234
252
  `PickupDropOffType`, `StopLocationType`, alert cause/effect/severity,
@@ -244,14 +262,44 @@ Notes on direct mode:
244
262
  fails the build, because a wrong departure time or a wrong call order is
245
263
  worse than no feed at all. A malformed **descriptive** cell still degrades
246
264
  to `None`.
265
+ - **Detours are applied, not annotated**: a GTFS-RT `TripModifications`
266
+ entity REPLACES a span of a trip's calls, so a board that ignored it
267
+ would keep showing departures at stops the vehicle no longer serves, and
268
+ would miss `propagated_modification_delay` on every stop after the
269
+ detour. Replacement times are measured from the reference stop the spec
270
+ names, a replacement stop may be defined only by an RT `Stop` entity, and
271
+ a detour that routes a trip through a stop its static schedule never
272
+ served shows up there.
273
+ - **Schedule over a range**: `scheduled_departures(stops, start, end)` is
274
+ the calendar query — every departure between two instants, schedule only,
275
+ no limit and no grace, rather than `get_arrivals` stretched to days.
276
+ - **Service calendars are answerable**: `services_on(date)` returns the
277
+ service ids running on a GTFS service date — `calendar.txt` resolved
278
+ against `calendar_dates` exceptions, removals winning when a producer
279
+ lists both types for one date — and every row carries its `service_id`,
280
+ so "does this trip run next Tuesday" needs no second arrivals query.
281
+ - **GBFS ids resolve**: `get_vehicle_types()`, `get_pricing_plans()`,
282
+ `get_regions()`, and `get_system_alerts()` turn the `vehicle_type_id`,
283
+ `pricing_plan_id`, and `region_id` on stations and vehicles into records.
284
+ All four documents are optional in GBFS, so an unpublished one is `[]`
285
+ rather than an error.
247
286
  - **Static metadata accessors**: `transit.agencies`, `transit.feed_info`
248
287
  (publisher, version, validity dates — useful for staleness checks), and
249
288
  `headsigns_serving()` alongside the stop/route helpers.
250
- - **Alert scoping**: `ServiceAlert` carries `route_ids`, `stop_ids`, and
251
- `trip_ids`; an alert is agency-wide only when all three are empty.
252
- `is_active(at)` evaluates its active periods.
253
- - **GBFS extras**: `rental_uris` deep links on stations and vehicles,
254
- `get_system_info()`, and TTL-based document caching.
289
+ - **Alert scoping covers every selector GTFS-RT offers**: `ServiceAlert`
290
+ carries `agency_ids`, `route_ids`, `route_types`, `direction_ids`,
291
+ `stop_ids`, and `trip_ids` — an alert is feed-wide only when *all* of them
292
+ are empty. Collecting a subset is not a missing nicety but a correctness
293
+ bug: an alert scoped to one agency, or to a whole mode, would otherwise
294
+ read as applying everywhere. `is_active(at)` evaluates its active periods.
295
+ - **GBFS exposes what the documents carry**: the full station surface
296
+ (`is_installed` alongside `is_renting`/`is_returning` — a station removed
297
+ from the street is not "operational"; disabled counts, address, region,
298
+ virtual-station flag), free-floating vehicle docking and fuel state, and a
299
+ `SystemInfo` with the operator's contact, licensing, and terms URLs.
300
+ `last_reported` is exposed on both stations and vehicles so you can tell
301
+ fresh data from stale, and is parsed from either GBFS 2.x POSIX seconds or
302
+ 3.0 RFC3339. Plus `rental_uris` deep links and TTL-based document caching.
255
303
  - **`cache_dir` strongly recommended**: the static index is cached on disk
256
304
  keyed by feed, validated against the dataset ID, so restarts are instant and
257
305
  rebuilds only happen when the agency publishes a new dataset
@@ -282,6 +330,45 @@ Notes on direct mode:
282
330
  design, with no server-side geo-query.
283
331
  - **Timestamps are tz-aware UTC** throughout the feeds layer.
284
332
 
333
+ ## What this does not expose
334
+
335
+ Deliberate omissions, so you can tell "not supported" from "not found yet".
336
+
337
+ **GTFS files not ingested.** The static index reads `agency.txt`, `stops.txt`,
338
+ `routes.txt`, `trips.txt`, `stop_times.txt`, `calendar.txt`,
339
+ `calendar_dates.txt`, `frequencies.txt`, and `feed_info.txt`. Everything else
340
+ in the zip is ignored:
341
+
342
+ - `shapes.txt` — route geometry. Nothing here draws a line on a map, so trips
343
+ carry no `shape_id`.
344
+ - `transfers.txt` — no transfer rules, minimum transfer times, or
345
+ trip-to-trip continuations, and no journey planning across a transfer.
346
+ - `pathways.txt` / `levels.txt` — no in-station walking graph.
347
+ - `fare_attributes.txt` / `fare_rules.txt` and all GTFS-Fares v2 files — no
348
+ fares, zone pricing, or rider categories. (`Stop.zone_id` is exposed as a
349
+ raw cell, but nothing interprets it.)
350
+ - `translations.txt` — text is returned as the feed wrote it.
351
+
352
+ Service calendars **are** answerable — `services_on(date)` resolves
353
+ `calendar.txt` against `calendar_dates` exceptions, and rows carry their
354
+ `service_id` — but the raw weekday pattern and validity range behind a
355
+ service are not exposed as a model. `scheduled_departures(stops, start, end)`
356
+ covers the range query a calendar view needs.
357
+
358
+ **GTFS-RT: trip shapes.** The RT `shape` entity (a detour's new geometry) is
359
+ not read, for the same reason `shapes.txt` is not: nothing here draws a line
360
+ on a map. Detours themselves ARE applied — see *Detours are applied, not
361
+ annotated* — and the `stop` entities they define are read.
362
+
363
+ **GBFS endpoints not fetched.** `geofencing_zones`, because it is GeoJSON
364
+ polygon geometry while zones here are deliberately circles — supporting it
365
+ means polygon containment, which is a geometry feature rather than another
366
+ document. And `system_hours`, which GBFS 3.0 removed in favour of
367
+ `system_information.opening_hours` (exposed as `SystemInfo.opening_hours`).
368
+
369
+ **Behaviour, not data.** There is no polling loop or scheduler (see *Pull, not
370
+ push*), no write access of any kind, and no cross-feed journey planning.
371
+
285
372
  ## Error handling
286
373
 
287
374
  All errors derive from `MobilityDatabaseError`. The catalog and feeds layers
@@ -367,7 +454,7 @@ The suite combines example-based, property-based, and conformance testing:
367
454
  resolver at volume), and `start_date`/`start_time` instance matching over
368
455
  windows containing two service-day instances of the same trip;
369
456
  - the circular-zone geometry (`in_circle`'s bbox prefilter is checked
370
- against the exact haversine distance at generated boundary points);
457
+ against the exact great-circle distance at generated boundary points);
371
458
  - GBFS field parsing (`_localized`, `_version_key`, station/vehicle merging)
372
459
  and GTFS-RT protobuf parsing, both checked for **totality** — every
373
460
  generated input must produce a typed result or a documented
@@ -27,7 +27,7 @@ dependencies = [
27
27
  dynamic = ["version"]
28
28
 
29
29
  [project.optional-dependencies]
30
- feeds = ["gtfs-realtime-bindings>=1.0.0"]
30
+ feeds = ["gtfs-realtime-bindings>=3.0.0"]
31
31
 
32
32
  [project.urls]
33
33
  "Source Code" = "https://github.com/raman325/aiomobilitydatabase"
@@ -35,7 +35,7 @@ feeds = ["gtfs-realtime-bindings>=1.0.0"]
35
35
 
36
36
  [dependency-groups]
37
37
  dev = [
38
- "gtfs-realtime-bindings>=1.0.0",
38
+ "gtfs-realtime-bindings>=3.0.0",
39
39
  "hypothesis>=6.100",
40
40
  "mypy>=1.14",
41
41
  "pre-commit>=4.0",
@@ -1,6 +1,6 @@
1
1
  """Constants for aiomobilitydatabase."""
2
2
 
3
- __version__ = "0.4.0"
3
+ __version__ = "0.6.0"
4
4
 
5
5
  PROD_BASE_URL = "https://api.mobilitydatabase.org"
6
6
  QA_BASE_URL = "https://api-qa.mobilitydatabase.org"
@@ -1,17 +1,14 @@
1
1
  """Typed async consumption of Mobility Database transit and GBFS feeds.
2
2
 
3
- Requires the ``feeds`` extra (``pip install aiomobilitydatabase[feeds]``) for
4
- the ``gtfs-realtime-bindings`` protobuf dependency.
3
+ GBFS works with the base install. GTFS and GTFS-RT (``TransitFeedHandle``,
4
+ ``MobilityFeedsClient.get_transit_feed*``) need the ``feeds`` extra
5
+ (``pip install aiomobilitydatabase[feeds]``) for protobuf; using them
6
+ without it raises an ``ImportError`` naming the extra.
5
7
  """
6
8
 
7
- try:
8
- from google.transit import gtfs_realtime_pb2 as _pb2_check # noqa: F401
9
- except ImportError as err:
10
- raise ImportError(
11
- "aiomobilitydatabase.feeds requires the 'feeds' extra: "
12
- "pip install aiomobilitydatabase[feeds]"
13
- ) from err
9
+ from typing import TYPE_CHECKING, Any
14
10
 
11
+ from . import _extra
15
12
  from .client import MobilityFeedsClient
16
13
  from .exceptions import (
17
14
  FeedParseError,
@@ -26,14 +23,18 @@ from .models import (
26
23
  Agency,
27
24
  AlertCause,
28
25
  AlertEffect,
26
+ AlertImage,
29
27
  AlertSeverity,
30
28
  ArrivalsQuery,
31
29
  BikesAllowed,
30
+ CarriageDetail,
32
31
  CongestionLevel,
33
32
  FeedInfo,
33
+ GbfsAlert,
34
34
  GbfsVehicle,
35
35
  OccupancyStatus,
36
36
  PickupDropOffType,
37
+ PricingPlan,
37
38
  Route,
38
39
  ServiceAlert,
39
40
  StaticBuildProgress,
@@ -43,30 +44,48 @@ from .models import (
43
44
  StopArrival,
44
45
  StopLocationType,
45
46
  SystemInfo,
47
+ SystemRegion,
46
48
  UpcomingTrip,
47
49
  VehiclePosition,
48
50
  VehicleStopStatus,
51
+ VehicleType,
49
52
  WheelchairAccess,
50
53
  )
51
- from .transit import TransitFeedHandle
54
+
55
+ if TYPE_CHECKING:
56
+ from .transit import TransitFeedHandle
57
+
58
+
59
+ if not TYPE_CHECKING:
60
+
61
+ def __getattr__(name: str) -> Any:
62
+ """Load TransitFeedHandle on first access, so GBFS needs no protobuf."""
63
+ if name == "TransitFeedHandle":
64
+ return _extra.load_transit_handle()
65
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
66
+
52
67
 
53
68
  __all__ = [
54
69
  "Agency",
55
70
  "AlertCause",
56
71
  "AlertEffect",
72
+ "AlertImage",
57
73
  "AlertSeverity",
58
74
  "ArrivalsQuery",
59
75
  "BikesAllowed",
76
+ "CarriageDetail",
60
77
  "Circle",
61
78
  "CongestionLevel",
62
79
  "FeedInfo",
63
80
  "FeedParseError",
81
+ "GbfsAlert",
64
82
  "GbfsFeedHandle",
65
83
  "GbfsVehicle",
66
84
  "MobilityFeedsClient",
67
85
  "MobilityFeedsError",
68
86
  "OccupancyStatus",
69
87
  "PickupDropOffType",
88
+ "PricingPlan",
70
89
  "Route",
71
90
  "ServiceAlert",
72
91
  "SourceAuthenticationError",
@@ -79,9 +98,11 @@ __all__ = [
79
98
  "StopArrival",
80
99
  "StopLocationType",
81
100
  "SystemInfo",
101
+ "SystemRegion",
82
102
  "TransitFeedHandle",
83
103
  "UpcomingTrip",
84
104
  "VehiclePosition",
85
105
  "VehicleStopStatus",
106
+ "VehicleType",
86
107
  "WheelchairAccess",
87
108
  ]
@@ -0,0 +1,24 @@
1
+ """Lazy access to the GTFS / GTFS-RT handle, which needs the ``feeds`` extra."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import TYPE_CHECKING
6
+
7
+ if TYPE_CHECKING:
8
+ from .transit import TransitFeedHandle
9
+
10
+ EXTRA_HINT = (
11
+ "GTFS and GTFS-RT feeds require the 'feeds' extra: "
12
+ "pip install aiomobilitydatabase[feeds]"
13
+ )
14
+
15
+
16
+ def load_transit_handle() -> type[TransitFeedHandle]:
17
+ """Import TransitFeedHandle, naming the missing extra if protobuf is absent."""
18
+ try:
19
+ from .transit import TransitFeedHandle # noqa: PLC0415
20
+ except ImportError as err:
21
+ if (err.name or "").startswith("google"):
22
+ raise ImportError(EXTRA_HINT, name=err.name) from err
23
+ raise
24
+ return TransitFeedHandle
@@ -0,0 +1,28 @@
1
+ """Data-origin URL guard shared by every feed handle."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from urllib.parse import urlsplit
6
+
7
+ from .exceptions import SourceConnectionError
8
+
9
+ _ALLOWED_URL_SCHEMES = frozenset({"http", "https"})
10
+
11
+
12
+ def _require_http_url(url: str, context: str) -> None:
13
+ """Reject a data-origin URL whose scheme isn't http/https before fetch.
14
+
15
+ Producer URLs, hosted dataset URLs, and GBFS endpoint URLs all
16
+ originate from data (catalog payloads, GBFS documents an agency
17
+ controls) rather than from a caller-supplied parameter, so a malicious
18
+ or corrupt source could point at a local resource (``file://``) or
19
+ another unintended scheme. This is a proportionate library-level guard,
20
+ not full SSRF prevention -- producer hosts are legitimately arbitrary,
21
+ so host/IP validation is out of scope; a stricter policy belongs in the
22
+ consuming application (e.g. the HA integration) if needed.
23
+ """
24
+ scheme = urlsplit(url).scheme.lower()
25
+ if scheme not in _ALLOWED_URL_SCHEMES:
26
+ raise SourceConnectionError(
27
+ f"Refusing to fetch {context}: unsupported URL scheme {scheme!r} ({url})"
28
+ )
@@ -7,16 +7,19 @@ import shutil
7
7
  from collections.abc import Callable, Mapping, Sequence
8
8
  from pathlib import Path
9
9
  from types import TracebackType
10
- from typing import Self
10
+ from typing import TYPE_CHECKING, Self
11
11
 
12
12
  import aiohttp
13
13
 
14
14
  from ..client import MobilityDatabaseClient
15
15
  from ..exceptions import MobilityDatabaseError
16
+ from ._extra import load_transit_handle
16
17
  from .const import DEFAULT_TIMEOUT_SECONDS
17
18
  from .gbfs import GbfsFeedHandle
18
19
  from .models import StaticBuildProgress
19
- from .transit import TransitFeedHandle
20
+
21
+ if TYPE_CHECKING:
22
+ from .transit import TransitFeedHandle
20
23
 
21
24
 
22
25
  class MobilityFeedsClient:
@@ -189,7 +192,7 @@ class MobilityFeedsClient:
189
192
  callback's own scheduling, so it cannot abort a build already in
190
193
  progress.
191
194
  """
192
- return await TransitFeedHandle.create(self, feed_id, api_key, on_progress)
195
+ return await load_transit_handle().create(self, feed_id, api_key, on_progress)
193
196
 
194
197
  async def get_transit_feed_from_urls(
195
198
  self,
@@ -220,7 +223,7 @@ class MobilityFeedsClient:
220
223
  :meth:`purge_cache`). ``on_progress`` follows the same contract as
221
224
  :meth:`get_transit_feed`.
222
225
  """
223
- return await TransitFeedHandle.create_from_urls(
226
+ return await load_transit_handle().create_from_urls(
224
227
  self,
225
228
  static_url,
226
229
  trip_updates_urls=trip_updates_urls,