somestuff-oepnvstuff 0.2.3__tar.gz

somestuff_oepnvstuff-0.2.3/.gitignore

@@ -0,0 +1,180 @@
+/**/.gtfs_cache
+/*.local
+.claude
+
+/*gguf*
+
+/docker-config
+/docker_build_local.log
+
+/ms?hit
+*mstest*py
+*_test.py
+/umqtt
+.idea/
+/upydev_.config
+*.local.*
+/scripts/logdir/
+
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+

somestuff_oepnvstuff-0.2.3/LICENSE.md

@@ -0,0 +1,163 @@
+GNU Lesser General Public License
+=================================
+
+_Version 3, 29 June 2007_  
+_Copyright © 2007 Free Software Foundation, Inc. &lt;<http://fsf.org/>&gt;_
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+
+This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+### 0. Additional Definitions
+
+As used herein, “this License” refers to version 3 of the GNU Lesser
+General Public License, and the “GNU GPL” refers to version 3 of the GNU
+General Public License.
+
+“The Library” refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+An “Application” is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+A “Combined Work” is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the “Linked
+Version”.
+
+The “Minimal Corresponding Source” for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+The “Corresponding Application Code” for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+### 1. Exception to Section 3 of the GNU GPL
+
+You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+### 2. Conveying Modified Versions
+
+If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+* **a)** under this License, provided that you make a good faith effort to
+ensure that, in the event an Application does not supply the
+function or data, the facility still operates, and performs
+whatever part of its purpose remains meaningful, or
+
+* **b)** under the GNU GPL, with none of the additional permissions of
+this License applicable to that copy.
+
+### 3. Object Code Incorporating Material from Library Header Files
+
+The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+* **a)** Give prominent notice with each copy of the object code that the
+Library is used in it and that the Library and its use are
+covered by this License.
+* **b)** Accompany the object code with a copy of the GNU GPL and this license
+document.
+
+### 4. Combined Works
+
+You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+* **a)** Give prominent notice with each copy of the Combined Work that
+the Library is used in it and that the Library and its use are
+covered by this License.
+
+* **b)** Accompany the Combined Work with a copy of the GNU GPL and this license
+document.
+
+* **c)** For a Combined Work that displays copyright notices during
+execution, include the copyright notice for the Library among
+these notices, as well as a reference directing the user to the
+copies of the GNU GPL and this license document.
+
+* **d)** Do one of the following:
+    - **0)** Convey the Minimal Corresponding Source under the terms of this
+License, and the Corresponding Application Code in a form
+suitable for, and under terms that permit, the user to
+recombine or relink the Application with a modified version of
+the Linked Version to produce a modified Combined Work, in the
+manner specified by section 6 of the GNU GPL for conveying
+Corresponding Source.
+    - **1)** Use a suitable shared library mechanism for linking with the
+Library.  A suitable mechanism is one that **(a)** uses at run time
+a copy of the Library already present on the user's computer
+system, and **(b)** will operate properly with a modified version
+of the Library that is interface-compatible with the Linked
+Version.
+
+* **e)** Provide Installation Information, but only if you would otherwise
+be required to provide such information under section 6 of the
+GNU GPL, and only to the extent that such information is
+necessary to install and execute a modified version of the
+Combined Work produced by recombining or relinking the
+Application with a modified version of the Linked Version. (If
+you use option **4d0**, the Installation Information must accompany
+the Minimal Corresponding Source and Corresponding Application
+Code. If you use option **4d1**, you must provide the Installation
+Information in the manner specified by section 6 of the GNU GPL
+for conveying Corresponding Source.)
+
+### 5. Combined Libraries
+
+You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+* **a)** Accompany the combined library with a copy of the same work based
+on the Library, uncombined with any other library facilities,
+conveyed under the terms of this License.
+* **b)** Give prominent notice with the combined library that part of it
+is a work based on the Library, and explaining where to find the
+accompanying uncombined form of the same work.
+
+### 6. Revised Versions of the GNU Lesser General Public License
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License “or any later version”
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

somestuff_oepnvstuff-0.2.3/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.5
+Name: somestuff-oepnvstuff
+Version: 0.2.3
+Summary: GTFS-Realtime coverage checker: does an open GTFS-RT feed carry real-time data for your lines at your stop? One-shot or MQTT-publishing watcher
+Project-URL: Homepage, https://github.com/vroomfondel/somestuff
+Project-URL: Repository, https://github.com/vroomfondel/somestuff
+Project-URL: Issues, https://github.com/vroomfondel/somestuff/issues
+Author-email: Henning Thieß <ht@xomox.cc>
+License-File: LICENSE.md
+Keywords: gtfs,gtfs-realtime,monitoring,mqtt,oepnv,public-transport,transit
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: gtfs-realtime-bindings>=2.2
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: mqttstuff>=0.0.7
+Requires-Dist: python-dotenv>=1.2
+Requires-Dist: requests>=2.34
+Requires-Dist: tabulate>=0.10
+Requires-Dist: typer>=0.27
+Description-Content-Type: text/markdown
+
+# oepnvstuff
+
+Validate whether an open GTFS-Realtime feed actually carries real-time data
+(delays / actual times) for specific transit lines at a specific station, either
+as a one-shot check or as a long-running watcher that publishes its findings to
+MQTT.
+
+Open-data GTFS-RT aggregators (such as gtfs.de) merge whatever the transit
+agencies deliver. For many rural and suburban lines that is schedule only: the
+feed exists, but your lines never get actual times. This tool answers "is there
+real realtime for my lines at my stop?" before you build anything on top of it.
+The defaults (station `Blankenese`, lines `1/12/22/189`) are just defaults;
+every parameter is overridable via CLI option or `OEPNV_*` environment variable.
+
+## Modules
+
+- **`check_realtime.py`** — Typer CLI: one-shot check or `--watch` poll loop,
+  console report, optional MQTT publishing.
+- **`monitor.py`** — `RealtimeMonitor`: poll loop with staleness detection that
+  dispatches typed results to pluggable `on_*` handlers (cycle, alert, stale,
+  error). Console output and the MQTT bridge are just handlers.
+- **`gtfs_static.py`** — static feed: cached download with conditional GET plus
+  schedule indexing (`StaticFeedIndex`): matched stops, routes of the target
+  lines, and the trips that belong to those lines and serve a matched stop.
+- **`gtfs_realtime.py`** — realtime feed: `RealtimeFetcher` (ETag /
+  If-Modified-Since) and protobuf parsing into a `RealtimeSnapshot`
+  (TripUpdates + ServiceAlerts).
+- **`mqtt_bridge.py`** — `GtfsMqttBridge`: publishes cycle and line status,
+  departures, new alerts and stale transitions via `mqttstuff`.
+
+Only `mqtt_bridge.py` imports `mqttstuff`; the core runs without a broker.
+Logging (loguru, with an intercept for stdlib `logging`, e.g. `requests` and
+`paho-mqtt`) and the startup banner are shared via `somestuff.oepnvstuff`.
+
+### How it works
+
+1. The static GTFS feed (planned schedule, one big zip) is downloaded once and
+   indexed: stops whose name contains the station query, the routes of the target
+   lines, and the trips of those lines that serve one of the matched stops. Next
+   to the cached zip a `<name>.meta.json` sidecar stores the server's
+   `ETag`/`Last-Modified`; every later run sends a conditional GET, so an
+   unchanged feed costs a `304` round-trip instead of a re-download.
+2. The realtime feed (`.pb`, TripUpdates + ServiceAlerts) is fetched, or in
+   `--watch` mode polled (GTFS-RT is not push/WebSocket). The fetcher keeps the
+   HTTP validators between polls, so unchanged cycles are `304`s.
+3. TripUpdates are matched against the target trips (`trip_id`) and target lines
+   (`route_id`); delay values are aggregated per line.
+4. Staleness is detected two ways, and either marks the cycle stale: the feed's
+   own `FeedHeader.timestamp` is older than `--max-age` seconds, or
+   `--stale-cycles` consecutive cycles passed without a timestamp change.
+
+## Installation
+
+```bash
+pip install somestuff-oepnvstuff
+```
+
+`somestuff` is a PEP 420 namespace; the package is imported as
+`somestuff.oepnvstuff` and shares the namespace with the other `somestuff-*`
+distributions.
+
+## Usage
+
+Console script and module invocation are equivalent:
+
+```bash
+oepnv-check-realtime
+python3 -m somestuff.oepnvstuff.check_realtime
+```
+
+One-shot check (human-readable report, the exit code summarises the result):
+
+```bash
+oepnv-check-realtime
+oepnv-check-realtime --station "Blankenese" --lines "286,488"
+```
+
+Both feed options also accept local file paths (handy for tests):
+`--static feed.zip --realtime snapshot.pb`.
+
+Exit codes: `0` realtime found for at least one line (or watch ended cleanly),
+`2` schedule found but no realtime (or stale abort), `3` no matching stops or
+trips in the static feed, `1` technical error.
+
+### Stations, lines and `--near`
+
+```bash
+# which stops would match? Reads only stops.txt plus one stop_times pass and
+# shows coordinates, serving lines (incl. agency) and directions per stop
+oepnv-check-realtime --show-stops
+
+# several stations at once, ';'-separated (stop names contain commas and spaces)
+oepnv-check-realtime --station "Blankenese;Ellerbek" --lines "1,189,195"
+
+# same-named stations in different towns? GTFS has no postal codes, so filter
+# geographically by 'lat,lon,radius_km'; applies to the check itself as well.
+# Several areas are ';'-separated and OR-combined.
+oepnv-check-realtime --show-stops --station Blankenese --near 53.5633,9.8144,2
+oepnv-check-realtime --near "53.5633,9.8144,2;53.647,9.892,3"
+```
+
+### Watch mode
+
+```bash
+# poll loop, one compact status line per cycle
+oepnv-check-realtime --watch --interval 180
+
+# exit with code 2 once the feed goes stale (lets a supervisor restart it)
+oepnv-check-realtime --watch --stop-on-stale
+```
+
+### Departures
+
+```bash
+# next N departures per line+direction, with realtime delay
+# ("1 Richtung S Rissen: in 2 min (+80s)")
+oepnv-check-realtime --watch --departures --departures-count 2
+```
+
+`--departures-horizon` sets the look-ahead window in hours (default 48).
+
+### MQTT
+
+```bash
+oepnv-check-realtime --watch --mqtt --mqtt-host broker.example.org
+mosquitto_sub -h broker.example.org -v -t 'oepnv/#'
+```
+
+With `base_topic` at its default `oepnv`:
+
+| Topic                                        | Payload                                                                                                                                                                    |
+|----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `oepnv/status`                               | per-cycle summary: feed ts/age, stale flag, per-line hit counts                                                                                                            |
+| `oepnv/lines/<line>/status`                  | one line: `updates`, `delay_min/max/avg_s`, `static_trips`                                                                                                                 |
+| `oepnv/departures`                           | with `--departures`: all upcoming departures in one document (`in_minutes`, `delay_s`, `realtime`, stop, times); published every cycle, empty list when the board is empty |
+| `oepnv/departures/<line>/<stop>/<direction>` | one group's departures; ASCII-simplified segments (`departures/1/S_Blankenese/U_Kellinghusenstrasse`)                                                                      |
+| `oepnv/alerts`                               | each new (deduplicated) service alert: `{entity, text}`                                                                                                                    |
+| `oepnv/stale`                                | fired once on the transition into staleness                                                                                                                                |
+
+Everything is published with `retain=False`: the broker keeps no last value and
+subscribers see the live stream only. A late subscriber waits at most one poll
+interval for the next status/departures cycle.
+
+## Configuration
+
+Precedence: CLI option > real environment variable > `./oepnv.local.env` (current
+working directory) > `oepnv.local.env` next to the installed `check_realtime`
+module. Both env files are auto-loaded via `python-dotenv` and never override
+variables that are already set. An example env file ships in the repository, not
+in the wheel:
+https://github.com/vroomfondel/somestuff/tree/main/somestuff/oepnvstuff/
+
+| Env var                          | CLI                            | Default                                                                                       |
+|----------------------------------|--------------------------------|-----------------------------------------------------------------------------------------------|
+| `OEPNV_STATIC_URL`               | `--static`                     | `https://download.gtfs.de/germany/nv_free/latest.zip` (URL or `.zip` path)                    |
+| `OEPNV_REALTIME_URL`             | `--realtime`                   | `https://realtime.gtfs.de/realtime-free.pb` (URL or `.pb` path)                               |
+| `OEPNV_LINES`                    | `--lines`, `-l`                | `1,12,22,189` (comma/space separated)                                                         |
+| `OEPNV_STATION`                  | `--station`, `-s`              | `Blankenese` (case-insensitive substring match; several stations `;`-separated)               |
+| `OEPNV_NEAR`                     | `--near`                       | off; `lat,lon,radius_km` geo filter for the matched stops, areas `;`-separated (OR)           |
+| `OEPNV_ENABLE_DEPARTURES`        | `--departures/--no-departures` | off; report upcoming departures per line+direction                                            |
+| `OEPNV_DEPARTURES_COUNT`         | `--departures-count`           | `3`; next N departures per line+direction                                                     |
+| `OEPNV_DEPARTURES_HORIZON_HOURS` | `--departures-horizon`         | `48` h look-ahead                                                                             |
+| `OEPNV_CACHE_DIR`                | `--cache-dir`                  | `.gtfs_cache`                                                                                 |
+| `OEPNV_FORCE_REFRESH`            | `--force-refresh`              | off; re-download the static zip even on `304`                                                 |
+| `OEPNV_WATCH`                    | `--watch`, `-w`                | off                                                                                           |
+| `OEPNV_INTERVAL`                 | `--interval`                   | `180` s, see Bandwidth below                                                                  |
+| `OEPNV_MAX_AGE`                  | `--max-age`                    | `120` s (`0` = off)                                                                           |
+| `OEPNV_STALE_CYCLES`             | `--stale-cycles`               | `6`                                                                                           |
+| `OEPNV_STOP_ON_STALE`            | `--stop-on-stale`              | off                                                                                           |
+| `OEPNV_RECENT_WINDOW`            | `--recent-window`              | `900` s; a line still counts as `realtime_recent` this long after its last update (`0` = off) |
+| `OEPNV_MQTT_ENABLE`              | `--mqtt/--no-mqtt`             | off                                                                                           |
+| `OEPNV_MQTT_HOST`                | `--mqtt-host`                  | `mosquitto.mosquitto.svc.cluster.local`                                                       |
+| `OEPNV_MQTT_PORT`                | `--mqtt-port`                  | `1883`                                                                                        |
+| `OEPNV_MQTT_USER`                | `--mqtt-user`                  | anonymous                                                                                     |
+| `OEPNV_MQTT_PASSWORD`            | `--mqtt-password`              | empty                                                                                         |
+| `OEPNV_MQTT_BASE_TOPIC`          | `--mqtt-base-topic`            | `oepnv`                                                                                       |
+| `OEPNV_MQTT_TLS`                 | `--mqtt-tls`                   | off; the port is not switched automatically, TLS brokers usually listen on `8883`             |
+| `OEPNV_MQTT_TLS_CA`              | `--mqtt-tls-ca`                | system CA store; CA certificate path                                                          |
+| `OEPNV_MQTT_TLS_CERT`            | `--mqtt-tls-cert`              | off; client certificate for mutual TLS (with `OEPNV_MQTT_TLS_KEY`)                            |
+| `OEPNV_MQTT_TLS_KEY`             | `--mqtt-tls-key`               | off; client key for mutual TLS                                                                |
+| `OEPNV_MQTT_TLS_INSECURE`        | `--mqtt-tls-insecure`          | off; skip hostname verification (self-signed certs), chain verification still applies         |
+| `OEPNV_VERBOSE`                  | `--verbose`, `-v`              | off; DEBUG logging                                                                            |
+
+`--show-stops` has no environment variable.
+
+### Bandwidth
+
+`OEPNV_INTERVAL` is the only lever on data volume, for a reason that is not
+obvious:
+
+- `RealtimeFetcher` sends conditional requests (`If-None-Match` /
+  `If-Modified-Since`) and gtfs.de answers them correctly with `304`.
+- gtfs.de rebuilds `realtime-free.pb` once per minute (`FeedHeader.timestamp`
+  always lands on `:50`). With an interval of 60 s or less every poll is
+  therefore a genuinely new body; the `304` is structurally unreachable, not
+  broken.
+- The feed is uncompressed (no `Content-Encoding`) and there is no smaller
+  regional variant: `realtime-{nv,fv,rv}.pb` return 404, only the nationwide
+  feed exists.
+
+Volume therefore depends only on how many feed versions are fetched, not on how
+often you poll. Polling faster than the rebuild costs nothing (the extra polls
+are `304`s); polling slower is the only saving. Measured over 360 cycles: about
+44 MB per version (min 29, max 53).
+
+| Interval        | Versions/day | Volume/day |
+|-----------------|--------------|------------|
+| 20-60 s         | 1440         | ~61 GB     |
+| 180 s (default) | 480          | ~20 GB     |
+| 300 s           | 288          | ~12 GB     |
+| 600 s           | 144          | ~6 GB      |
+
+`OEPNV_MAX_AGE` does not have to grow with the interval: `age` is
+`now - feed_ts` at fetch time and stays below 60 s because of the per-minute
+rebuild, regardless of the interval.
+
+### Kubernetes
+
+Configure everything via env in the Deployment. Point `OEPNV_CACHE_DIR` at a
+persistent volume so pod restarts reuse the large static zip via `304`, and
+combine `OEPNV_WATCH=1` with `OEPNV_STOP_ON_STALE=1` so a dead feed exits with
+code 2 and the kubelet restarts the pod. A ready-made Deployment (watch + MQTT +
+cache volume) and a Secret example for the broker credentials are in the
+repository, not in the wheel:
+https://github.com/vroomfondel/somestuff/tree/main/somestuff/oepnvstuff/
+
+## Library
+
+The monitor knows nothing about consoles or brokers: it dispatches typed
+results to registered handlers. Add your own the same way the console report and
+the MQTT bridge do:
+
+```python
+from somestuff.oepnvstuff.gtfs_realtime import RealtimeFetcher
+from somestuff.oepnvstuff.gtfs_static import build_index, obtain
+from somestuff.oepnvstuff.monitor import CycleResult, RealtimeMonitor
+
+index = build_index(obtain("https://download.gtfs.de/germany/nv_free/latest.zip", ".gtfs_cache"),
+                    ["1", "189"], "Blankenese")
+monitor = RealtimeMonitor(RealtimeFetcher("https://realtime.gtfs.de/realtime-free.pb"), index,
+                          interval=180.0, stop_on_stale=True)
+
+def my_handler(cycle: CycleResult) -> None:
+    for line, status in cycle.per_line.items():
+        print(line, status.updates, status.avg_delay)
+
+monitor.add_cycle_handler(my_handler)          # every completed cycle
+monitor.add_alert_handler(print)               # each new service alert (deduplicated)
+monitor.add_stale_handler(print)               # edge-triggered on going stale
+monitor.add_error_handler(print)               # fetch errors (loop keeps running)
+
+raise SystemExit(monitor.watch())              # or: monitor.check_once()
+```
+
+Handler exceptions are logged and swallowed, so one misbehaving sink cannot kill
+the poll loop.
+
+## Data sources
+
+The defaults are the free, registration-less feeds from gtfs.de (CC BY-SA 4.0,
+https://gtfs.de/de/open-data/): static `germany/nv_free/latest.zip` (German
+regional transit) and `realtime-free.pb` (TripUpdates + ServiceAlerts). Any other
+GTFS / GTFS-RT pair works via `--static` / `--realtime`, for example an agency's
+own feed if the open aggregate turns out to lack your lines (for HVV territory:
+Geofox-GTI).
+
+## Notes
+
+- Requires: `loguru`, `typer`, `gtfs-realtime-bindings`, `python-dotenv`,
+  `requests`, `tabulate`, `mqttstuff`.
+- Licensed under the LGPL, see `LICENSE.md` in the repository root.