caltrain-api 1.0.1__tar.gz → 1.1.0__tar.gz

caltrain_api-1.1.0/.github/workflows/publish.yml

@@ -0,0 +1,73 @@
+# Publish caltrain-api to PyPI when a version tag (vX.Y.Z) is pushed.
+#
+# Uses PyPI Trusted Publishing (OIDC): PyPI is configured to trust this
+# repository + workflow + environment, so no API token is stored anywhere.
+# PyPI side: https://pypi.org/manage/project/caltrain-api/settings/publishing/
+#   owner: jsinnott, repository: caltrain-api, workflow: publish.yml, environment: pypi
+#
+# Release flow (unchanged from before, minus the manual upload):
+#   bump version in pyproject.toml + src/caltrain_api/__init__.py, update the
+#   README changelog, commit, then:  git tag vX.Y.Z && git push origin vX.Y.Z
+
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.14"]   # oldest supported and newest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --extra dev
+      - run: uv run pytest -q tests/unit
+      - run: uv run mypy --strict src
+
+  build:
+    name: Build and check distributions
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Tag must match package version
+        run: |
+          version=$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)
+          init_version=$(grep -m1 '^__version__ = ' src/caltrain_api/__init__.py | cut -d'"' -f2)
+          echo "tag=$GITHUB_REF_NAME pyproject=$version __init__=$init_version"
+          test "$GITHUB_REF_NAME" = "v$version" || { echo "::error::tag $GITHUB_REF_NAME != v$version"; exit 1; }
+          test "$version" = "$init_version" || { echo "::error::__version__ $init_version != $version"; exit 1; }
+      - run: uv build
+      - run: uvx twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/caltrain-api/
+    permissions:
+      id-token: write   # required for Trusted Publishing; nothing else gets it
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

{caltrain_api-1.0.1 → caltrain_api-1.1.0}/.gitignore

@@ -30,3 +30,6 @@ Thumbs.db
 
 # Personal project notes for Claude Code (not part of the published project)
 CLAUDE.md
+
+# Sphinx build output
+docs/_build/

caltrain_api-1.1.0/.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration: https://docs.readthedocs.io/en/stable/config-file/v2.html
+# Published at https://caltrain-api.readthedocs.io/
+#   "latest" follows master; "stable" and per-version builds follow vX.Y.Z tags.
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+sphinx:
+  configuration: docs/conf.py
+  # Same strictness as local builds: nitpicky is set in conf.py, so any
+  # warning (including a broken cross-reference) fails the build.
+  fail_on_warning: true
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

{caltrain_api-1.0.1 → caltrain_api-1.1.0}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.5
 Name: caltrain-api
-Version: 1.0.1
+Version: 1.1.0
 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: Documentation, https://caltrain-api.readthedocs.io/
 Project-URL: Changelog, https://github.com/jsinnott/caltrain-api#changelog
 Author-email: Joe Sinnott <joe@jsinnott.net>
 License-Expression: MIT
@@ -31,12 +32,19 @@ Provides-Extra: dev
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: types-protobuf; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: autodoc-pydantic>=2; extra == 'docs'
+Requires-Dist: furo; extra == 'docs'
+Requires-Dist: myst-parser; extra == 'docs'
+Requires-Dist: sphinx<9,>=7; extra == 'docs'
 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.
 
+**Documentation:** https://caltrain-api.readthedocs.io/ (usage guide and full API reference).
+
 ## Install
 
 ```bash
@@ -103,10 +111,18 @@ CALTRAIN_511_API_KEY=... .venv/bin/pytest -s tests/integration   # live; ~2 511
 .venv/bin/mypy --strict src
 ```
 
+API docs (Sphinx, published by Read the Docs; warnings fail the build):
+
+```bash
+uv sync --extra docs
+.venv/bin/sphinx-build -W --keep-going -b html docs docs/_build/html && open docs/_build/html/index.html
+```
+
 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.1.0 -- API documentation: Sphinx docs published at https://caltrain-api.readthedocs.io/ (`docs` extra; strict build). `ExpectedCall` is now exported from `caltrain_api` (it was already part of `TrainObservation`). Docstrings added for previously undocumented members. First release published by the GitHub Actions Trusted Publishing workflow.
 - 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.

{caltrain_api-1.0.1 → caltrain_api-1.1.0}/README.md

@@ -2,6 +2,8 @@
 
 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.
 
+**Documentation:** https://caltrain-api.readthedocs.io/ (usage guide and full API reference).
+
 ## Install
 
 ```bash
@@ -68,10 +70,18 @@ CALTRAIN_511_API_KEY=... .venv/bin/pytest -s tests/integration   # live; ~2 511
 .venv/bin/mypy --strict src
 ```
 
