OSHConnect-Python

Library for communicating with Opensensorhub that provides options for saving configurations, getting visualization recommendations for data, retrieving data in real time, archival streams, and batch modes, and more.

API Documentation available here

Links:

• Architecture Doc
• UML Diagram

Pre-releases

Every push to the dev branch publishes a .devN pre-release wheel to TestPyPI once the test suite passes. To install the latest:

pip install --index-url https://test.pypi.org/simple/ \
            --extra-index-url https://pypi.org/simple/ \
            oshconnect --pre

The --extra-index-url is needed so transitive deps (pydantic, paho-mqtt, …) still resolve from real PyPI. Tagged releases (v*) continue to publish to real PyPI via .github/workflows/publish.yml.

Running Tests

uv sync                                # install dev deps (incl. pytest, pytest-cov)
uv run pytest                          # full suite (skips network-marked tests if you add `-m "not network"`)
uv run pytest tests/test_swe_components.py -v   # one file, verbose
uv run pytest -k name_token            # one keyword

Tests that need a live OSH server (e.g. localhost:8282 running FakeWeatherDriver) are tagged @pytest.mark.network. CI skips them; locally you can include or exclude them:

uv run pytest -m "not network"         # what CI runs
uv run pytest -m network               # only the live-server tests

Test Coverage

Coverage is opt-in via pytest-cov. The default pytest run is fast; add --cov when you want a report.

uv run pytest --cov                    # terminal summary + missing lines
uv run pytest --cov --cov-report=html  # HTML report at htmlcov/index.html
uv run pytest --cov --cov-report=xml   # coverage.xml (CI / Codecov-ready)

Configuration lives in pyproject.toml under [tool.coverage.*] — branch coverage is on, source is scoped to src/oshconnect, and obvious dead lines (if TYPE_CHECKING:, raise NotImplementedError, etc.) are excluded.

CI (.github/workflows/tests.yaml) runs the suite with --cov on every push across Python 3.12 / 3.13 / 3.14 and uploads coverage.xml as a workflow artifact (downloadable from the run page).

Documentation Coverage

interrogate reports what fraction of public modules / classes / functions / methods carry a docstring (presence only, it doesn't check style). It's purely informational right now; there's no CI gate. Configuration lives in pyproject.toml under [tool.interrogate] (__init__, dunder, private, and property/setter members are skipped).

uv run interrogate src/oshconnect              # one-line summary
uv run interrogate -v src/oshconnect           # per-file table
uv run interrogate -vv src/oshconnect          # per-symbol (shows which symbols are missing)

Once we agree on a baseline, raise [tool.interrogate].fail-under from 0 so new code without docstrings starts failing locally and in CI.

OGC Format Serialization

Format-explicit conversion methods on the wrapper classes (System, Datastream, ControlStream) and the underlying pydantic resource models. Use these to round-trip CS API server JSON in SML+JSON, OM+JSON, and SWE+JSON without having to remember the model_dump(by_alias=True, …) incantation, and to construct OSHConnect wrappers from raw server payloads.

from oshconnect import Node, System, Datastream

node = Node(protocol="http", address="localhost", port=8282)

# Build a System from an SML+JSON server response
sys_dict = {"type": "PhysicalSystem", "uniqueId": "urn:test:1", "label": "Sensor"}
sys = System.from_csapi_dict(sys_dict, node)        # auto-detects SML vs GeoJSON
sys.to_smljson_dict()                                # -> dict ready to POST

# Build a Datastream from a CS API listing entry
ds = Datastream.from_csapi_dict(ds_json, node)
ds.to_csapi_dict()                                   # the resource body
ds.schema_to_swejson_dict()                          # the SWE+JSON schema doc
ds.observation_to_omjson_dict({"temperature": 22.5}) # one OM+JSON observation

# Single observations / commands
from oshconnect.resource_datamodels import ObservationResource
obs = ObservationResource.from_omjson_dict(om_json_payload)
obs.to_swejson_dict()                                # flat SWE+JSON record

The two older static factories System.from_system_resource and Datastream.from_resource are deprecated in favor of from_csapi_dict and emit DeprecationWarning on use. They'll be removed in a future major version.

Generating the Docs

The documentation is built with Sphinx using the Furo theme, autodoc for auto-generated API reference from docstrings, MyST so that Markdown source files work alongside reST, and sphinxcontrib-mermaid for the architecture diagrams. Sources live under docs/source/.

Install dev dependencies (including Sphinx, Furo, and the plugins):

uv sync --all-extras

Build the HTML docs:

uv run sphinx-build -b html docs/source docs/build/sphinx

Open docs/build/sphinx/index.html in a browser to view locally.

For a live-reloading preview while editing, use sphinx-autobuild:

uv run --with sphinx-autobuild sphinx-autobuild docs/source docs/build/sphinx

To match what CI publishes (warnings become errors — useful after touching docstrings or signatures):

uv run sphinx-build -W --keep-going -b html docs/source docs/build/sphinx

CI builds the site on every push and deploys main to GitHub Pages via .github/workflows/docs_pages.yaml.