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

signalk_cli-2.2.0/README.md → signalk_cli-3.0.0/PKG-INFO

@@ -1,21 +1,71 @@
+Metadata-Version: 2.4
+Name: signalk-cli
+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
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Natural Language :: English
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering
+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: 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
+
 # SignalK CLI
 
-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.
+[![Rhizomatics Open Source](https://img.shields.io/badge/rhizomatics%20open%20source-lightseagreen)](https://github.com/rhizomatics)
+
+[![PyPI - Version](https://img.shields.io/pypi/v/signalk-cli)](https://pypi.org/project/signalk-cli/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/rhizomatics/signalk-cli)
+[![Coverage](https://raw.githubusercontent.com/rhizomatics/signalk-cli/refs/heads/badges/badges/coverage.svg)](https://signalk-cli.rhizomatics.org.uk/developer/coverage/)
+![Tests](https://raw.githubusercontent.com/rhizomatics/signalk-cli/refs/heads/badges/badges/tests.svg)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/rhizomatics/signalk-cli/main.svg)](https://results.pre-commit.ci/latest/github/rhizomatics/signalk-cli/main)
+[![Publish Python 🐍 distribution 📦 to PyPI and TestPyPI](https://github.com/rhizomatics/signalk-cli/actions/workflows/pypi-publish.yml/badge.svg)](https://github.com/rhizomatics/signalk-cli/actions/workflows/pypi-publish.yml)
+[![Github Deploy](https://github.com/rhizomatics/signalk-cli/actions/workflows/python-package.yml/badge.svg?branch=main)](https://github.com/rhizomatics/signalk-cli/actions/workflows/python-package.yml)
+[![CodeQL](https://github.com/rhizomatics/signalk-cli/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/rhizomatics/signalk-cli/actions/workflows/github-code-scanning/codeql)
+[![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 or the Python API.  Export data as CSV, Apache Arrow Feather, or JSON or use as dataframes in scripts or data notebooks.
 
 APIs supported:
 
-* [SignalK v2 History API](https://signalk.org/https://demo.signalk.org/documentation/Developing/REST_APIs/History_API.html). Commands available:
-  - list-paths
-  - list-providers
-  - list-contexts
-  - query
-  - cardinality
-* [SignalK v1 Streaming API](https://signalk.org/specification/1.8.2/doc/streaming_api.html). Commands available:
-  - deltas
+### [SignalK v2 History API](https://demo.signalk.org/documentation/Developing/REST_APIs/History_API.html). 
+
+- Commands available:
+    - `list-paths`
+    - `list-providers`
+    - `list-contexts`
+    - `query`
+    - `cardinality`
+
+### [SignalK v1 Streaming API](https://signalk.org/specification/1.8.2/doc/streaming_api.html). 
+
+- Commands available:
+    - `deltas`
 
 ## Installation
 
-`signalk-cli` is published to PyPi at https://pypi.org/project/signalk-cli/
+`signalk-cli` is published to [PyPi](https://pypi.org/project/signalk-cli/)
 
 Python is required to run this, version 3.13 or above. [uv](https://docs.astral.sh/uv/) is the recommended way to install the package ( and can install Python ) but is not required.
 
@@ -25,6 +75,19 @@ 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 / WebAssembly
+
+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("signalk-cli")
+```
+
+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
 
 Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).
@@ -47,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>`.
@@ -90,8 +167,9 @@ 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.0/PKG-INFO → signalk_cli-3.0.0/README.md

@@ -1,49 +1,39 @@
-Metadata-Version: 2.4
-Name: signalk-cli
-Version: 2.2.0
-Summary: Query SignalK v2 APIs and export data as CSV, JSON or Apache Arrow Feather
-Keywords: signalk,sailing,marine,nmea,boating
-Author: jey burrows
-Author-email: jey burrows <jrb@rhizomatics.org.uk>
-License-Expression: Apache-2.0
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Natural Language :: English
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Scientific/Engineering
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: click>=8.3.3
-Requires-Dist: niquests[ws]>=2.28
-Requires-Dist: zeroconf>=0.149.16,<0.150.0
-Requires-Dist: pyarrow>=17.0 ; extra == 'feather'
-Requires-Python: >=3.13
-Project-URL: Homepage, https://github.com/rhizomatics/signalk-cli
-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: feather
-Description-Content-Type: text/markdown
-
 # SignalK CLI
 
-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.
+[![Rhizomatics Open Source](https://img.shields.io/badge/rhizomatics%20open%20source-lightseagreen)](https://github.com/rhizomatics)
+
+[![PyPI - Version](https://img.shields.io/pypi/v/signalk-cli)](https://pypi.org/project/signalk-cli/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/rhizomatics/signalk-cli)
+[![Coverage](https://raw.githubusercontent.com/rhizomatics/signalk-cli/refs/heads/badges/badges/coverage.svg)](https://signalk-cli.rhizomatics.org.uk/developer/coverage/)
+![Tests](https://raw.githubusercontent.com/rhizomatics/signalk-cli/refs/heads/badges/badges/tests.svg)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/rhizomatics/signalk-cli/main.svg)](https://results.pre-commit.ci/latest/github/rhizomatics/signalk-cli/main)
+[![Publish Python 🐍 distribution 📦 to PyPI and TestPyPI](https://github.com/rhizomatics/signalk-cli/actions/workflows/pypi-publish.yml/badge.svg)](https://github.com/rhizomatics/signalk-cli/actions/workflows/pypi-publish.yml)
+[![Github Deploy](https://github.com/rhizomatics/signalk-cli/actions/workflows/python-package.yml/badge.svg?branch=main)](https://github.com/rhizomatics/signalk-cli/actions/workflows/python-package.yml)
+[![CodeQL](https://github.com/rhizomatics/signalk-cli/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/rhizomatics/signalk-cli/actions/workflows/github-code-scanning/codeql)
+[![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 or the Python API.  Export data as CSV, Apache Arrow Feather, or JSON or use as dataframes in scripts or data notebooks.
 
 APIs supported:
 
-* [SignalK v2 History API](https://signalk.org/https://demo.signalk.org/documentation/Developing/REST_APIs/History_API.html). Commands available:
-  - list-paths
-  - list-providers
-  - list-contexts
-  - query
-  - cardinality
-* [SignalK v1 Streaming API](https://signalk.org/specification/1.8.2/doc/streaming_api.html). Commands available:
-  - deltas
+### [SignalK v2 History API](https://demo.signalk.org/documentation/Developing/REST_APIs/History_API.html). 
+
+- Commands available:
+    - `list-paths`
+    - `list-providers`
+    - `list-contexts`
+    - `query`
+    - `cardinality`
+
+### [SignalK v1 Streaming API](https://signalk.org/specification/1.8.2/doc/streaming_api.html). 
+
+- Commands available:
+    - `deltas`
 
 ## Installation
 
-`signalk-cli` is published to PyPi at https://pypi.org/project/signalk-cli/
+`signalk-cli` is published to [PyPi](https://pypi.org/project/signalk-cli/)
 
 Python is required to run this, version 3.13 or above. [uv](https://docs.astral.sh/uv/) is the recommended way to install the package ( and can install Python ) but is not required.
 
@@ -53,6 +43,19 @@ 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 / WebAssembly
+
+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("signalk-cli")
+```
+
+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
 
 Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).
@@ -75,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>`.
@@ -118,8 +135,9 @@ 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.0 → signalk_cli-3.0.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "signalk-cli"
-version = "2.2.0"
-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,11 +9,15 @@ keywords = [
     "signalk",
     "sailing",
     "marine",
-    "nmea",
     "boating",
+    "nmea",
+    "dataframe",
+    "cli",
+    "pyarrow",
+    "nanoarrow",
 ]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Environment :: Console",
     "Natural Language :: English",
     "Intended Audience :: Developers",
@@ -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.150.0",
+    "niquests[ws]>=3.21.0; sys_platform == 'emscripten'",
+    "zeroconf>=0.149.16,<0.152.0; sys_platform != 'emscripten'",
 ]
 
 [[project.authors]]
@@ -34,9 +40,10 @@ email = "jrb@rhizomatics.org.uk"
 
 [project.optional-dependencies]
 feather = ["pyarrow>=17.0"]
+arrow = ["pyarrow>=17.0"]
 
 [project.urls]
-Homepage = "https://github.com/rhizomatics/signalk-cli"
+Homepage = "https://signalk-cli.rhizomatics.org.uk"
 Repository = "https://github.com/rhizomatics/signalk-cli"
 Issues = "https://github.com/rhizomatics/signalk-cli/issues"
 Changelog = "https://github.com/rhizomatics/signalk-cli/blob/main/CHANGELOG.md"
@@ -55,8 +62,26 @@ dev = [
     "pytest-xdist",
     "mypy",
     "coverage",
+    "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",
+    "mkdocs-materialx[imaging]",
+    "mkdocs-minify-plugin",
+    "mkdocs-autorefs",
+    "mkdocs-pagetree-plugin",
+    "mkdocs-coverage",
+    "pymdown-extensions",
+    "mkdocs-meta-descriptions-plugin",
+    "pngquant",
+    "mkdocs-htmlproofer-plugin",
+    "mkdocs-llmstxt>=0.5.0,<0.6.0",
+    "mkdocstrings[python]>=1.0.6,<2.0.0",
 ]
 
 [tool.bandit]
@@ -73,7 +98,6 @@ pythonpath = [
     "src",
     ".",
 ]
-asyncio_mode = "auto"
 testpaths = ["tests"]
 norecursedirs = [".git"]
 
@@ -82,7 +106,7 @@ branch = true
 source = ["src"]
 
 [tool.coverage.report]
-fail_under = 0
+fail_under = 90
 
 [tool.coverage.xml]
 output = "cov.xml"
@@ -99,6 +123,19 @@ ignore-words-list = "hass,referer,uint"
 [tool.mypy]
 mypy_path = ["./src"]
 
+[[tool.mypy.overrides]]
+module = [
+    "pyarrow.*",
+    "nanoarrow.*",
+]
+ignore_missing_imports = true
+
+[tool.ty.analysis]
+allowed-unresolved-imports = [
+    "pyarrow",
+    "pyarrow.**",
+]
+
 [tool.uv]
 compile-bytecode = true
 managed = true

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

@@ -1,7 +1,7 @@
 [project]
 name = "signalk-cli"
-version = "2.2.0"
-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,9 +9,11 @@ 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 :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Environment :: Console",
     "Natural Language :: English",
     "Intended Audience :: Developers",
@@ -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.150.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",
@@ -39,12 +47,31 @@ dev = [
     "pytest-xdist",
     "mypy",
     "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=[
+    "properdocs",
+    "mkdocs-materialx[imaging]",
+    "mkdocs-minify-plugin",
+    "mkdocs-autorefs",
+    "mkdocs-pagetree-plugin",
+    "mkdocs-coverage",
+    "pymdown-extensions",
+    "mkdocs-meta-descriptions-plugin",
+    "pngquant",
+    "mkdocs-htmlproofer-plugin",
+    "mkdocs-llmstxt>=0.5.0,<0.6.0",
+    "mkdocstrings[python]>=1.0.6,<2.0.0",
 ]
 
 [project.urls]
-Homepage = "https://github.com/rhizomatics/signalk-cli"
+Homepage = "https://signalk-cli.rhizomatics.org.uk"
 Repository = "https://github.com/rhizomatics/signalk-cli"
 Issues="https://github.com/rhizomatics/signalk-cli/issues"
 Changelog="https://github.com/rhizomatics/signalk-cli/blob/main/CHANGELOG.md"
@@ -67,7 +94,6 @@ line-ending = "auto"
 
 [tool.pytest.ini_options]
 pythonpath = ["src", "."]
-asyncio_mode = "auto"
 testpaths = [
     "tests",
 ]
@@ -81,7 +107,7 @@ branch = true
 source = ["src"]
 
 [tool.coverage.report]
-fail_under=0
+fail_under=90
 
 [tool.coverage.xml]
 output="cov.xml"
@@ -98,6 +124,14 @@ ignore-words-list="hass,referer,uint"
 [tool.mypy]
 mypy_path=["./src"]
 
+[[tool.mypy.overrides]]
+module = ["pyarrow.*", "nanoarrow.*"]
+ignore_missing_imports = true
+
+[tool.ty.analysis]
+# optional `feather` extra
+allowed-unresolved-imports = ["pyarrow", "pyarrow.**"]
+
 [tool.uv]
 compile-bytecode = true
 managed = true

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)