+API docs (Sphinx, published by Read the Docs; warnings fail the build):
+
+```bash
+uv sync --extra docs
+.venv/bin/sphinx-build -W --keep-going -b html docs docs/_build/html && open docs/_build/html/index.html
+```
+
 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.1.0 -- API documentation: Sphinx docs published at https://caltrain-api.readthedocs.io/ (`docs` extra; strict build). `ExpectedCall` is now exported from `caltrain_api` (it was already part of `TrainObservation`). Docstrings added for previously undocumented members. First release published by the GitHub Actions Trusted Publishing workflow.
 - 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.

caltrain_api-1.1.0/docs/api.rst

@@ -0,0 +1,88 @@
+API reference
+=============
+
+Everything here is importable directly from ``caltrain_api`` and is covered by
+semantic versioning.
+
+.. currentmodule:: caltrain_api
+
+Facade
+------
+
+Most applications need only :class:`CaltrainAPI`: it combines the timetable
+with real-time data and returns immutable snapshots.
+
+.. autoclass:: CaltrainAPI
+
+Trains and positions
+--------------------
+
+.. autopydantic_model:: Train
+.. autopydantic_model:: TrainPosition
+.. autopydantic_model:: Stop
+.. autopydantic_model:: Departure
+.. autopydantic_model:: Journey
+.. autopydantic_model:: Alert
+
+Stations and track
+------------------
+
+.. autopydantic_model:: Station
+.. autopydantic_model:: TrackLocation
+.. autoclass:: Corridor
+
+Enumerations
+------------
+
+.. autoclass:: Direction
+   :members:
+   :undoc-members:
+.. autoclass:: ServiceType
+   :members:
+   :undoc-members:
+.. autoclass:: PositionSource
+   :members:
+   :undoc-members:
+.. autoclass:: Relation
+   :members:
+   :undoc-members:
+.. autoclass:: TrainStatus
+   :members:
+   :undoc-members:
+
+Timetable
+---------
+
+:class:`Schedule` works without an API key or (after the first download)
+network access. :class:`CaltrainAPI` builds on it; use it directly for
+timetable-only applications.
+
+.. autoclass:: Schedule
+
+Descriptions
+------------
+
+.. autopydantic_model:: DescriptionPolicy
+
+Real-time sources
+-----------------
+
+The default source is :class:`SiriRealtimeSource`. Implement
+:class:`RealtimeSource` to plug in another feed.
+
+.. autoclass:: RealtimeSource
+.. autoclass:: SiriRealtimeSource
+.. autopydantic_model:: RealtimeSnapshot
+.. autopydantic_model:: TrainObservation
+.. autopydantic_model:: ExpectedCall
+
+Errors
+------
+
+.. autoexception:: CaltrainError
+.. autoexception:: ScheduleUnavailableError
+.. autoexception:: RealtimeUnavailableError
+.. autoexception:: RateLimitedError
+.. autoexception:: UnknownStationError
+.. autoexception:: UnknownTrainError
+.. autoexception:: OffCorridorError

caltrain_api-1.1.0/docs/conf.py

