caltrain-api 1.0.1__tar.gz

caltrain_api-1.0.1/.gitignore

@@ -0,0 +1,32 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+
+# Virtual environments (both names, so a stray one can't be committed)
+.venv/
+venv/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Secrets
+.env
+*.key
+*.pem
+
+# Downloaded feed data used by tools/one-off-* exploration scripts
+.explore/
+
+# Editor workspace files
+*.code-workspace
+
+# Personal project notes for Claude Code (not part of the published project)
+CLAUDE.md

caltrain_api-1.0.1/.python-version

@@ -0,0 +1 @@
+3.13

caltrain_api-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Sinnott
+
+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.

caltrain_api-1.0.1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: caltrain-api
+Version: 1.0.1
+Summary: Caltrain schedules and train positions (lat/lon, milepost, and plain-English) from GTFS and 511 real-time data.
+Project-URL: Homepage, https://github.com/jsinnott/caltrain-api
+Project-URL: Repository, https://github.com/jsinnott/caltrain-api
+Project-URL: Issues, https://github.com/jsinnott/caltrain-api/issues
+Project-URL: Changelog, https://github.com/jsinnott/caltrain-api#changelog
+Author-email: Joe Sinnott <joe@jsinnott.net>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 511,bay area,caltrain,gtfs,gtfs-realtime,train,transit
+Classifier: Development Status :: 5 - Production/Stable
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: gtfs-realtime-bindings>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: types-protobuf; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# caltrain-api
+
+Caltrain schedules and train positions -- latitude/longitude, milepost from SF 4th & King, and plain-English descriptions ("approaching Redwood City") -- from Caltrain's static GTFS and 511.org real-time data.
+
+## Install
+
+```bash
+pip install caltrain-api
+```
+
+Python 3.11+. Real-time data needs a free [511.org API key](https://511.org/open-data/token); without one, everything works from the published timetable.
+
+## Usage
+
+```python
+import os
+from datetime import date
+from caltrain_api import CaltrainAPI, Direction
+
+api = CaltrainAPI(api_key=os.environ.get("CALTRAIN_511_API_KEY"))  # None -> schedule only
+
+for train in api.get_active_trains():
+    p = train.position                          # best estimate
+    print(train.number, train.service_type.value, f"mp {p.milepost:.1f}",
+          p.description, train.delay)           # e.g. 124 local mp 30.0 at Palo Alto 0:01:58
+
+train = api.get_train(124)
+train.position             # ESTIMATED: from real-time predicted times
+train.reported_position    # REPORTED: raw feed lat/lon (can be minutes stale)
+train.scheduled_position   # SCHEDULED: where the timetable says it should be
+train.next_stop, train.stops, train.alerts
+
+for d in api.get_departures("Palo Alto", direction=Direction.NORTHBOUND, limit=5):
+    print(d.train.number, d.stop.departure, d.stop.delay)
+
+for j in api.get_schedule("Palo Alto", "San Francisco",
+                          api.schedule.typical_service_date("weekday", date.today())):
+    print(j.train.number, j.origin_stop.scheduled_departure, j.scheduled_duration)
+
+api.get_stations()         # in milepost order, SF first
+api.get_alerts()
+```
+
+Every method that takes `at=` answers for any moment (timezone-aware datetimes); real-time data applies only within 5 minutes of now.
+
+Positions offer three expressions: `lat`/`lon`, `milepost` (miles along the track from SF 4th & King = 0.0, ~76.8 at Gilroy; computed from GTFS geometry, so close to but not identical with Caltrain's official mileposts), and `description` plus a structured `relation` (`AT`, `PASSING`, `APPROACHING`, `DEPARTED`, `BETWEEN`, `WAITING`, `ARRIVED`). Thresholds (0.2 mi "at", 0.5 mi "approaching/departed") are configurable via `DescriptionPolicy`.
+
+### Data handling
+
+- The static GTFS is downloaded on first use, cached in the user cache dir (`~/Library/Caches/caltrain-api` on macOS), and re-checked daily or when the feed expires. `api.refresh_schedule(force=True)` forces it. Offline, the cached copy is used.
+- Real-time data is fetched lazily, at most every 120 s (511 allows 60 requests/hour; positions only change every few minutes). Empty feeds and failures keep the last good data for up to 10 minutes, then fall back to the schedule. Rate limiting backs off automatically.
+- `CaltrainAPI` is thread-safe; share one instance.
+
+See [docs/data-findings.md](https://github.com/jsinnott/caltrain-api/blob/master/docs/data-findings.md) for what the data sources actually provide and how that shaped these choices.
+
+## License
+
+MIT
+
+## Development
+
+From a clone of https://github.com/jsinnott/caltrain-api:
+
+```bash
+uv sync --extra dev
+.venv/bin/pytest tests/unit                                     # offline, pinned fixtures
+CALTRAIN_511_API_KEY=... .venv/bin/pytest -s tests/integration   # live; ~2 511 requests
+.venv/bin/mypy --strict src
+```
+
+Unit tests use a pinned GTFS feed and a captured 511 response (2026-11-13 11:45 PT) in `tests/fixtures/`. `tools/one-off-*.py` are survey/measurement scripts for the live data sources.
+
+## Changelog
+
+- 1.0.1 -- Packaging for PyPI: LICENSE file, project URLs, classifiers, `py.typed` marker (type checkers now use the library's annotations), README links that work on PyPI. No code changes.
+- 1.0.0 -- Stable release: the public API (everything exported from `caltrain_api`) is now covered by semantic versioning. No code changes from 0.2.1.
+- 0.2.1 -- Fix: a train waiting at its origin could be placed miles down the line, because 511 reports its equipment (often finishing a previous run) before departure. Reports no longer constrain estimates before departure, and WAITING/ARRIVED apply only near the origin/destination.
+- 0.2.0 -- `CaltrainAPI.get_schedule(origin, destination, service_date)` returning `Journey` objects (point-to-point timetable); `Schedule.typical_service_date("weekday"|"weekend", on_or_after)` picks an ordinary non-holiday date.
+- 0.1.0 -- First working release. `Schedule.load`/`refresh` (download, disk cache, conditional revalidation, offline fallback); `SiriRealtimeSource` (511 SIRI VehicleMonitoring + ServiceAlerts); `CaltrainAPI` facade with lazy polling, empty-feed/failure tolerance, rate-limit backoff, estimated/reported/scheduled positions, delays, alerts, `get_departures`.
+- 0.0.1 -- Offline timetable: `Corridor`, `DescriptionPolicy`, `Schedule.from_zip`. `Train.trip_id` added; holiday "M"-prefixed trains parsed to plain numbers.
+- 0.0.0 -- API stubs for review.

caltrain_api-1.0.1/README.md

@@ -0,0 +1,81 @@
+# caltrain-api
+
+Caltrain schedules and train positions -- latitude/longitude, milepost from SF 4th & King, and plain-English descriptions ("approaching Redwood City") -- from Caltrain's static GTFS and 511.org real-time data.
+
+## Install
+
+```bash
+pip install caltrain-api
+```
+
+Python 3.11+. Real-time data needs a free [511.org API key](https://511.org/open-data/token); without one, everything works from the published timetable.
+
+## Usage
+
+```python
+import os
+from datetime import date
+from caltrain_api import CaltrainAPI, Direction
+
+api = CaltrainAPI(api_key=os.environ.get("CALTRAIN_511_API_KEY"))  # None -> schedule only
+
+for train in api.get_active_trains():
+    p = train.position                          # best estimate
+    print(train.number, train.service_type.value, f"mp {p.milepost:.1f}",
+          p.description, train.delay)           # e.g. 124 local mp 30.0 at Palo Alto 0:01:58
+
+train = api.get_train(124)
+train.position             # ESTIMATED: from real-time predicted times
+train.reported_position    # REPORTED: raw feed lat/lon (can be minutes stale)
+train.scheduled_position   # SCHEDULED: where the timetable says it should be
+train.next_stop, train.stops, train.alerts
+
+for d in api.get_departures("Palo Alto", direction=Direction.NORTHBOUND, limit=5):
+    print(d.train.number, d.stop.departure, d.stop.delay)
+
+for j in api.get_schedule("Palo Alto", "San Francisco",
+                          api.schedule.typical_service_date("weekday", date.today())):
+    print(j.train.number, j.origin_stop.scheduled_departure, j.scheduled_duration)
+
+api.get_stations()         # in milepost order, SF first
+api.get_alerts()
+```
+
+Every method that takes `at=` answers for any moment (timezone-aware datetimes); real-time data applies only within 5 minutes of now.
+
+Positions offer three expressions: `lat`/`lon`, `milepost` (miles along the track from SF 4th & King = 0.0, ~76.8 at Gilroy; computed from GTFS geometry, so close to but not identical with Caltrain's official mileposts), and `description` plus a structured `relation` (`AT`, `PASSING`, `APPROACHING`, `DEPARTED`, `BETWEEN`, `WAITING`, `ARRIVED`). Thresholds (0.2 mi "at", 0.5 mi "approaching/departed") are configurable via `DescriptionPolicy`.
+
+### Data handling
+
+- The static GTFS is downloaded on first use, cached in the user cache dir (`~/Library/Caches/caltrain-api` on macOS), and re-checked daily or when the feed expires. `api.refresh_schedule(force=True)` forces it. Offline, the cached copy is used.
+- Real-time data is fetched lazily, at most every 120 s (511 allows 60 requests/hour; positions only change every few minutes). Empty feeds and failures keep the last good data for up to 10 minutes, then fall back to the schedule. Rate limiting backs off automatically.
+- `CaltrainAPI` is thread-safe; share one instance.
+
+See [docs/data-findings.md](https://github.com/jsinnott/caltrain-api/blob/master/docs/data-findings.md) for what the data sources actually provide and how that shaped these choices.
+
+## License
+
+MIT
+
+## Development
+
+From a clone of https://github.com/jsinnott/caltrain-api:
+
+```bash
+uv sync --extra dev
+.venv/bin/pytest tests/unit                                     # offline, pinned fixtures
+CALTRAIN_511_API_KEY=... .venv/bin/pytest -s tests/integration   # live; ~2 511 requests
+.venv/bin/mypy --strict src
+```
+
+Unit tests use a pinned GTFS feed and a captured 511 response (2026-11-13 11:45 PT) in `tests/fixtures/`. `tools/one-off-*.py` are survey/measurement scripts for the live data sources.
+
+## Changelog
+
+- 1.0.1 -- Packaging for PyPI: LICENSE file, project URLs, classifiers, `py.typed` marker (type checkers now use the library's annotations), README links that work on PyPI. No code changes.
+- 1.0.0 -- Stable release: the public API (everything exported from `caltrain_api`) is now covered by semantic versioning. No code changes from 0.2.1.
+- 0.2.1 -- Fix: a train waiting at its origin could be placed miles down the line, because 511 reports its equipment (often finishing a previous run) before departure. Reports no longer constrain estimates before departure, and WAITING/ARRIVED apply only near the origin/destination.
+- 0.2.0 -- `CaltrainAPI.get_schedule(origin, destination, service_date)` returning `Journey` objects (point-to-point timetable); `Schedule.typical_service_date("weekday"|"weekend", on_or_after)` picks an ordinary non-holiday date.
+- 0.1.0 -- First working release. `Schedule.load`/`refresh` (download, disk cache, conditional revalidation, offline fallback); `SiriRealtimeSource` (511 SIRI VehicleMonitoring + ServiceAlerts); `CaltrainAPI` facade with lazy polling, empty-feed/failure tolerance, rate-limit backoff, estimated/reported/scheduled positions, delays, alerts, `get_departures`.
+- 0.0.1 -- Offline timetable: `Corridor`, `DescriptionPolicy`, `Schedule.from_zip`. `Train.trip_id` added; holiday "M"-prefixed trains parsed to plain numbers.
+- 0.0.0 -- API stubs for review.

caltrain_api-1.0.1/docs/data-findings.md

@@ -0,0 +1,95 @@
+# Data source findings
+
+Survey of Caltrain's static GTFS and 511's real-time feeds, taken 2026-11-13
+(a Friday, ~11:45 PT) with `tools/one-off-explore-static-gtfs.py` and
+`tools/one-off-explore-realtime.py`. Re-run those scripts to re-check; feed
+behavior can change without notice.
+
+## Static GTFS
+
+- Source: `https://data.trilliumtransit.com/gtfs/caltrain-ca-us/caltrain-ca-us.zip`
+  (linked from caltrain.com/developer-resources). ~170 KB, no key. Feed is
+  republished frequently; `feed_info.txt` carries `feed_start_date` /
+  `feed_end_date` (this one: 2026-11-13 .. 2027-01-31).
+- **Stations**: 31 parent stations (`location_type=1`), each with NB and SB
+  platform children (`70011`/`70012` etc.; Stanford's are `2537740`/`2537744`),
+  plus elevator entrances (`location_type=2`). `stop_times` references
+  platforms only. Stanford exists but no trip stops there.
+- **Trains**: `trip_id == trip_short_name` for all trips. On regular service
+  that is the plain train number ("123"); the holiday-only ("modified")
+  service's 75 trips are prefixed: "M101".."M176". The library parses the
+  digits as `Train.number` and keeps the raw id as `Train.trip_id`. (The
+  survey script's parity check silently skipped the M trips -- 182 of 257.)
+  `direction_id` 0 = North (odd numbers), 1 = South (even numbers), confirmed
+  by `directions.txt`.
+- **Mileposts** (computed, SF = 0.0): San Jose Diridon 46.84 (official 46.9),
+  Gilroy 76.77 (official 77.4).
+- **Service type**: `routes.txt` short names are "Local Weekday", "Local
+  Weekend", "Limited", "Express", "South County". `realtime_routes.txt`
+  collapses them to clean names (Local / Limited / Express / South County).
+- **Skip-stop**: express/limited trips simply omit stations they don't serve
+  (7-24 stops per trip); `pickup_type`/`drop_off_type` are always 0. Knowing
+  what a train *passes* requires station mileposts independent of the trip.
+- **Shapes**: 17 directional, per-pattern shapes. Corridor is covered in two
+  pieces: SF <-> San Jose Diridon/Tamien (~46.9 / 48.7 mi) and Diridon <->
+  Gilroy (~30.0 mi). `shape_dist_traveled` is present on every point and every
+  stop_time, **in meters**. A single SF->Gilroy milepost axis must be stitched
+  from these.
+- **Calendar**: weekday and weekend services in `calendar.txt`; a third,
+  holiday-only service (`c_71743...`, Local + South County, 79 trips) appears
+  only in `calendar_dates.txt`, which also has `holiday_name`. Times run past
+  midnight (max `25:29:00`, 161 rows >= 24:00).
+- **Data-quality note**: `calendar_dates.txt` labels 2027-01-27 (a Wednesday)
+  as Martin Luther King Jr. Day; MLK Day 2027 is Monday 2027-01-18. The library
+  should follow the feed, but this is a reminder the feed can be wrong.
+- `linked_datasets.txt` points at a **keyless** Trillium service-alerts
+  GTFS-RT feed.
+
+## 511 real-time (agency=CT)
+
+- **Rate limit**: 60/hour per key, reported in `ratelimit-limit` /
+  `ratelimit-remaining` headers. `remaining` was non-monotonic across calls
+  (59,58,57,56,55,58,54,58), suggesting several backend counters -- don't rely
+  on it for precise budgeting.
+- **VehiclePositions** (GTFS-RT): real lat/lon (not station-snapped -- 44 of
+  69 observations were mid-segment), but only `trip`, `vehicle`, `position.
+  {lat,lon}`, `timestamp` are populated -- no bearing, speed, stop status.
+  **Positions refresh only every ~3-4 minutes** (11:45 -> 11:48 -> 11:52) while
+  the per-vehicle `timestamp` advances every minute, so the timestamp is not
+  the fix time. At line speed a fix can be several miles stale.
+- **Feed dropouts**: 2 of 10 VehiclePositions samples came back empty (15
+  bytes, 0 entities) mid-service. Empty must mean "no data", not "no trains".
+- Trains staged at their origin before departure (SF, Tamien, Diridon) appear
+  in the feed.
+- **TripUpdates**: absolute predicted `arrival.time`/`departure.time` per
+  remaining stop; `delay` fields are all 0 and `stop_sequence` is 0 -- delay
+  must be computed against the static schedule. Example: train 123 predicted
+  at Mountain View 11:44:45 vs scheduled 10:46 (~59 min late) while showing
+  `delay=0`. Cancellation (per alerts) was *not* reflected in
+  `schedule_relationship` (all SCHEDULED).
+- **ServiceAlerts**: useful structured `informed_entity` (trip ids, stop ids)
+  and effects (SIGNIFICANT_DELAYS, MODIFIED_SERVICE), plus free text.
+  Sometimes contradictory (train 123 both "Cancelled" and "38 minutes late").
+- **SIRI VehicleMonitoring** (`format=json`): one call returns, per train,
+  the same position as VehiclePositions *plus* Aimed (scheduled) and Expected
+  times for the monitored call and all onward calls. One request ~= VP + TU.
+  Times are UTC ISO-8601; JSON has a UTF-8 BOM.
+  `FramedVehicleJourneyRef.DataFrameRef` is the trip's service date, so a
+  late train is matched to the right day's run exactly. `StopPointRef` is the
+  GTFS platform stop_id.
+- **Report lag** (measured 2026-11-13 12:50-12:58 with
+  `tools/one-off-measure-report-lag.py`, 31 observations): reported positions
+  normally trail the predicted timeline by ~1 minute (median +0.9 min).
+  But at 12:50 *every* train's report lagged ~15 minutes at once -- 511
+  briefly served a frozen batch of positions -- and two minutes later all
+  were fresh again and agreed with the predictions. Conclusion: predicted
+  times are the more reliable source; reports are used only to stop an
+  estimate falling behind them (a train held longer than predicted).
+- **Pre-departure reports are the equipment, not the trip**: a train waiting
+  to start (e.g. 140 at SF) can be reported miles away -- its trainset still
+  finishing the previous run (seen 2026-11-13 ~13:50, 140 reported at mp 10).
+  The library ignores reports for reconciliation until departure.
+- **Trillium's keyless alerts feed** (from `linked_datasets.txt`) returned
+  HTTP 500 on 2026-11-13; the library uses 511's ServiceAlerts instead.
+- Real-time trip ids match static trip ids. Real-time `route_id` is the route
+  *short name* ("Local Weekday"), not the static numeric `route_id`.

caltrain_api-1.0.1/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "caltrain-api"
+version = "1.0.1"
+description = "Caltrain schedules and train positions (lat/lon, milepost, and plain-English) from GTFS and 511 real-time data."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Joe Sinnott", email = "joe@jsinnott.net" }]
+keywords = ["caltrain", "gtfs", "gtfs-realtime", "511", "transit", "train", "bay area"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.6",
+    "gtfs-realtime-bindings>=1.0",
+    "platformdirs>=4",
+]
+
+[project.urls]
+Homepage = "https://github.com/jsinnott/caltrain-api"
+Repository = "https://github.com/jsinnott/caltrain-api"
+Issues = "https://github.com/jsinnott/caltrain-api/issues"
+Changelog = "https://github.com/jsinnott/caltrain-api#changelog"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "mypy>=1.10",
+    "types-protobuf",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/caltrain_api"]

caltrain_api-1.0.1/src/caltrain_api/__init__.py

@@ -0,0 +1,68 @@
+"""Caltrain schedules and train positions.
+
+Public API -- everything importable from ``caltrain_api`` directly is covered
+by semantic versioning; submodule internals are not.
+"""
+
+__version__ = "1.0.1"
+
+from .api import CaltrainAPI
+from .corridor import Corridor
+from .describe import DescriptionPolicy
+from .errors import (
+    CaltrainError,
+    OffCorridorError,
+    RateLimitedError,
+    RealtimeUnavailableError,
+    ScheduleUnavailableError,
+    UnknownStationError,
+    UnknownTrainError,
+)
+from .models import (
+    Alert,
+    Departure,
+    Journey,
+    Direction,
+    PositionSource,
+    Relation,
+    ServiceType,
+    Station,
+    Stop,
+    TrackLocation,
+    Train,
+    TrainPosition,
+    TrainStatus,
+)
+from .realtime import RealtimeSnapshot, RealtimeSource, SiriRealtimeSource, TrainObservation
+from .schedule import Schedule
+
+__all__ = [
+    "Alert",
+    "CaltrainAPI",
+    "CaltrainError",
+    "Corridor",
+    "Departure",
+    "Journey",
+    "DescriptionPolicy",
+    "Direction",
+    "OffCorridorError",
+    "PositionSource",
+    "RateLimitedError",
+    "RealtimeSnapshot",
+    "RealtimeSource",
+    "RealtimeUnavailableError",
+    "Relation",
+    "Schedule",
+    "ScheduleUnavailableError",
+    "ServiceType",
+    "SiriRealtimeSource",
+    "Station",
+    "Stop",
+    "TrackLocation",
+    "Train",
+    "TrainObservation",
+    "TrainPosition",
+    "TrainStatus",
+    "UnknownStationError",
+    "UnknownTrainError",
+]

caltrain_api-1.0.1/src/caltrain_api/_feedcache.py

@@ -0,0 +1,164 @@
+"""On-disk cache for the static GTFS zip (internal).
+
+Layout under the cache dir:
+    caltrain-gtfs.zip    the feed, replaced atomically
+    caltrain-gtfs.json   metadata: url, downloaded_at, checked_at, etag, last_modified
+
+Downloads are conditional (If-None-Match / If-Modified-Since), and a new zip
+replaces the cached one only after it parses successfully, so a bad download
+never clobbers a good cache.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import TypeVar
+
+import httpx
+
+from . import __version__
+from .errors import ScheduleUnavailableError
+
+log = logging.getLogger(__name__)
+
+ZIP_NAME = "caltrain-gtfs.zip"
+META_NAME = "caltrain-gtfs.json"
+USER_AGENT = f"caltrain-api/{__version__}"
+
+T = TypeVar("T")
+
+
+@dataclass
+class FeedMeta:
+    url: str
+    downloaded_at: datetime
+    checked_at: datetime
+    etag: str | None = None
+    last_modified: str | None = None
+
+    def to_json(self) -> str:
+        return json.dumps({
+            "url": self.url,
+            "downloaded_at": self.downloaded_at.isoformat(),
+            "checked_at": self.checked_at.isoformat(),
+            "etag": self.etag,
+            "last_modified": self.last_modified,
+        }, indent=2)
+
+    @classmethod
+    def from_json(cls, text: str) -> FeedMeta:
+        d = json.loads(text)
+        return cls(url=d["url"], downloaded_at=datetime.fromisoformat(d["downloaded_at"]),
+                   checked_at=datetime.fromisoformat(d["checked_at"]),
+                   etag=d.get("etag"), last_modified=d.get("last_modified"))
+
+
+class FeedCache:
+    def __init__(
+        self,
+        cache_dir: Path,
+        url: str,
+        max_age: timedelta,
+        http_client: httpx.Client | None,
+        clock: Callable[[], datetime],
+    ):
+        self.cache_dir = cache_dir
+        self.url = url
+        self.max_age = max_age
+        self.http_client = http_client
+        self.clock = clock
+
+    @property
+    def zip_path(self) -> Path:
+        return self.cache_dir / ZIP_NAME
+
+    @property
+    def meta_path(self) -> Path:
+        return self.cache_dir / META_NAME
+
+    def read_meta(self) -> FeedMeta | None:
+        try:
+            return FeedMeta.from_json(self.meta_path.read_text())
+        except (OSError, ValueError, KeyError) as exc:
+            if self.meta_path.exists():
+                log.warning("Ignoring unreadable GTFS cache metadata %s: %s", self.meta_path, exc)
+            return None
+
+    def is_stale(self, valid_until: date | None) -> bool:
+        """True if the cache should be re-checked against the server."""
+        meta = self.read_meta()
+        now = self.clock()
+        if meta is None or not self.zip_path.exists():
+            return True
+        if meta.url != self.url:
+            log.info("GTFS URL changed; cache is stale")
+            return True
+        if now - meta.checked_at > self.max_age:
+            return True
+        return valid_until is not None and now.date() > valid_until
+
+    def _write_atomic(self, path: Path, data: bytes) -> None:
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=self.cache_dir, prefix=path.name, suffix=".tmp")
+        try:
+            with os.fdopen(fd, "wb") as f:
+                f.write(data)
+            os.replace(tmp, path)
+        except BaseException:
+            Path(tmp).unlink(missing_ok=True)
+            raise
+
+    def download(self, parse: Callable[[bytes], T], *, conditional: bool) -> T | None:
+        """Fetch the feed. Returns ``parse(data)`` for new content, or None if
+        the server says the cached copy is current (HTTP 304).
+
+        The data is parsed *before* it replaces the cache.
+
+        Raises:
+            ScheduleUnavailableError: network/HTTP failure or unparseable feed.
+        """
+        meta = self.read_meta()
+        headers = {"User-Agent": USER_AGENT}
+        if conditional and meta is not None and self.zip_path.exists() and meta.url == self.url:
+            if meta.etag:
+                headers["If-None-Match"] = meta.etag
+            if meta.last_modified:
+                headers["If-Modified-Since"] = meta.last_modified
+
+        log.info("Downloading GTFS from %s", self.url)
+        client = self.http_client or httpx.Client(timeout=60, follow_redirects=True)
+        try:
+            resp = client.get(self.url, headers=headers)
+        except httpx.HTTPError as exc:
+            raise ScheduleUnavailableError(f"GTFS download failed: {type(exc).__name__}: {exc}") from exc
+        finally:
+            if self.http_client is None:
+                client.close()
+
+        now = self.clock()
+        if resp.status_code == 304 and meta is not None:
+            log.info("GTFS unchanged on server (304)")
+            meta.checked_at = now
+            self._write_atomic(self.meta_path, meta.to_json().encode())
+            return None
+        if resp.status_code != 200:
+            raise ScheduleUnavailableError(f"GTFS download failed: HTTP {resp.status_code}")
+
+        try:
+            parsed = parse(resp.content)
+        except Exception as exc:
+            raise ScheduleUnavailableError(f"downloaded GTFS is unusable: {exc}") from exc
+
+        self._write_atomic(self.zip_path, resp.content)
+        new_meta = FeedMeta(url=self.url, downloaded_at=now, checked_at=now,
+                            etag=resp.headers.get("ETag"), last_modified=resp.headers.get("Last-Modified"))
+        self._write_atomic(self.meta_path, new_meta.to_json().encode())
+        log.info("Cached GTFS (%d bytes) at %s", len(resp.content), self.zip_path)
+        return parsed