gtfs-hub 0.1.0__tar.gz

gtfs_hub-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+.DS_Store

gtfs_hub-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes are listed here. Versions follow [Semantic Versioning](https://semver.org/); below 1.0, a breaking change to the API, the provider contract or the database schema bumps the minor version.
+
+## 0.1.0 - 2026-11-11
+
+First public release.
+
+- Local SQLite copy of a GTFS schedule, sized by the selected lines, with snapshots, coverage checks and safe rebuilds.
+- Departures joined with GTFS Realtime trip updates, including night service past 24:00, cancellations and skipped stops.
+- Vehicle positions of selected lines, and service alerts.
+- Route shapes of selected lines, and locating a position on a shape.
+- `GenericProvider` for plain URLs, and the `gtfs_hub.providers` entry point group for provider packages.
+- Typed errors deriving from `GtfsError`.

gtfs_hub-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 grozycki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gtfs_hub-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: gtfs-hub
+Version: 0.1.0
+Summary: Provider-agnostic GTFS schedule library for low-memory hardware
+Project-URL: Homepage, https://github.com/grozycki/gtfs-hub
+Project-URL: Issues, https://github.com/grozycki/gtfs-hub/issues
+Project-URL: Changelog, https://github.com/grozycki/gtfs-hub/blob/main/CHANGELOG.md
+Author: grozycki
+License-Expression: MIT
+License-File: LICENSE
+Keywords: gtfs,gtfs-realtime,public-transport,timetable,transit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aiohttp>=3.10
+Requires-Dist: gtfs-realtime-bindings>=1.0
+Description-Content-Type: text/markdown
+
+# gtfs-hub
+
+Provider-agnostic GTFS schedule library for low-memory hardware. It keeps a local SQLite copy of a schedule, sized by the lines you select rather than by the size of the feed.
+
+Requires Python 3.13 or newer.
+
+## Installation
+
+```bash
+pip install gtfs-hub
+```
+
+Versions follow [Semantic Versioning](https://semver.org/); below 1.0, a breaking change to the API, the provider contract or the database schema bumps the minor version. See the [changelog](CHANGELOG.md).
+
+## Usage
+
+Any standard source works from plain URLs, through `GenericProvider`. Pass your own `aiohttp` session: the library never creates one.
+
+```python
+from pathlib import Path
+
+from aiohttp import ClientSession
+
+from gtfs_hub import GenericProvider, GtfsHub, LineKey
+
+
+async def main(url: str, database: Path) -> None:
+    async with ClientSession() as session:
+        hub = GtfsHub(GenericProvider([url]), database, session)
+
+        # The first sync with no lines fills the searchable catalogue.
+        await hub.async_sync([])
+        lines = await hub.async_search_lines("11")
+
+        # Timetables are stored only for selected lines.
+        selection = [line.key for line in lines]
+        await hub.async_sync(selection)
+
+        for key in selection:
+            stops = await hub.async_stops_of_line(key)
+            print(LineKey(key.route_type, key.short_name), [stop.name for stop in stops])
+```
+
+Call `async_sync` with the full selection whenever the source may have changed or the selection did. Lines that are new are imported, lines that are gone are removed, and unchanged files are not downloaded. On failure it raises a `GtfsError`, and the previous database stays in use. The database is a cache, so it is safe to delete: the next sync rebuilds it.
+
+## Departures
+
+Fetch realtime once per poll, and pass it to each departures call. A failed fetch only means passing `None`: the schedule still answers.
+
+```python
+from gtfs_hub import GtfsError, GtfsHub
+
+
+async def show_departures(hub: GtfsHub, stop_key: str) -> None:
+    try:
+        realtime = await hub.async_fetch_realtime()
+    except GtfsError:
+        realtime = None
+    for departure in await hub.async_departures(stop_key, realtime=realtime, limit=5):
+        print(departure.line.short_name, departure.headsign, departure.expected, departure.status)
+```
+
+Departures cover the lines stored by the last sync, on every service date reaching the period, including night service past 24:00. Times are in UTC. `scheduled` is always set, while `predicted` and `delay` stay `None` without a usable update, so "no data" never reads as "on time". Stops a running trip has passed give no departure, and points where riders cannot board give none either. Realtime older than `max_age` (5 minutes by default) is ignored, and `RealtimeData.is_stale` tells a consumer so. When no snapshot covers today, `async_departures` raises `GtfsNoDataError`.
+
+Trips in `frequencies.txt` are not supported and are left out, with a log line.
+
+## Shapes
+
+When a source publishes `shapes.txt`, the paths of selected lines are stored with their timetables. `async_line_shapes(key, service_date=None)` returns each distinct path of a line, with its points in order, its direction and the most common headsign of its trips. With a service date, only the snapshot serving that date counts, so other days' variants stay out. A broken `shapes.txt` costs only the paths, never the timetables. Vehicles carry the `shape` of their trip.
+
+`locate(shape, latitude, longitude, after=None)` places a position on a path: metres along it, metres off it, and the bearing of the path there. A position more than 60 m off has no location. Pass the previous `along` of the same trip as `after`, so a path that runs one street both ways resolves to the pass ahead; without it, such a position has no location rather than a guess.
+
+## Generic provider
+
+| Argument | Meaning |
+|---|---|
+| `schedule_urls` | One or more ZIP files, each treated as one snapshot |
+| `trip_updates_url`, `vehicle_positions_url`, `alerts_url` | Optional realtime endpoints |
+| `headers` | Optional headers for realtime requests |
+| `stop_key` | `stop_id` by default, or `stop_code` when that is the stable field |
+| `name`, `attribution` | Display name, and the licence text consumers must show |
+
+It reports no capabilities and no vehicle identity until a source has been surveyed.
+
+## Keys
+
+- **Lines** are `LineKey(route_type, short_name)`. Store this, never a `route_id`.
+- **Stops** are the value of the provider's `stop_key` field. One key can resolve to several `stop_id` values.
+- `Line.url` and `Stop.url` carry `route_url` and `stop_url` when the source fills them.
+- Empty results from `async_resolve_line` and `async_resolve_stop` mean the key is in no current snapshot.
+
+## Coverage
+
+`async_snapshot_for(date)` picks the newest snapshot for a service date. `async_missing_dates(start, end)` reports dates no snapshot covers, which differ from dates without service.
+
+## Errors
+
+| Error | Meaning |
+|---|---|
+| `GtfsConnectionError` | Temporary failure: retry later |
+| `GtfsRateLimitError` | Slow down, with `retry_after` in seconds when known |
+| `GtfsAuthError` | The source rejected the credentials |
+| `GtfsFeedError` | Bad or unusable data |
+| `GtfsNoDataError` | No usable database yet: run a sync |
+
+All derive from `GtfsError`.
+
+## Writing a provider
+
+A package is needed only when finding or reading the data takes code. Subclass `BaseProvider`, implement `async_list_static_feeds`, and register a factory in the `gtfs_hub.providers` entry point group, with the provider key as its name.
+
+## Development
+
+```bash
+uv sync
+```
+
+```bash
+uv run pytest
+```

gtfs_hub-0.1.0/README.md

@@ -0,0 +1,120 @@
+# gtfs-hub
+
+Provider-agnostic GTFS schedule library for low-memory hardware. It keeps a local SQLite copy of a schedule, sized by the lines you select rather than by the size of the feed.
+
+Requires Python 3.13 or newer.
+
+## Installation
+
+```bash
+pip install gtfs-hub
+```
+
+Versions follow [Semantic Versioning](https://semver.org/); below 1.0, a breaking change to the API, the provider contract or the database schema bumps the minor version. See the [changelog](CHANGELOG.md).
+
+## Usage
+
+Any standard source works from plain URLs, through `GenericProvider`. Pass your own `aiohttp` session: the library never creates one.
+
+```python
+from pathlib import Path
+
+from aiohttp import ClientSession
+
+from gtfs_hub import GenericProvider, GtfsHub, LineKey
+
+
+async def main(url: str, database: Path) -> None:
+    async with ClientSession() as session:
+        hub = GtfsHub(GenericProvider([url]), database, session)
+
+        # The first sync with no lines fills the searchable catalogue.
+        await hub.async_sync([])
+        lines = await hub.async_search_lines("11")
+
+        # Timetables are stored only for selected lines.
+        selection = [line.key for line in lines]
+        await hub.async_sync(selection)
+
+        for key in selection:
+            stops = await hub.async_stops_of_line(key)
+            print(LineKey(key.route_type, key.short_name), [stop.name for stop in stops])
+```
+
+Call `async_sync` with the full selection whenever the source may have changed or the selection did. Lines that are new are imported, lines that are gone are removed, and unchanged files are not downloaded. On failure it raises a `GtfsError`, and the previous database stays in use. The database is a cache, so it is safe to delete: the next sync rebuilds it.
+
+## Departures
+
+Fetch realtime once per poll, and pass it to each departures call. A failed fetch only means passing `None`: the schedule still answers.
+
+```python
+from gtfs_hub import GtfsError, GtfsHub
+
+
+async def show_departures(hub: GtfsHub, stop_key: str) -> None:
+    try:
+        realtime = await hub.async_fetch_realtime()
+    except GtfsError:
+        realtime = None
+    for departure in await hub.async_departures(stop_key, realtime=realtime, limit=5):
+        print(departure.line.short_name, departure.headsign, departure.expected, departure.status)
+```
+
+Departures cover the lines stored by the last sync, on every service date reaching the period, including night service past 24:00. Times are in UTC. `scheduled` is always set, while `predicted` and `delay` stay `None` without a usable update, so "no data" never reads as "on time". Stops a running trip has passed give no departure, and points where riders cannot board give none either. Realtime older than `max_age` (5 minutes by default) is ignored, and `RealtimeData.is_stale` tells a consumer so. When no snapshot covers today, `async_departures` raises `GtfsNoDataError`.
+
+Trips in `frequencies.txt` are not supported and are left out, with a log line.
+
+## Shapes
+
+When a source publishes `shapes.txt`, the paths of selected lines are stored with their timetables. `async_line_shapes(key, service_date=None)` returns each distinct path of a line, with its points in order, its direction and the most common headsign of its trips. With a service date, only the snapshot serving that date counts, so other days' variants stay out. A broken `shapes.txt` costs only the paths, never the timetables. Vehicles carry the `shape` of their trip.
+
+`locate(shape, latitude, longitude, after=None)` places a position on a path: metres along it, metres off it, and the bearing of the path there. A position more than 60 m off has no location. Pass the previous `along` of the same trip as `after`, so a path that runs one street both ways resolves to the pass ahead; without it, such a position has no location rather than a guess.
+
+## Generic provider
+
+| Argument | Meaning |
+|---|---|
+| `schedule_urls` | One or more ZIP files, each treated as one snapshot |
+| `trip_updates_url`, `vehicle_positions_url`, `alerts_url` | Optional realtime endpoints |
+| `headers` | Optional headers for realtime requests |
+| `stop_key` | `stop_id` by default, or `stop_code` when that is the stable field |
+| `name`, `attribution` | Display name, and the licence text consumers must show |
+
+It reports no capabilities and no vehicle identity until a source has been surveyed.
+
+## Keys
+
+- **Lines** are `LineKey(route_type, short_name)`. Store this, never a `route_id`.
+- **Stops** are the value of the provider's `stop_key` field. One key can resolve to several `stop_id` values.
+- `Line.url` and `Stop.url` carry `route_url` and `stop_url` when the source fills them.
+- Empty results from `async_resolve_line` and `async_resolve_stop` mean the key is in no current snapshot.
+
+## Coverage
+
+`async_snapshot_for(date)` picks the newest snapshot for a service date. `async_missing_dates(start, end)` reports dates no snapshot covers, which differ from dates without service.
+
+## Errors
+
+| Error | Meaning |
+|---|---|
+| `GtfsConnectionError` | Temporary failure: retry later |
+| `GtfsRateLimitError` | Slow down, with `retry_after` in seconds when known |
+| `GtfsAuthError` | The source rejected the credentials |
+| `GtfsFeedError` | Bad or unusable data |
+| `GtfsNoDataError` | No usable database yet: run a sync |
+
+All derive from `GtfsError`.
+
+## Writing a provider
+
+A package is needed only when finding or reading the data takes code. Subclass `BaseProvider`, implement `async_list_static_feeds`, and register a factory in the `gtfs_hub.providers` entry point group, with the provider key as its name.
+
+## Development
+
+```bash
+uv sync
+```
+
+```bash
+uv run pytest
+```

gtfs_hub-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gtfs-hub"
+version = "0.1.0"
+description = "Provider-agnostic GTFS schedule library for low-memory hardware"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.13"
+authors = [{ name = "grozycki" }]
+keywords = ["gtfs", "gtfs-realtime", "public-transport", "transit", "timetable"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = ["aiohttp>=3.10", "gtfs-realtime-bindings>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/grozycki/gtfs-hub"
+Issues = "https://github.com/grozycki/gtfs-hub/issues"
+Changelog = "https://github.com/grozycki/gtfs-hub/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.13",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.8",
+    "types-protobuf>=5.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gtfs_hub"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "scripts", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "ANN", "TC", "PYI"]
+
+[tool.mypy]
+strict = true
+files = ["src", "scripts", "tests"]
+warn_unreachable = true
+disallow_any_explicit = true
+disallow_any_unimported = true
+enable_error_code = [
+    "deprecated",
+    "explicit-override",
+    "ignore-without-code",
+    "possibly-undefined",
+    "redundant-expr",
+    "redundant-self",
+    "truthy-bool",
+    "unused-awaitable",
+]

gtfs_hub-0.1.0/scripts/check_agnostic.py

@@ -0,0 +1,28 @@
+"""Fail when the core package mentions a specific agency."""
+
+import sys
+from pathlib import Path
+
+FORBIDDEN = ("gzm", "ztm", "metropolia", "transportgzm", "otwartedane")
+
+
+def find_violations(root: Path) -> list[str]:
+    """Return one line per forbidden term found under root."""
+    violations = []
+    for path in sorted(root.rglob("*.py")):
+        text = path.read_text(encoding="utf-8")
+        for number, line in enumerate(text.splitlines(), start=1):
+            lowered = line.lower()
+            violations += [f"{path}:{number}: {term}" for term in FORBIDDEN if term in lowered]
+    return violations
+
+
+def main() -> int:
+    root = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("src/gtfs_hub")
+    violations = find_violations(root)
+    print("\n".join(violations) or f"{root}: no agency names")
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gtfs_hub-0.1.0/src/gtfs_hub/__init__.py

@@ -0,0 +1,91 @@
+"""Provider-agnostic GTFS schedule library."""
+
+from .discovery import (
+    async_create_provider,
+    async_list_provider_keys,
+    create_provider,
+    list_provider_keys,
+)
+from .download import raise_for_status
+from .errors import (
+    GtfsAuthError,
+    GtfsConnectionError,
+    GtfsError,
+    GtfsFeedError,
+    GtfsNoDataError,
+    GtfsRateLimitError,
+)
+from .generic import GenericProvider
+from .hub import GtfsHub
+from .models import (
+    Capabilities,
+    Departure,
+    DepartureStatus,
+    Line,
+    LineKey,
+    Livery,
+    RealtimeEndpoints,
+    ResolvedId,
+    Shape,
+    ShapeId,
+    ShapeLocation,
+    Snapshot,
+    StaticFeedRef,
+    Stop,
+    StopChoice,
+    StopKey,
+    StopKeyField,
+    SyncResult,
+    TripDelay,
+    TripId,
+    Vehicle,
+    VehicleClass,
+    VehicleKey,
+)
+from .provider import BaseProvider, Provider, TableReader
+from .realtime import RealtimeData
+from .shapes import locate
+
+__all__ = [
+    "BaseProvider",
+    "Capabilities",
+    "Departure",
+    "DepartureStatus",
+    "GenericProvider",
+    "GtfsAuthError",
+    "GtfsConnectionError",
+    "GtfsError",
+    "GtfsFeedError",
+    "GtfsHub",
+    "GtfsNoDataError",
+    "GtfsRateLimitError",
+    "Line",
+    "LineKey",
+    "Livery",
+    "Provider",
+    "RealtimeData",
+    "RealtimeEndpoints",
+    "ResolvedId",
+    "Shape",
+    "ShapeId",
+    "ShapeLocation",
+    "Snapshot",
+    "StaticFeedRef",
+    "Stop",
+    "StopChoice",
+    "StopKey",
+    "StopKeyField",
+    "SyncResult",
+    "TableReader",
+    "TripDelay",
+    "TripId",
+    "Vehicle",
+    "VehicleClass",
+    "VehicleKey",
+    "async_create_provider",
+    "async_list_provider_keys",
+    "create_provider",
+    "list_provider_keys",
+    "locate",
+    "raise_for_status",
+]