@@ -0,0 +1,82 @@
+"""Sphinx configuration for caltrain-api.
+
+Published by Read the Docs (see .readthedocs.yaml). Build locally with the
+same strictness -- any warning, including a broken cross-reference, fails:
+
+    uv sync --extra docs
+    .venv/bin/sphinx-build -W --keep-going -b html docs docs/_build/html
+"""
+
+from importlib.metadata import version as _version
+
+project = "caltrain-api"
+author = "Joe Sinnott"
+copyright = "2026, Joe Sinnott"
+release = _version("caltrain-api")
+version = release
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",        # Google-style Args:/Returns:/Raises: sections
+    "sphinx.ext.intersphinx",     # links to Python / pydantic / httpx docs
+    "sphinx.ext.viewcode",        # "[source]" links
+    "myst_parser",                # Markdown pages (README, data findings)
+    "sphinxcontrib.autodoc_pydantic",
+]
+
+exclude_patterns = ["_build"]
+nitpicky = True  # warn on every unresolvable reference (local and Read the Docs alike)
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
+
+# -- autodoc -------------------------------------------------------------------
+autodoc_member_order = "bysource"
+autodoc_typehints = "signature"
+autodoc_class_signature = "separated"
+autodoc_default_options = {"members": True, "show-inheritance": True}
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_use_rtype = False
+
+# Pydantic models: list fields with their descriptions; hide JSON schema,
+# config and validator noise that callers don't need.
+autodoc_pydantic_model_show_json = False
+autodoc_pydantic_model_show_config_summary = False
+autodoc_pydantic_model_show_validator_summary = False
+autodoc_pydantic_model_show_validator_members = False
+autodoc_pydantic_model_show_field_summary = False
+autodoc_pydantic_model_member_order = "bysource"
+autodoc_pydantic_field_list_validators = False
+autodoc_pydantic_field_show_constraints = True
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "pydantic": ("https://docs.pydantic.dev/latest", None),
+    # httpx's docs are MkDocs, with no Sphinx inventory to link against.
+}
+
+# Names in rendered type annotations that have no link target. They still
+# display; this just stops the strict (-n) build from failing on them.
+nitpick_ignore = [
+    ("py:class", "httpx.Client"),
+    ("py:class", "AwareDatetime"),   # pydantic.AwareDatetime, rendered unqualified
+    ("py:class", "date"),            # datetime.date, rendered unqualified
+    ("py:class", "timedelta"),       # datetime.timedelta, rendered unqualified
+]
+
+
+def _hide_private_bases(app, name, obj, options, bases):
+    """Show the internal frozen-model base class as pydantic.BaseModel."""
+    from pydantic import BaseModel
+
+    bases[:] = [BaseModel if b.__name__ == "_Frozen" else b for b in bases]
+
+
+def setup(app):
+    app.connect("autodoc-process-bases", _hide_private_bases)
+
+# -- MyST ----------------------------------------------------------------------
+myst_heading_anchors = 3
+
+# -- HTML ----------------------------------------------------------------------
+html_theme = "furo"
+html_title = f"caltrain-api {release}"

caltrain_api-1.1.0/docs/index.md

