signalk-cli 2.2.1__tar.gz → 3.0.0__tar.gz

{signalk_cli-2.2.1 → signalk_cli-3.0.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: signalk-cli
-Version: 2.2.1
-Summary: Query SignalK v2 APIs and export data as CSV, JSON or Apache Arrow Feather
-Keywords: signalk,sailing,marine,nmea,boating
+Version: 3.0.0
+Summary: Query SignalK v2 APIs and export data as CSV, JSON or Apache Arrow Feather from command line or as a Python API
+Keywords: signalk,sailing,marine,boating,nmea,dataframe,cli,pyarrow,nanoarrow
 Author: jey burrows
 Author-email: jey burrows <jrb@rhizomatics.org.uk>
 License-Expression: Apache-2.0
@@ -15,14 +15,18 @@ Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: click>=8.3.3
+Requires-Dist: nanoarrow>=0.9.0,<1.0.0
 Requires-Dist: niquests[ws]>=2.28
-Requires-Dist: zeroconf>=0.149.16,<0.152.0
+Requires-Dist: niquests[ws]>=3.21.0 ; sys_platform == 'emscripten'
+Requires-Dist: zeroconf>=0.149.16,<0.152.0 ; sys_platform != 'emscripten'
+Requires-Dist: pyarrow>=17.0 ; extra == 'arrow'
 Requires-Dist: pyarrow>=17.0 ; extra == 'feather'
 Requires-Python: >=3.13
 Project-URL: Homepage, https://signalk-cli.rhizomatics.org.uk
 Project-URL: Repository, https://github.com/rhizomatics/signalk-cli
 Project-URL: Issues, https://github.com/rhizomatics/signalk-cli/issues
 Project-URL: Changelog, https://github.com/rhizomatics/signalk-cli/blob/main/CHANGELOG.md
+Provides-Extra: arrow
 Provides-Extra: feather
 Description-Content-Type: text/markdown
 
@@ -41,7 +45,7 @@ Description-Content-Type: text/markdown
 [![Dependabot Updates](https://github.com/rhizomatics/signalk-cli/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/rhizomatics/signalk-cli/actions/workflows/dependabot/dependabot-updates)
 [![boat tech directory](https://boat-tech-directory.rhizomatics.org.uk/images/badge.svg)](https://boat-tech-directory.rhizomatics.org.uk)
 
-Query and explore NMEA and other boat data from SignalK APIs using the command line, and export data as CSV, Apache Arrow Feather, or JSON.
+Query and explore NMEA and other boat data from SignalK APIs using the command line or the Python API.  Export data as CSV, Apache Arrow Feather, or JSON or use as dataframes in scripts or data notebooks.
 
 APIs supported:
 
@@ -71,17 +75,18 @@ Python is required to run this, version 3.13 or above. [uv](https://docs.astral.
 
 For Apache Arrow Feather export, use the optional dependency: ```pip install 'signalk-cli[feather]'```
 
-### Pyodide / slim install
+### Pyodide / WebAssembly
 
-`zeroconf` (used only for mDNS host discovery) can't run in Pyodide, and is optional at runtime. Install without dependencies and add the rest explicitly:
+The same wheel installs in Pyodide (e.g. marimo in the browser). Platform markers skip `zeroconf`, which can't run there, and require `niquests>=3.21.0`:
 
 ```python
 import micropip
-await micropip.install(["click", "niquests[ws]>=3.21.0"])
-await micropip.install("signalk-cli", deps=False)
+await micropip.install("signalk-cli")
 ```
 
-Without `zeroconf`, the host must be given with `--host` or `SIGNALK_HOST` (or come from the cache).
+Without `zeroconf` there's no mDNS discovery, so the host must be given with `--host` or `SIGNALK_HOST` (or come from the cache).
+
+See [signalk-datalab-plugin](https://github.com/rhizomatics/signalk-datalab-plugin) for a working example of this.
 
 ### Local Copy
 
@@ -105,6 +110,20 @@ uv run --with signalk-cli signalk_cli.history list-providers
 uv run --with signalk-cli signalk_cli.stream deltas navigation.position --follow
 ```
 
+## Python library
+
+Everything the CLI does is also available from Python, returning tables that load straight into polars, pandas, pyarrow or DuckDB:
+
+```python
+from signalk_cli import HistoryClient, TimeRange
+import polars as pl
+
+with HistoryClient("http://boat.local:3000") as client:
+    df = pl.DataFrame(client.query(["navigation.*"], TimeRange(duration="P1D")))
+```
+
+See the [Python library guide](https://signalk-cli.rhizomatics.org.uk/library/) and API reference.
+
 ## Running
 
 Run via `python -m signalk_cli.history <command>` or `python -m signalk_cli.stream <command>` or without installing the module with `uv run --with signalk-cli signalk_cli.history <command>`.
@@ -150,7 +169,7 @@ python -m signalk_cli.history query [OPTIONS] PATH...
 **PATH** arguments may be:
 
 - **Literal paths** — e.g. `navigation.speedOverGround`
-- **Regex / glob patterns** — any argument containing metacharacters (`*`, `.`, `[`, `(`, etc.) is matched against the server's `/paths` endpoint. Bare `*` is treated as a glob wildcard.
+- **Regex / glob patterns** — any argument containing a pattern character (`*`, `?`, `+`, `[`, `(`, `{`, `|`, `^`, `$` or `\`) is matched against the server's `/paths` endpoint. A `.` on its own doesn't count, so a plain dotted path is always literal. Bare `*` is treated as a glob wildcard.
 - **Inline path specs** — `path:method` or `path:method:param`, e.g. `navigation.speedOverGround:sma:5`. These pass through to the server unchanged.
 
 #### Options

{signalk_cli-2.2.1 → signalk_cli-3.0.0}/README.md

@@ -13,7 +13,7 @@
 [![Dependabot Updates](https://github.com/rhizomatics/signalk-cli/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/rhizomatics/signalk-cli/actions/workflows/dependabot/dependabot-updates)
 [![boat tech directory](https://boat-tech-directory.rhizomatics.org.uk/images/badge.svg)](https://boat-tech-directory.rhizomatics.org.uk)
 
-Query and explore NMEA and other boat data from SignalK APIs using the command line, and export data as CSV, Apache Arrow Feather, or JSON.
+Query and explore NMEA and other boat data from SignalK APIs using the command line or the Python API.  Export data as CSV, Apache Arrow Feather, or JSON or use as dataframes in scripts or data notebooks.
 
 APIs supported:
 
@@ -43,17 +43,18 @@ Python is required to run this, version 3.13 or above. [uv](https://docs.astral.
 
 For Apache Arrow Feather export, use the optional dependency: ```pip install 'signalk-cli[feather]'```
 
-### Pyodide / slim install
+### Pyodide / WebAssembly
 
-`zeroconf` (used only for mDNS host discovery) can't run in Pyodide, and is optional at runtime. Install without dependencies and add the rest explicitly:
+The same wheel installs in Pyodide (e.g. marimo in the browser). Platform markers skip `zeroconf`, which can't run there, and require `niquests>=3.21.0`:
 
 ```python
 import micropip
-await micropip.install(["click", "niquests[ws]>=3.21.0"])
-await micropip.install("signalk-cli", deps=False)
+await micropip.install("signalk-cli")
 ```
 
-Without `zeroconf`, the host must be given with `--host` or `SIGNALK_HOST` (or come from the cache).
+Without `zeroconf` there's no mDNS discovery, so the host must be given with `--host` or `SIGNALK_HOST` (or come from the cache).
+
+See [signalk-datalab-plugin](https://github.com/rhizomatics/signalk-datalab-plugin) for a working example of this.
 
 ### Local Copy
 
@@ -77,6 +78,20 @@ uv run --with signalk-cli signalk_cli.history list-providers
 uv run --with signalk-cli signalk_cli.stream deltas navigation.position --follow
 ```
 
+## Python library
+
+Everything the CLI does is also available from Python, returning tables that load straight into polars, pandas, pyarrow or DuckDB:
+
+```python
+from signalk_cli import HistoryClient, TimeRange
+import polars as pl
+
+with HistoryClient("http://boat.local:3000") as client:
+    df = pl.DataFrame(client.query(["navigation.*"], TimeRange(duration="P1D")))
+```
+
+See the [Python library guide](https://signalk-cli.rhizomatics.org.uk/library/) and API reference.
+
 ## Running
 
 Run via `python -m signalk_cli.history <command>` or `python -m signalk_cli.stream <command>` or without installing the module with `uv run --with signalk-cli signalk_cli.history <command>`.
@@ -122,7 +137,7 @@ python -m signalk_cli.history query [OPTIONS] PATH...
 **PATH** arguments may be:
 
 - **Literal paths** — e.g. `navigation.speedOverGround`
-- **Regex / glob patterns** — any argument containing metacharacters (`*`, `.`, `[`, `(`, etc.) is matched against the server's `/paths` endpoint. Bare `*` is treated as a glob wildcard.
+- **Regex / glob patterns** — any argument containing a pattern character (`*`, `?`, `+`, `[`, `(`, `{`, `|`, `^`, `$` or `\`) is matched against the server's `/paths` endpoint. A `.` on its own doesn't count, so a plain dotted path is always literal. Bare `*` is treated as a glob wildcard.
 - **Inline path specs** — `path:method` or `path:method:param`, e.g. `navigation.speedOverGround:sma:5`. These pass through to the server unchanged.
 
 #### Options

{signalk_cli-2.2.1 → signalk_cli-3.0.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "signalk-cli"
-version = "2.2.1"
-description = "Query SignalK v2 APIs and export data as CSV, JSON or Apache Arrow Feather"
+version = "3.0.0"
+description = "Query SignalK v2 APIs and export data as CSV, JSON or Apache Arrow Feather from command line or as a Python API"
 readme = "README.md"
 requires-python = ">=3.13"
 license = "Apache-2.0"
@@ -9,8 +9,12 @@ keywords = [
     "signalk",
     "sailing",
     "marine",
-    "nmea",
     "boating",
+    "nmea",
+    "dataframe",
+    "cli",
+    "pyarrow",
+    "nanoarrow",
 ]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -24,8 +28,10 @@ classifiers = [
 ]
 dependencies = [
     "click>=8.3.3",
+    "nanoarrow>=0.9.0,<1.0.0",
     "niquests[ws]>=2.28",
-    "zeroconf>=0.149.16,<0.152.0",
+    "niquests[ws]>=3.21.0; sys_platform == 'emscripten'",
+    "zeroconf>=0.149.16,<0.152.0; sys_platform != 'emscripten'",
 ]
 
 [[project.authors]]
@@ -34,6 +40,7 @@ email = "jrb@rhizomatics.org.uk"
 
 [project.optional-dependencies]
 feather = ["pyarrow>=17.0"]
+arrow = ["pyarrow>=17.0"]
 
 [project.urls]
 Homepage = "https://signalk-cli.rhizomatics.org.uk"
@@ -58,6 +65,9 @@ dev = [
     "genbadge[all]",
     "icdiff",
     "codespell",
+    "polars>=1.44.2,<2.0.0",
+    "duckdb>=1.5.5,<2.0.0",
+    "pandas>=3.0.6,<4.0.0",
 ]
 docs = [
     "properdocs",
@@ -71,6 +81,7 @@ docs = [
     "pngquant",
     "mkdocs-htmlproofer-plugin",
     "mkdocs-llmstxt>=0.5.0,<0.6.0",
+    "mkdocstrings[python]>=1.0.6,<2.0.0",
 ]
 
 [tool.bandit]
@@ -95,7 +106,7 @@ branch = true
 source = ["src"]
 
 [tool.coverage.report]
-fail_under = 0
+fail_under = 90
 
 [tool.coverage.xml]
 output = "cov.xml"
@@ -113,7 +124,10 @@ ignore-words-list = "hass,referer,uint"
 mypy_path = ["./src"]
 
 [[tool.mypy.overrides]]
-module = "pyarrow.*"
+module = [
+    "pyarrow.*",
+    "nanoarrow.*",
+]
 ignore_missing_imports = true
 
 [tool.ty.analysis]

{signalk_cli-2.2.1 → signalk_cli-3.0.0}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 [project]
 name = "signalk-cli"
-version = "2.2.1"
-description = "Query SignalK v2 APIs and export data as CSV, JSON or Apache Arrow Feather"
+version = "3.0.0"
+description = "Query SignalK v2 APIs and export data as CSV, JSON or Apache Arrow Feather from command line or as a Python API"
 readme = "README.md"
 requires-python = ">=3.13"
 license="Apache-2.0"
@@ -9,7 +9,9 @@ authors = [
     { name = "jey burrows", email = "jrb@rhizomatics.org.uk" }
 ]
 
-keywords = ["signalk", "sailing", "marine", "nmea","boating"]
+keywords = ["signalk", "sailing", "marine", "boating",
+            "nmea",
+            "dataframe","cli","pyarrow","nanoarrow"]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Environment :: Console",
@@ -23,12 +25,18 @@ classifiers = [
 
 dependencies = [
     "click>=8.3.3",
+    "nanoarrow>=0.9.0,<1.0.0",
     "niquests[ws]>=2.28",
-    "zeroconf>=0.149.16,<0.152.0",
+    # Pyodide/WASM: niquests needs >=3.21 there, and zeroconf can't run (no raw sockets)
+    "niquests[ws]>=3.21.0; sys_platform == 'emscripten'",
+    "zeroconf>=0.149.16,<0.152.0; sys_platform != 'emscripten'",
 ]
 
 [project.optional-dependencies]
+# pyarrow, only needed to write Feather files from the CLI
 feather = ["pyarrow>=17.0"]
+# alias of feather
+arrow = ["pyarrow>=17.0"]
 [dependency-groups]
 dev = [
     "ruff>=0.16.0",
@@ -41,7 +49,10 @@ dev = [
     "coverage",
     "genbadge[all]",
     "icdiff",
-    "codespell"
+    "codespell",
+    "polars>=1.44.2,<2.0.0",
+    "duckdb>=1.5.5,<2.0.0",
+    "pandas>=3.0.6,<4.0.0",
 ]
 
 docs=[
@@ -56,6 +67,7 @@ docs=[
     "pngquant",
     "mkdocs-htmlproofer-plugin",
     "mkdocs-llmstxt>=0.5.0,<0.6.0",
+    "mkdocstrings[python]>=1.0.6,<2.0.0",
 ]
 
 [project.urls]
@@ -95,7 +107,7 @@ branch = true
 source = ["src"]
 
 [tool.coverage.report]
-fail_under=0
+fail_under=90
 
 [tool.coverage.xml]
 output="cov.xml"
@@ -113,7 +125,7 @@ ignore-words-list="hass,referer,uint"
 mypy_path=["./src"]
 
 [[tool.mypy.overrides]]
-module = "pyarrow.*"
+module = ["pyarrow.*", "nanoarrow.*"]
 ignore_missing_imports = true
 
 [tool.ty.analysis]

signalk_cli-3.0.0/src/signalk_cli/__init__.py

@@ -0,0 +1,33 @@
+"""signalk_cli — Python clients and CLI for SignalK APIs.
+
+The clients are importable from here or from their packages:
+
+```python
+from signalk_cli import HistoryClient, StreamClient, TimeRange
+```
+"""
+
+import logging
+
+from ._arrow import ArrowTable
+from .errors import SignalKError
+from .history import HistoryClient, HistoryResult, TimeRange
+from .net import discover_host
+from .stream import DeltaMessage, DeltaRow, DeltaStream, StreamClient
+
+# Library convention: stay silent unless the application configures logging.
+# The CLI attaches its own stderr handler per command.
+logging.getLogger("signalk_cli").addHandler(logging.NullHandler())
+
+__all__ = [
+    "ArrowTable",
+    "DeltaMessage",
+    "DeltaRow",
+    "DeltaStream",
+    "HistoryClient",
+    "HistoryResult",
+    "SignalKError",
+    "StreamClient",
+    "TimeRange",
+    "discover_host",
+]

signalk_cli-3.0.0/src/signalk_cli/_arrow.py

@@ -0,0 +1,147 @@
+"""A small Arrow table built with nanoarrow, handed to dataframe libraries via the PyCapsule interface."""
+
+import json
+from collections.abc import Mapping, Sequence
+from datetime import datetime
+from typing import Any
+
+import nanoarrow as na
+
+_TIMESTAMP = na.timestamp("us", timezone="UTC")
+
+FEATHER_EXTENSIONS = {".feather", ".arrow", ".fea"}
+
+
+def _is_number(v: object) -> bool:
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def as_text(v: object) -> str | None:
+    if v is None or isinstance(v, str):
+        return v
+    if isinstance(v, (dict, list)):
+        return json.dumps(v)
+    return str(v)
+
+
+def _epoch_us(ts: str | datetime | None) -> int | None:
+    if ts is None:
+        return None
+    dt = datetime.fromisoformat(ts) if isinstance(ts, str) else ts
+    return round(dt.timestamp() * 1_000_000)
+
+
+def infer_column(values: Sequence[Any]) -> tuple[list, Any]:
+    """Pick one Arrow type for a column of JSON values: float64, bool, or string.
+
+    Numbers (and nulls) become float64, booleans stay bool, and anything else
+    — strings, objects, arrays, or a mix — becomes a string column, with
+    objects and arrays JSON-encoded.
+    """
+    present = [v for v in values if v is not None]
+    if all(_is_number(v) for v in present):
+        return [None if v is None else float(v) for v in values], na.float64()
+    if all(isinstance(v, bool) for v in present):
+        return list(values), na.bool_()
+    return [as_text(v) for v in values], na.string()
+
+
+class ArrowTable:
+    """A table of query results, ready to load into any Arrow-aware dataframe library.
+
+    It implements the [Arrow PyCapsule interface](https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html),
+    so it can be passed straight to polars, pandas, pyarrow, DuckDB and others
+    without signalk-cli depending on any of them:
+
+    Examples:
+        ```python
+        import polars as pl
+        df = pl.DataFrame(table)
+        import pandas as pd
+        df = pd.DataFrame.from_arrow(table)  # pandas >= 3.0
+        import pyarrow as pa
+        t = pa.table(table)
+        ```
+    """
+
+    def __init__(self, columns: dict[str, tuple[list, Any]]) -> None:
+        self._columns = {name: values for name, (values, _) in columns.items()}
+        self._types = {name: t for name, (_, t) in columns.items()}
+        lengths = {len(v) for v in self._columns.values()}
+        if len(lengths) > 1:
+            raise ValueError(f"Columns have different lengths: {sorted(lengths)}")
+        self._num_rows = lengths.pop() if lengths else 0
+
+    @classmethod
+    def from_rows(
+        cls,
+        timestamps: Sequence[str | datetime | None],
+        columns: Mapping[str, Sequence[Any]],
+        *,
+        text_columns: Sequence[str] = (),
+        timestamp_name: str = "timestamp",
+    ) -> "ArrowTable":
+        """Build a table with a UTC timestamp column followed by the given columns.
+
+        Column types are inferred from the values (see `infer_column`),
+        except `text_columns`, which are always strings so an empty result
+        keeps the same schema.
+        """
+        built: dict[str, tuple[list, Any]] = {
+            timestamp_name: ([_epoch_us(t) for t in timestamps], _TIMESTAMP)
+        }
+        for name, values in columns.items():
+            if name in text_columns:
+                built[name] = ([as_text(v) for v in values], na.string())
+            else:
+                built[name] = infer_column(values)
+        return cls(built)
+
+    @property
+    def num_rows(self) -> int:
+        return self._num_rows
+
+    @property
+    def column_names(self) -> list[str]:
+        return list(self._columns)
+
+    def __len__(self) -> int:
+        return self._num_rows
+
+    def __repr__(self) -> str:
+        cols = ", ".join(f"{n}: {self._types[n].type.name}" for n in self._columns)
+        return f"ArrowTable({self._num_rows} rows; {cols})"
+
+    def to_pydict(self) -> dict[str, list]:
+        """Return the columns as plain Python lists (timestamps as epoch microseconds)."""
+        return {name: list(values) for name, values in self._columns.items()}
+
+    def _batch(self):
+        children = [
+            na.c_array(values, self._types[name])
+            for name, values in self._columns.items()
+        ]
+        schema = na.struct({name: self._types[name] for name in self._columns})
+        return na.c_array_from_buffers(
+            schema, self._num_rows, [None], children=children
+        )
+
+    def __arrow_c_schema__(self):
+        return na.c_schema(
+            na.struct({name: self._types[name] for name in self._columns})
+        ).__arrow_c_schema__()
+
+    def __arrow_c_stream__(self, requested_schema=None):
+        return na.ArrayStream(self._batch()).__arrow_c_stream__(requested_schema)
+
+
+def write_feather(table: ArrowTable, output: str) -> None:
+    """Write a table to a Feather (Arrow IPC file) — needs pyarrow."""
+    try:
+        import pyarrow as pa
+        from pyarrow import feather
+    except ImportError:
+        raise ImportError(
+            "pyarrow is required for Feather output: pip install 'signalk-cli[feather]'"
+        ) from None
+    feather.write_feather(pa.table(table), output)

signalk_cli-3.0.0/src/signalk_cli/_cli.py

@@ -0,0 +1,82 @@
+"""Click helpers shared by the history and stream CLIs. Not part of the library API."""
+
+import contextlib
+import io
+import logging
+from collections.abc import Iterator
+
+import click
+
+from . import net
+
+logger = logging.getLogger("signalk_cli")
+
+
+class _ClickHandler(logging.Handler):
+    """Send library log messages to stderr as plain text, like the CLI's own messages."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        click.echo(self.format(record), err=True)
+
+
+def host_option(f):
+    return click.option(
+        "--host",
+        default=None,
+        envvar="SIGNALK_HOST",
+        help="SignalK server base URL. http:// added if scheme omitted. "
+        "Discovered via mDNS if omitted.",
+    )(f)
+
+
+def bare_option(f):
+    return click.option(
+        "--bare",
+        is_flag=True,
+        help="Suppress all informational messages, outputting data only.",
+    )(f)
+
+
+@contextlib.contextmanager
+def stderr_ctx(bare: bool) -> Iterator[None]:
+    """Route library log messages to stderr for one command, or discard them all if bare."""
+    handler = _ClickHandler()
+    previous_level = logger.level
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+    try:
+        with (
+            contextlib.redirect_stderr(io.StringIO())
+            if bare
+            else contextlib.nullcontext()
+        ):
+            yield
+    finally:
+        logger.removeHandler(handler)
+        logger.setLevel(previous_level)
+
+
+def resolve_host(host: str | None, no_cache: bool = False) -> str:
+    """Return a normalised host URL, discovering via mDNS if none provided."""
+    if host:
+        return net.normalise_host(host)
+    if not no_cache:
+        cached = net.get_cached_host()
+        if cached:
+            click.echo(f"Using cached host: {cached}", err=True)
+            return cached
+    if net.Zeroconf is None:
+        raise click.UsageError(
+            "No host specified and mDNS discovery unavailable (zeroconf not "
+            "installed). Use --host or set SIGNALK_HOST."
+        )
+    click.echo("No host specified — searching for SignalK via mDNS...", err=True)
+    discovered = net.discover_host()
+    if not discovered:
+        raise click.UsageError(
+            "No SignalK server found via mDNS. Use --host or set SIGNALK_HOST."
+        )
+    click.echo(f"Discovered: {discovered}", err=True)
+    if not no_cache:
+        net.save_cached_host(discovered)
+    return discovered

signalk_cli-3.0.0/src/signalk_cli/errors.py

@@ -0,0 +1,37 @@
+"""Exceptions raised by the signalk_cli library API."""
+
+import contextlib
+
+import niquests
+
+
+def api_error(exc: niquests.RequestException) -> str:
+    """Return the most informative message from an API error response."""
+    resp = getattr(exc, "response", None)
+    if resp is not None:
+        with contextlib.suppress(Exception):
+            body = resp.json()
+            return body.get("error") or body.get("message") or str(exc)
+    return str(exc)
+
+
+class SignalKError(Exception):
+    """A request to a SignalK server failed.
+
+    Attributes:
+        status_code: HTTP status of the failed response, or None if the
+            server couldn't be reached.
+    """
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+    @classmethod
+    def from_request(cls, exc: niquests.RequestException) -> "SignalKError":
+        """Wrap a niquests exception, using the server's error message if it sent one."""
+        resp = getattr(exc, "response", None)
+        status = getattr(resp, "status_code", None)
+        return cls(
+            api_error(exc), status_code=status if isinstance(status, int) else None
+        )

signalk_cli-3.0.0/src/signalk_cli/history/__init__.py

@@ -0,0 +1,25 @@
+"""signalk_cli.history — Python client and CLI for the SignalK v2 History API."""
+
+from .._arrow import ArrowTable
+from ..errors import SignalKError
+from ._time import TimeRange
+from .api import (
+    AGGREGATION_METHODS,
+    HISTORY_BASE,
+    HistoryClient,
+    HistoryResult,
+    build_path_specs,
+    match_paths,
+)
+
+__all__ = [
+    "AGGREGATION_METHODS",
+    "HISTORY_BASE",
+    "ArrowTable",
+    "HistoryClient",
+    "HistoryResult",
+    "SignalKError",
+    "TimeRange",
+    "build_path_specs",
+    "match_paths",
+]