@@ -0,0 +1,26 @@
+# caltrain-api
+
+Caltrain schedules and train positions for Python: where every train is (latitude/longitude, milepost from San Francisco 4th & King, and plain English like "approaching Redwood City"), where it should be, departures, point-to-point timetables, delays and service alerts -- from Caltrain's static GTFS feed and 511.org real-time data.
+
+```bash
+pip install caltrain-api
+```
+
+```python
+from caltrain_api import CaltrainAPI
+
+api = CaltrainAPI(api_key="...")   # a free 511.org key; omit for timetable-only
+for train in api.get_active_trains():
+    print(train.number, train.position.milepost, train.position.description)
+```
+
+Start with the {doc}`overview` (usage, positions, data handling), then the {doc}`api` for every class and method. {doc}`data-findings` records what the data sources actually provide and how that shaped the design.
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+overview
+api
+data-findings
+```

caltrain_api-1.1.0/docs/overview.md

@@ -0,0 +1,5 @@
+# Overview
+
+```{include} ../README.md
+:start-after: "# caltrain-api"
+```

{caltrain_api-1.0.1 → caltrain_api-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "caltrain-api"
-version = "1.0.1"
+version = "1.1.0"
 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"
@@ -37,6 +37,7 @@ dependencies = [
 Homepage = "https://github.com/jsinnott/caltrain-api"
 Repository = "https://github.com/jsinnott/caltrain-api"
 Issues = "https://github.com/jsinnott/caltrain-api/issues"
+Documentation = "https://caltrain-api.readthedocs.io/"
 Changelog = "https://github.com/jsinnott/caltrain-api#changelog"
 
 [project.optional-dependencies]
@@ -45,6 +46,12 @@ dev = [
     "mypy>=1.10",
     "types-protobuf",
 ]
+docs = [
+    "sphinx>=7,<9",   # autodoc-pydantic 2.2 drops model properties/methods under Sphinx 9
+    "furo",
+    "myst-parser",
+    "autodoc-pydantic>=2",
+]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/caltrain_api"]

{caltrain_api-1.0.1 → caltrain_api-1.1.0}/src/caltrain_api/__init__.py

@@ -4,7 +4,7 @@ Public API -- everything importable from ``caltrain_api`` directly is covered
 by semantic versioning; submodule internals are not.
 """
 
-__version__ = "1.0.1"
+__version__ = "1.1.0"
 
 from .api import CaltrainAPI
 from .corridor import Corridor
@@ -33,7 +33,13 @@ from .models import (
     TrainPosition,
     TrainStatus,
 )
-from .realtime import RealtimeSnapshot, RealtimeSource, SiriRealtimeSource, TrainObservation
+from .realtime import (
+    ExpectedCall,
+    RealtimeSnapshot,
+    RealtimeSource,
+    SiriRealtimeSource,
+    TrainObservation,
+)
 from .schedule import Schedule
 
 __all__ = [
@@ -45,6 +51,7 @@ __all__ = [
     "Journey",
     "DescriptionPolicy",
     "Direction",
+    "ExpectedCall",
     "OffCorridorError",
     "PositionSource",
     "RateLimitedError",

{caltrain_api-1.0.1 → caltrain_api-1.1.0}/src/caltrain_api/corridor.py

@@ -92,7 +92,7 @@ class _Polyline:
 class Corridor:
     """The Caltrain line as a single measured polyline.
 
-    Obtain one from :attr:`Schedule.corridor`; constructing directly is for tests.
+    Obtain one from :attr:`~caltrain_api.Schedule.corridor`; constructing directly is for tests.
     Immutable and safe to share between threads.
     """
 

{caltrain_api-1.0.1 → caltrain_api-1.1.0}/src/caltrain_api/models.py

@@ -151,12 +151,12 @@ class Stop(_Frozen):
 
     @property
     def arrival(self) -> datetime:
-        """Best available arrival time: expected if known, else scheduled."""
+        """The best available arrival time (expected if known, else scheduled)."""
         return self.expected_arrival or self.scheduled_arrival
 
     @property
     def departure(self) -> datetime:
-        """Best available departure time: expected if known, else scheduled."""
+        """The best available departure time (expected if known, else scheduled)."""
         return self.expected_departure or self.scheduled_departure
 
     @property
@@ -173,7 +173,7 @@ class TrainPosition(TrackLocation):
     A ``TrackLocation`` plus when, how we know, and how it relates to stations.
     ``station``/``previous_station``/``next_station`` refer to *physical*
     neighbors along the track, including stations the train does not stop at;
-    use :attr:`Train.next_stop` for the next station it will serve.
+    use :attr:`~caltrain_api.Train.next_stop` for the next station it will serve.
     """
 
     source: PositionSource
@@ -263,10 +263,12 @@ class Train(_Frozen):
 
     @property
     def origin(self) -> Station:
+        """The station the trip starts from."""
         return self.stops[0].station
 
     @property
     def destination(self) -> Station:
+        """The station the trip ends at."""
         return self.stops[-1].station
 
     @property
@@ -315,6 +317,7 @@ class Journey(_Frozen):
 
     @property
     def scheduled_duration(self) -> timedelta:
+        """Timetable duration, origin departure to destination arrival."""
         return self.destination_stop.scheduled_arrival - self.origin_stop.scheduled_departure
 
     @property

{caltrain_api-1.0.1 → caltrain_api-1.1.0}/src/caltrain_api/realtime.py

@@ -290,6 +290,7 @@ class SiriRealtimeSource:
         return resp.content
 
     def fetch(self) -> RealtimeSnapshot:
+        """Fetch train data (and alerts, if due) from 511. See :meth:`RealtimeSource.fetch`."""
         now = self._clock()
         raw = self._get(self.VEHICLE_MONITORING_URL, "VehicleMonitoring", format="json")
         try:

{caltrain_api-1.0.1 → caltrain_api-1.1.0}/src/caltrain_api/schedule.py

@@ -451,14 +451,17 @@ class Schedule:
 
     @property
     def feed_version(self) -> str:
+        """The feed's ``feed_version`` from ``feed_info.txt`` (or ``"unknown"``)."""
         return self._feed_version
 
     @property
     def valid_from(self) -> date:
+        """First service date the feed covers (``feed_start_date``, else the calendar's earliest)."""
         return self._valid_from
 
     @property
     def valid_until(self) -> date:
+        """Last service date the feed covers; past it, :meth:`load` re-downloads."""
         return self._valid_until
 
     @property
@@ -468,10 +471,12 @@ class Schedule:
 
     @property
     def corridor(self) -> Corridor:
+        """The measured SF -> Gilroy track used for all mileposts."""
         return self._corridor
 
     @property
     def description_policy(self) -> DescriptionPolicy:
+        """Thresholds and wording used for position descriptions."""
         return self._policy
 
     # -- stations -----------------------------------------------------------
@@ -690,7 +695,7 @@ class Schedule:
         The relation is WAITING before the origin departure (by best-available
         times) and ARRIVED from the destination arrival on -- in both cases
         only within ``near_radius`` of that station -- and otherwise
-        classified by :attr:`description_policy`.
+        classified by :attr:`~caltrain_api.Schedule.description_policy`.
 
         Args:
             stops: The train's stops (determine AT vs PASSING and WAITING/ARRIVED).