signalk-cli 1.0.0__py3-none-any.whl

signalk_cli/__init__.py

@@ -0,0 +1 @@
+"""signalk_cli — Python clients and CLI for SignalK APIs."""

signalk_cli/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for `python -m signalk` — lists supported API modules."""
+
+print("Supported SignalK APIs:")
+print("  signalk_cli.history  — SignalK v2 History API")
+print()
+print("Usage: python -m signalk_cli.<api> [COMMAND] [OPTIONS]")
+print("       python -m signalk_cli.history --help")

signalk_cli/history/__init__.py

@@ -0,0 +1,31 @@
+"""signalk_cli.history — Python client and CLI for the SignalK v2 History API."""
+
+from .history_api import (
+    HISTORY_BASE,
+    api_error,
+    apply_time_default,
+    expand_paths,
+    fetch_default_provider,
+    fetch_server_paths,
+    get_cached_provider,
+    normalise_host,
+    resolve_provider,
+    save_cached_provider,
+)
+from .output import extract_rows, write_csv, write_feather
+
+__all__ = [
+    "HISTORY_BASE",
+    "api_error",
+    "apply_time_default",
+    "expand_paths",
+    "extract_rows",
+    "fetch_default_provider",
+    "fetch_server_paths",
+    "get_cached_provider",
+    "normalise_host",
+    "resolve_provider",
+    "save_cached_provider",
+    "write_csv",
+    "write_feather",
+]

signalk_cli/history/__main__.py

@@ -0,0 +1,3 @@
+from signalk_cli.history.cli import cli
+
+cli()

signalk_cli/history/cli.py

@@ -0,0 +1,499 @@
+"""Click CLI for the SignalK v2 History API."""
+
+import contextlib
+import io
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlparse
+
+import click
+import niquests
+
+from .history_api import (
+    HISTORY_BASE,
+    api_error,
+    apply_time_default,
+    discover_host,
+    expand_paths,
+    fetch_server_paths,
+    get_cached_host,
+    normalise_host,
+    resolve_provider,
+    save_cached_host,
+)
+from .output import (
+    FEATHER_EXTENSIONS,
+    csv_sink,
+    write_csv,
+    write_csv_wide,
+    write_feather,
+    write_feather_wide,
+)
+
+AGGREGATION_METHODS = [
+    "average",
+    "min",
+    "max",
+    "first",
+    "last",
+    "mid",
+    "middle_index",
+    "sma",
+    "ema",
+]
+
+# ---------------------------------------------------------------------------
+# Shared option decorators
+# ---------------------------------------------------------------------------
+
+
+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 _resolve_host(host: str | None, no_cache: bool = False) -> str:
+    """Return a normalised host URL, discovering via mDNS if none provided."""
+    if host:
+        return normalise_host(host)
+    if not no_cache:
+        cached = get_cached_host()
+        if cached:
+            click.echo(f"Using cached host: {cached}", err=True)
+            return cached
+    click.echo("No host specified — searching for SignalK via mDNS...", err=True)
+    discovered = 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:
+        save_cached_host(discovered)
+    return discovered
+
+
+def _provider_options(f):
+    f = click.option("--no-cache", is_flag=True, help="Ignore cached default provider")(
+        f
+    )
+    f = click.option(
+        "--provider",
+        help="History provider plugin id (default fetched and cached automatically)",
+    )(f)
+    return f
+
+
+def _time_options(f):
+    f = click.option(
+        "--duration",
+        metavar="DURATION",
+        help="Duration: integer seconds or ISO 8601 (e.g. PT15M, 3600)",
+    )(f)
+    f = click.option("--to", metavar="DATETIME", help="End of range (ISO 8601)")(f)
+    f = click.option(
+        "--from", "from_", metavar="DATETIME", help="Start of range (ISO 8601)"
+    )(f)
+    return f
+
+
+def _bare_option(f):
+    return click.option(
+        "--bare",
+        is_flag=True,
+        help="Suppress all informational messages, outputting data only.",
+    )(f)
+
+
+def _stderr_ctx(bare: bool) -> contextlib.AbstractContextManager:
+    return (
+        contextlib.redirect_stderr(io.StringIO()) if bare else contextlib.nullcontext()
+    )
+
+
+def _build_time_params(from_: str | None, to: str | None, duration: str | None) -> dict:
+    p: dict = {}
+    if from_:
+        p["from"] = from_
+    if to:
+        p["to"] = to
+    if duration:
+        p["duration"] = duration
+    return p
+
+
+def _build_path_specs(
+    paths: list[str],
+    aggregation: str | None,
+    samples: int | None,
+    alpha: float | None,
+) -> tuple[str, bool]:
+    """Build the comma-separated paths query param with aggregation suffixes.
+
+    Returns (query_string, wide_mode).  wide_mode is True when no aggregation
+    is given and no path contains an inline ':method' suffix — in that case
+    min/max/average are requested and the output uses wide columns.
+    """
+    has_inline = any(":" in p for p in paths)
+
+    if aggregation:
+        specs = []
+        for path in paths:
+            if ":" in path:
+                specs.append(path)  # inline spec passes through unchanged
+            else:
+                spec = f"{path}:{aggregation}"
+                if aggregation == "sma" and samples is not None:
+                    spec += f":{samples}"
+                elif aggregation == "ema" and alpha is not None:
+                    spec += f":{alpha}"
+                specs.append(spec)
+        return ",".join(specs), False
+
+    if has_inline:
+        return ",".join(paths), False
+
+    # Default: wide mode — fetch min, max and average for each path
+    specs = [f"{p}:{m}" for p in paths for m in ("min", "average", "max")]
+    return ",".join(specs), True
+
+
+# ---------------------------------------------------------------------------
+# CLI group
+# ---------------------------------------------------------------------------
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+def cli():
+    """SignalK v2 history CLI."""
+
+
+# ---------------------------------------------------------------------------
+# query
+# ---------------------------------------------------------------------------
+
+
+@cli.command()
+@click.argument("paths", nargs=-1, required=True, metavar="PATH...")
+@_host_option
+@_time_options
+@click.option(
+    "--resolution",
+    metavar="RESOLUTION",
+    help="Sample window: integer seconds or time expression (1s, 1m, 1h, 1d)",
+)
+@click.option(
+    "--context", "-c", default="vessels.self", show_default=True, help="SignalK context"
+)
+@_provider_options
+@click.option(
+    "--aggregation",
+    "--agg",
+    "aggregation",
+    type=click.Choice(AGGREGATION_METHODS, case_sensitive=False),
+    default=None,
+    help=(
+        "Aggregation method applied to all paths. "
+        "Omit for wide mode (min/max/average columns). "
+        "Paths may also carry an inline ':method[:param]' suffix."
+    ),
+)
+@click.option(
+    "--samples",
+    type=int,
+    default=None,
+    metavar="N",
+    help="Sample count for --aggregation sma",
+)
+@click.option(
+    "--alpha",
+    type=float,
+    default=None,
+    metavar="FLOAT",
+    help="Alpha value (0-1) for --aggregation ema",
+)
+@click.option(
+    "--format",
+    "fmt",
+    default=None,
+    type=click.Choice(["csv", "feather"], case_sensitive=False),
+    help="Output format (default: feather if output extension is .feather/.arrow/.fea, else csv)",
+)
+@click.option("--no-header", is_flag=True, help="Suppress header row (CSV only)")
+@click.option(
+    "--output",
+    "-o",
+    default=None,
+    metavar="FILE",
+    help="Output file (default: signalk-history-<server>-<timestamp>.<ext>, use - for stdout)",
+)
+@click.option(
+    "--stdout",
+    is_flag=True,
+    help="Also print to stdout; when no --output given, stdout only (CSV only)",
+)
+@_bare_option
+def query(
+    paths,
+    host,
+    from_,
+    to,
+    duration,
+    resolution,
+    context,
+    provider,
+    no_cache,
+    aggregation,
+    samples,
+    alpha,
+    fmt,
+    no_header,
+    output,
+    stdout,
+    bare,
+):
+    """Query history and write results as CSV or Feather.
+
+    PATH arguments may be literal SignalK paths, Python regex/glob patterns,
+    or inline path specs with aggregation (e.g. navigation.speedOverGround:sma:5).
+
+    Without --aggregation and without inline specs, the default is wide mode:
+    min/max/average are fetched per path and written as separate columns.
+
+    \b
+    Examples:
+      signalk-history query --host 10.36.10.21 --duration PT1H navigation.speedOverGround
+      signalk-history query --host 10.36.10.21 --duration PT1H --agg sma --samples 5 '*'
+      signalk-history query --host 10.36.10.21 --duration PT1H navigation.speedOverGround:ema:0.2
+      signalk-history query --host 10.36.10.21 --from 2026-05-26T00:00:00Z --to 2026-05-27T00:00:00Z '*'
+    """
+    # --bare: stdout-only with all informational messages suppressed
+    if bare and output is None:
+        output = "-"
+
+    with _stderr_ctx(bare):
+        host = _resolve_host(host, no_cache)
+        base_url = host.rstrip("/") + HISTORY_BASE
+        provider = resolve_provider(host, base_url, provider, no_cache)
+        time_params = apply_time_default(_build_time_params(from_, to, duration))
+
+        # Resolve output path early so we can infer format from extension
+        explicit_file = bool(output and output != "-")
+        if output is None:
+            server_name = urlparse(host).hostname or re.sub(r"[^\w.-]", "_", host)
+            ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+            # Extension determined after format is known; placeholder for now
+            output = f"signalk-history-{server_name}-{ts}"
+            explicit_file = True
+            defer_ext = True
+        else:
+            defer_ext = False
+
+        # Auto-detect format from extension when not explicitly set
+        if fmt is None:
+            if Path(output).suffix.lower() in FEATHER_EXTENSIONS:
+                fmt = "feather"
+            else:
+                fmt = "csv"
+
+        # Now append extension to auto-named file
+        if defer_ext:
+            output += ".feather" if fmt == "feather" else ".csv"
+
+        if fmt == "feather" and (stdout or bare):
+            raise click.UsageError(
+                "--stdout is not supported for feather output (binary format)"
+            )
+
+        click.echo(f"Server:      {host}", err=True)
+        click.echo(f"Provider:    {provider or '(none)'}", err=True)
+        click.echo(f"Context:     {context}", err=True)
+        click.echo(
+            f"From:        {time_params.get('from', '(server default)')}", err=True
+        )
+        click.echo(
+            f"To:          {time_params.get('to', '(server default)')}", err=True
+        )
+        click.echo(
+            f"Duration:    {time_params.get('duration', '(not specified)')}", err=True
+        )
+        click.echo(f"Resolution:  {resolution or '(server default)'}", err=True)
+        click.echo(f"Format:      {fmt}", err=True)
+
+        try:
+            resolved = expand_paths(list(paths), base_url, time_params, provider)
+        except niquests.RequestException as e:
+            click.echo(f"Error resolving paths: {api_error(e)}", err=True)
+            sys.exit(1)
+
+        if not resolved:
+            click.echo("No paths matched — nothing to query.", err=True)
+            sys.exit(1)
+
+        path_query, wide_mode = _build_path_specs(resolved, aggregation, samples, alpha)
+
+        agg_label = aggregation or ("wide (min/max/average)" if wide_mode else "inline")
+        click.echo(f"Aggregation: {agg_label}", err=True)
+
+        params: dict = {**time_params, "paths": path_query, "context": context}
+        if resolution:
+            params["resolution"] = resolution
+        if provider:
+            params["provider"] = provider
+
+        try:
+            resp = niquests.get(f"{base_url}/values", params=params, timeout=60)
+            resp.raise_for_status()
+        except niquests.RequestException as e:
+            click.echo(f"Error fetching history: {api_error(e)}", err=True)
+            sys.exit(1)
+
+        result = resp.json()
+
+        write_to_stdout = stdout or bare or (output == "-")
+        write_to_file = explicit_file
+
+        if fmt == "feather":
+            if wide_mode:
+                row_count, unique_paths = write_feather_wide(result, output)
+            else:
+                row_count, unique_paths = write_feather(result, output)
+        else:
+            file_fh, sink = csv_sink(output, write_to_file, write_to_stdout)
+            try:
+                if wide_mode:
+                    row_count, unique_paths = write_csv_wide(result, sink, no_header)
+                else:
+                    row_count, unique_paths = write_csv(result, sink, no_header)
+            finally:
+                if file_fh:
+                    file_fh.close()
+
+        if write_to_file:
+            click.echo(f"Wrote {output}", err=True)
+        click.echo(
+            f"{row_count} rows, {len(unique_paths)} unique path(s): {', '.join(sorted(unique_paths))}",
+            err=True,
+        )
+
+
+# ---------------------------------------------------------------------------
+# list-paths
+# ---------------------------------------------------------------------------
+
+
+@cli.command("list-paths")
+@_host_option
+@_time_options
+@_provider_options
+@click.option(
+    "--context", "-c", default="vessels.self", show_default=True, help="SignalK context"
+)
+@_bare_option
+def list_paths(host, from_, to, duration, provider, no_cache, context, bare):
+    """List paths that have data for the given time range."""
+    with _stderr_ctx(bare):
+        host = _resolve_host(host, no_cache)
+        base_url = host.rstrip("/") + HISTORY_BASE
+        provider = resolve_provider(host, base_url, provider, no_cache)
+        time_params = apply_time_default(_build_time_params(from_, to, duration))
+
+        click.echo(f"Server:   {host}", err=True)
+        click.echo(f"Provider: {provider or '(none)'}", err=True)
+        click.echo(f"From:     {time_params.get('from', '(server default)')}", err=True)
+        click.echo(f"To:       {time_params.get('to', '(server default)')}", err=True)
+        click.echo(
+            f"Duration: {time_params.get('duration', '(not specified)')}", err=True
+        )
+
+        try:
+            paths = fetch_server_paths(base_url, time_params, provider)
+        except niquests.RequestException as e:
+            click.echo(f"Error fetching paths: {api_error(e)}", err=True)
+            sys.exit(1)
+
+        for path in sorted(paths):
+            click.echo(path)
+
+        click.echo(f"{len(paths)} path(s)", err=True)
+
+
+# ---------------------------------------------------------------------------
+# list-providers
+# ---------------------------------------------------------------------------
+
+
+@cli.command("list-providers")
+@_host_option
+@_bare_option
+def list_providers(host, bare):
+    """List registered history providers."""
+    with _stderr_ctx(bare):
+        host = _resolve_host(host)
+        base_url = host.rstrip("/") + HISTORY_BASE
+        click.echo(f"Server: {host}", err=True)
+
+        try:
+            resp = niquests.get(f"{base_url}/_providers", timeout=10)
+            resp.raise_for_status()
+        except niquests.RequestException as e:
+            click.echo(f"Error fetching providers: {api_error(e)}", err=True)
+            sys.exit(1)
+
+        providers: dict = resp.json()
+        for pid, info in sorted(providers.items()):
+            marker = " (default)" if info.get("isDefault") else ""
+            click.echo(f"{pid}{marker}")
+
+        click.echo(f"{len(providers)} provider(s)", err=True)
+
+
+# ---------------------------------------------------------------------------
+# list-contexts
+# ---------------------------------------------------------------------------
+
+
+@cli.command("list-contexts")
+@_host_option
+@_time_options
+@_provider_options
+@_bare_option
+def list_contexts(host, from_, to, duration, provider, no_cache, bare):
+    """List contexts that have historical data for the given time range."""
+    with _stderr_ctx(bare):
+        host = _resolve_host(host, no_cache)
+        base_url = host.rstrip("/") + HISTORY_BASE
+        provider = resolve_provider(host, base_url, provider, no_cache)
+        time_params = apply_time_default(_build_time_params(from_, to, duration))
+
+        click.echo(f"Server:   {host}", err=True)
+        click.echo(f"Provider: {provider or '(none)'}", err=True)
+        click.echo(f"From:     {time_params.get('from', '(server default)')}", err=True)
+        click.echo(f"To:       {time_params.get('to', '(server default)')}", err=True)
+        click.echo(
+            f"Duration: {time_params.get('duration', '(not specified)')}", err=True
+        )
+
+        params = {**time_params}
+        if provider:
+            params["provider"] = provider
+
+        try:
+            resp = niquests.get(f"{base_url}/contexts", params=params, timeout=30)
+            resp.raise_for_status()
+        except niquests.RequestException as e:
+            click.echo(f"Error fetching contexts: {api_error(e)}", err=True)
+            sys.exit(1)
+
+        contexts: list = resp.json()
+        for ctx in sorted(contexts):
+            click.echo(ctx)
+
+        click.echo(f"{len(contexts)} context(s)", err=True)

signalk_cli/history/history_api.py

@@ -0,0 +1,231 @@
+"""SignalK v2 History API client."""
+
+import fnmatch
+import logging
+import re
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import click
+import niquests
+from zeroconf import ServiceBrowser, ServiceStateChange, Zeroconf
+
+HISTORY_BASE = "/signalk/v2/api/history"
+CACHE_DIR = Path.home() / ".cache" / "signalk-cli"
+_SIGNALK_TYPE = "_signalk-ws._tcp.local."
+_HOST_CACHE_FILE = CACHE_DIR / "host.cache"
+
+
+def get_cached_host() -> str | None:
+    try:
+        if _HOST_CACHE_FILE.exists():
+            return _HOST_CACHE_FILE.read_text().strip() or None
+    except OSError:
+        pass
+    return None
+
+
+def save_cached_host(host: str) -> None:
+    try:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        _HOST_CACHE_FILE.write_text(host)
+    except OSError:
+        pass
+
+
+def discover_host(timeout: float = 5.0) -> str | None:
+    """Browse mDNS for a SignalK server and return its base URL, or None."""
+    found: list[str] = []
+
+    def _on_change(
+        zeroconf: Zeroconf,
+        service_type: str,
+        name: str,
+        state_change: ServiceStateChange,
+    ) -> None:
+        if state_change is not ServiceStateChange.Added:
+            return
+        info = zeroconf.get_service_info(service_type, name)
+        if info is None:
+            return
+        addrs = info.parsed_addresses()
+        if not addrs:
+            return
+        host = f"http://{addrs[0]}:{info.port}"
+        found.append(host)
+
+    zc = Zeroconf()
+    try:
+        ServiceBrowser(zc, _SIGNALK_TYPE, handlers=[_on_change])
+        import time
+
+        deadline = time.monotonic() + timeout
+        while not found and time.monotonic() < deadline:
+            time.sleep(0.1)
+    finally:
+        zc.close()
+
+    return found[0] if found else None
+
+
+def normalise_host(host: str) -> str:
+    """Prepend http:// if the host has no scheme."""
+    if "://" not in host:
+        return f"http://{host}"
+    return host
+
+
+def apply_time_default(time_params: dict) -> dict:
+    """If neither 'from' nor 'duration' is set, default to the hour ending at 'to' (or now)."""
+    if "from" in time_params or "duration" in time_params:
+        return time_params
+    if "to" in time_params:
+        try:
+            to_dt = datetime.fromisoformat(time_params["to"].replace("Z", "+00:00"))
+        except ValueError:
+            to_dt = datetime.now(timezone.utc)
+    else:
+        to_dt = datetime.now(timezone.utc)
+    from_dt = to_dt - timedelta(hours=1)
+    result = {
+        **time_params,
+        "from": from_dt.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "to": to_dt.strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    click.echo(
+        f"No time range specified — defaulting to from={result['from']} to={result['to']}",
+        err=True,
+    )
+    return result
+
+
+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:
+        try:
+            body = resp.json()
+            return body.get("error") or body.get("message") or str(exc)
+        except Exception as e:
+            logging.debug("Error handling API error: %s", e)
+    return str(exc)
+
+
+# ---------------------------------------------------------------------------
+# Provider cache (on-disk, per host)
+# ---------------------------------------------------------------------------
+
+
+def _cache_key(host: str) -> Path:
+    safe = re.sub(r"[^\w.-]", "_", host)
+    return CACHE_DIR / f"{safe}.provider"
+
+
+def get_cached_provider(host: str) -> str | None:
+    try:
+        f = _cache_key(host)
+        if f.exists():
+            return f.read_text().strip() or None
+    except OSError:
+        pass
+    return None
+
+
+def save_cached_provider(host: str, provider_id: str) -> None:
+    try:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        _cache_key(host).write_text(provider_id)
+    except OSError:
+        pass
+
+
+def fetch_default_provider(base_url: str) -> str:
+    resp = niquests.get(f"{base_url}/_providers/_default", timeout=10)
+    resp.raise_for_status()
+    return resp.json()["id"]
+
+
+def resolve_provider(
+    host: str, base_url: str, provider: str | None, no_cache: bool
+) -> str | None:
+    """Return the effective provider id, fetching and caching the default if needed."""
+    if provider:
+        return provider
+    if not no_cache:
+        provider = get_cached_provider(host)
+    if not provider:
+        try:
+            provider = fetch_default_provider(base_url)
+            if not no_cache:
+                save_cached_provider(host, provider)
+        except niquests.HTTPError as e:
+            click.echo(
+                f"Warning: could not fetch default provider: {api_error(e)}", err=True
+            )
+    return provider
+
+
+# ---------------------------------------------------------------------------
+# Path resolution
+# ---------------------------------------------------------------------------
+
+
+def fetch_server_paths(
+    base_url: str, time_params: dict, provider: str | None
+) -> list[str]:
+    """Fetch all paths that have data for the given time range."""
+    params = {k: v for k, v in time_params.items() if v is not None}
+    if provider:
+        params["provider"] = provider
+    resp = niquests.get(f"{base_url}/paths", params=params, timeout=30)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def expand_paths(
+    patterns: list[str],
+    base_url: str,
+    time_params: dict,
+    provider: str | None,
+) -> list[str]:
+    """Expand path patterns to concrete paths.
+
+    Literal paths pass through unchanged. Patterns containing regex
+    metacharacters are matched against the server's /paths endpoint;
+    invalid regex is retried as a glob pattern.
+    """
+    regex_chars = set(r".*+?[](){}|^$\\")
+    literals: list[str] = []
+    regexps: list[str] = []
+
+    for p in patterns:
+        if ":" in p:
+            literals.append(p)  # inline spec — pass through unchanged
+        elif any(c in p for c in regex_chars):
+            regexps.append(p)
+        else:
+            literals.append(p)
+
+    if not regexps:
+        return literals
+
+    click.echo("Resolving patterns against server paths...", err=True)
+    available = fetch_server_paths(base_url, apply_time_default(time_params), provider)
+
+    def _compile(pattern: str) -> re.Pattern:
+        try:
+            return re.compile(pattern)
+        except re.PatternError:
+            click.echo(
+                f"Note: '{pattern}' is not valid regex, treating as glob", err=True
+            )
+            return re.compile(fnmatch.translate(pattern))
+
+    matched: set[str] = set()
+    for pattern, rx in [(p, _compile(p)) for p in regexps]:
+        hits = {path for path in available if rx.search(path)}
+        if not hits:
+            click.echo(f"Warning: '{pattern}' matched no paths", err=True)
+        matched |= hits
+
+    return literals + sorted(matched)

signalk_cli/history/output.py

@@ -0,0 +1,190 @@
+"""CSV and Feather output writers for SignalK data."""
+
+import csv
+import json
+import sys
+from typing import IO, cast
+
+import pyarrow as pa
+import pyarrow.feather as feather
+
+FEATHER_EXTENSIONS = {".feather", ".arrow", ".fea"}
+
+
+class _MultiWriter:
+    """Fans writes out to multiple underlying streams."""
+
+    def __init__(self, *fhs):
+        self._fhs = fhs
+
+    def write(self, s):
+        for fh in self._fhs:
+            fh.write(s)
+
+    def flush(self):
+        for fh in self._fhs:
+            fh.flush()
+
+
+# ---------------------------------------------------------------------------
+# Narrow mode (single value column)
+# ---------------------------------------------------------------------------
+
+
+def extract_rows(result: dict) -> tuple[list, list, list, set[str]]:
+    """Flatten an API result into parallel (timestamps, paths, values, unique_paths) lists."""
+    value_columns = result.get("values", [])
+    data_rows = result.get("data", [])
+    timestamps, paths, values = [], [], []
+    unique_paths: set[str] = set()
+
+    for row in data_rows:
+        if not row:
+            continue
+        timestamp = row[0]
+        for i, col in enumerate(value_columns):
+            path_name = col.get("path", f"col_{i}")
+            value = row[i + 1] if i + 1 < len(row) else None
+            if value is None:
+                continue
+            if isinstance(value, (dict, list)):
+                value = json.dumps(value)
+            elif not isinstance(value, str):
+                value = str(value)
+            timestamps.append(timestamp)
+            paths.append(path_name)
+            values.append(value)
+            unique_paths.add(path_name)
+
+    return timestamps, paths, values, unique_paths
+
+
+def write_csv(result: dict, sink, no_header: bool) -> tuple[int, set[str]]:
+    """Write result as CSV rows (timestamp, path, value). Returns (row_count, unique_paths)."""
+    timestamps, paths, values, unique_paths = extract_rows(result)
+    writer = csv.writer(sink)
+    if not no_header:
+        writer.writerow(["timestamp", "path", "value"])
+    for ts, path, val in zip(timestamps, paths, values):
+        writer.writerow([ts, path, val])
+    return len(timestamps), unique_paths
+
+
+def write_feather(result: dict, output: str) -> tuple[int, set[str]]:
+    """Write result as Feather (timestamp, path, value). Returns (row_count, unique_paths)."""
+    timestamps, paths, values, unique_paths = extract_rows(result)
+    table = pa.table(
+        {
+            "timestamp": pa.array(timestamps, type=pa.string()),
+            "path": pa.array(paths, type=pa.string()),
+            "value": pa.array(values, type=pa.string()),
+        }
+    )
+    feather.write_feather(table, output)
+    return len(timestamps), unique_paths
+
+
+# ---------------------------------------------------------------------------
+# Wide mode (min_value / max_value / avg_value columns)
+# ---------------------------------------------------------------------------
+
+
+def _cell(row: list, col_idx: int) -> str:
+    """Get a string cell value from a data row by 0-based column index (row[0] is timestamp)."""
+    i = col_idx + 1
+    if i >= len(row):
+        return ""
+    v = row[i]
+    if v is None:
+        return ""
+    if isinstance(v, (dict, list)):
+        return json.dumps(v)
+    return str(v)
+
+
+def extract_rows_wide(result: dict) -> tuple[list, list, list, list, list, set[str]]:
+    """Extract rows as (timestamps, paths, min_vals, max_vals, avg_vals, unique_paths)."""
+    value_columns = result.get("values", [])
+    data_rows = result.get("data", [])
+
+    # Build {path: {method: col_idx}} preserving path order
+    path_method_idx: dict[str, dict[str, int]] = {}
+    for i, col in enumerate(value_columns):
+        path = col.get("path", f"col_{i}")
+        method = col.get("method", "")
+        path_method_idx.setdefault(path, {})[method] = i
+
+    ordered_paths = list(path_method_idx)
+    timestamps, paths_out, min_vals, max_vals, avg_vals = [], [], [], [], []
+    unique_paths: set[str] = set()
+
+    for row in data_rows:
+        if not row:
+            continue
+        ts = row[0]
+        for path in ordered_paths:
+            methods = path_method_idx[path]
+            mn = _cell(row, methods["min"]) if "min" in methods else ""
+            av = _cell(row, methods["average"]) if "average" in methods else ""
+            mx = _cell(row, methods["max"]) if "max" in methods else ""
+            if not mn and not av and not mx:
+                continue
+            timestamps.append(ts)
+            paths_out.append(path)
+            min_vals.append(mn)
+            avg_vals.append(av)
+            max_vals.append(mx)
+            unique_paths.add(path)
+
+    return timestamps, paths_out, min_vals, max_vals, avg_vals, unique_paths
+
+
+def write_csv_wide(result: dict, sink, no_header: bool) -> tuple[int, set[str]]:
+    """Write result as CSV (timestamp, path, min_value, max_value, avg_value)."""
+    timestamps, paths, min_vals, max_vals, avg_vals, unique_paths = extract_rows_wide(
+        result
+    )
+    writer = csv.writer(sink)
+    if not no_header:
+        writer.writerow(["timestamp", "path", "min_value", "avg_value", "max_value"])
+    for row in zip(timestamps, paths, min_vals, avg_vals, max_vals):
+        writer.writerow(row)
+    return len(timestamps), unique_paths
+
+
+def write_feather_wide(result: dict, output: str) -> tuple[int, set[str]]:
+    """Write result as Feather (timestamp, path, min_value, max_value, avg_value)."""
+    timestamps, paths, min_vals, max_vals, avg_vals, unique_paths = extract_rows_wide(
+        result
+    )
+    table = pa.table(
+        {
+            "timestamp": pa.array(timestamps, type=pa.string()),
+            "path": pa.array(paths, type=pa.string()),
+            "min_value": pa.array(min_vals, type=pa.string()),
+            "avg_value": pa.array(avg_vals, type=pa.string()),
+            "max_value": pa.array(max_vals, type=pa.string()),
+        }
+    )
+    feather.write_feather(table, output)
+    return len(timestamps), unique_paths
+
+
+# ---------------------------------------------------------------------------
+# Sink helper
+# ---------------------------------------------------------------------------
+
+
+def csv_sink(
+    output: str, write_to_file: bool, write_to_stdout: bool
+) -> tuple[IO[str] | None, _MultiWriter | IO[str]]:
+    """Return (file_handle_or_None, sink) for CSV writing. Caller must close file_handle."""
+    file_fh: IO[str] | None = open(output, "w", newline="") if write_to_file else None
+    sink: _MultiWriter | IO[str]
+    if write_to_file and write_to_stdout:
+        sink = _MultiWriter(cast(IO[str], file_fh), sys.stdout)
+    elif write_to_file:
+        sink = cast(IO[str], file_fh)
+    else:
+        sink = sys.stdout
+    return file_fh, sink

signalk_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: signalk-cli
+Version: 1.0.0
+Summary: Query the SignalK v2 History API and export data as CSV 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 :: 3 - Alpha
+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>=2.28
+Requires-Dist: pyarrow>=17.0
+Requires-Dist: zeroconf>=0.149.16,<0.150.0
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/rhizomatics/signalk-cli
+Project-URL: Repository, https://github.com/rhizomatics/signalk-cli
+Description-Content-Type: text/markdown
+
+# SignalK CLI
+
+Query and explore SignalK APIs from the command line, and export data as CSV or Apache Arrow Feather. 
+
+Presently the [SignalK v2 History API](https://signalk.org/https://demo.signalk.org/documentation/Developing/REST_APIs/History_API.html) is supported.
+
+## Installation
+
+### PyPi
+
+```pip install signalk-cli``` or ```uv pip install signalk-cli```
+
+### Local Copy
+
+Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/rhizomatics/signalk-cli
+cd signalk-cli
+uv sync
+```
+
+## Running
+
+Run via `python -m signalk_cli.history <command>`. 
+
+## Determining SignalK host name
+
+If not host name set as an argument, the CLI will look for a `SIGNALK_HOST` environment variable, and failing that attempt to automatically discover
+the host using mDNS (aka Bonjour).
+
+```bash
+export SIGNALK_HOST=192.168.6.99   # http:// is added automatically if omitted
+```
+
+## Help
+
+Run with no arguments to list available commands:
+
+```
+$ python -m signalk_cli.history
+Usage: signak_cli.history [OPTIONS] COMMAND [ARGS]...
+
+  SignalK v2 history CLI.
+
+Commands:
+  list-contexts   List contexts that have historical data for the given time range.
+  list-paths      List paths that have data for the given time range.
+  list-providers  List registered history providers.
+  query           Query history and write results as CSV or Feather.
+```
+
+## Commands
+
+
+### `query`
+
+Fetch historical values for one or more paths and write to a file (default) or stdout. Aggregation can be controlled in the same way as the History API itself
+or a default form where `min_value`,`avg_value` and `max_value` are returned for every period.
+
+```
+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.
+- **Inline path specs** — `path:method` or `path:method:param`, e.g. `navigation.speedOverGround:sma:5`. These pass through to the server unchanged.
+
+#### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `--host` | `$SIGNALK_HOST` | Server base URL. `http://` added if scheme omitted. |
+| `--from DATETIME` | — | Start of range (ISO 8601, e.g. `2026-05-26T00:00:00Z`) |
+| `--to DATETIME` | now | End of range (ISO 8601) |
+| `--duration DURATION` | — | Duration as seconds (`3600`) or ISO 8601 (`PT1H`, `PT15M`). Combined with `--from` or `--to`, or alone for a window ending now. |
+| `--resolution RESOLUTION` | server default | Sample window size: seconds or time expression (`1s`, `1m`, `1h`, `1d`). |
+| `-c, --context TEXT` | `vessels.self` | SignalK context |
+| `--provider TEXT` | fetched & cached | History provider plugin id |
+| `--no-cache` | — | Ignore the cached default provider |
+| `--aggregation / --agg` | — | Aggregation method: `average`, `min`, `max`, `first`, `last`, `mid`, `middle_index`, `sma`, `ema`. Omit for wide mode (see below). |
+| `--samples N` | server default | Sample count for `--agg sma` |
+| `--alpha FLOAT` | server default | Alpha (0–1) for `--agg ema` |
+| `--format [csv\|feather]` | from extension, else csv | Output format. Auto-detected from `.feather`, `.arrow`, `.fea` extensions. |
+| `--no-header` | — | Suppress the CSV header row |
+| `-o / --output FILE` | auto-named | Output file. Use `-` to write CSV to stdout. |
+| `--stdout` | — | Print CSV to stdout. If `--output` is also given, writes to both. Not supported with feather. |
+| `--bare` | — | Print CSV to stdout with **no informational messages** (server, provider, progress, row count). Ideal for piping to other tools. Implies `--stdout`. Not supported with feather. |
+
+Output files are auto-named `signalk-history-<server>-<timestamp>.<ext>` in the current directory.
+
+If no time range is given, the tool defaults to the hour ending now.
+
+#### Output columns
+
+**Wide mode** (default — no `--aggregation` and no inline specs): fetches `min`, `average`, and `max` for each path and writes them as separate columns:
+
+```
+timestamp, path, min_value, avg_value, max_value
+```
+
+**Narrow mode** (explicit `--aggregation` or inline path specs): single value column:
+
+```
+timestamp, path, value
+```
+
+Structured values (positions, arrays) are JSON-encoded in the value column.
+
+Feather output produces the same columns as Apache Arrow Feather, readable with pandas, Polars, R, pyarrow, etc.
+
+#### Examples
+
+```bash
+# Last hour of speed — wide mode (min/max/avg columns), auto-named CSV
+python -m signalk_cli.history query --host 10.36.10.21 --duration PT1H \
+    navigation.speedOverGround
+
+# Wide mode printed to stdout
+python -m signalk_cli.history query --host 10.36.10.21 --duration PT1H --stdout \
+    navigation.speedOverGround
+
+# Simple moving average (5 samples), narrowed to one value column
+python -m signalk_cli.history query --host 10.36.10.21 --duration PT1H \
+    --agg sma --samples 5 \
+    navigation.speedOverGround
+
+# EMA with alpha 0.2
+python -m signalk_cli.history query --host 10.36.10.21 --duration PT1H \
+    --agg ema --alpha 0.2 \
+    navigation.speedOverGround
+
+# Inline spec — path:method, multiple paths with different methods
+python -m signalk_cli.history query --host 10.36.10.21 --duration PT1H --stdout \
+    'navigation.speedOverGround:max' 'navigation.courseOverGroundTrue:average'
+
+# Multiple literal paths, 1-minute resolution
+python -m signalk_cli.history query --host 10.36.10.21 --duration PT1H --resolution 1m \
+    navigation.speedOverGround navigation.courseOverGroundTrue
+
+# All navigation paths, specific date range, write to named file
+python -m signalk_cli.history query --host 10.36.10.21 \
+    --from 2026-05-26T00:00:00Z --to 2026-05-27T00:00:00Z \
+    --output may26.csv \
+    'navigation\..*'
+
+# Glob wildcard — all paths for the last 30 minutes as Feather
+python -m signalk_cli.history query --host 10.36.10.21 --duration PT30M --format feather '*'
+
+# Extension auto-selects feather format
+python -m signalk_cli.history query --host 10.36.10.21 --duration PT1H \
+    -o out.feather navigation.speedOverGround
+
+# Write to both a file and stdout
+python -m signalk_cli.historyquery --host 10.36.10.21 --duration PT1H \
+    --output out.csv --stdout navigation.speedOverGround
+
+# Duration in seconds, suppress header, pipe to another tool
+python -m signalk_cli.history query --host 10.36.10.21 --duration 3600 --no-header --stdout \
+    navigation.speedOverGround | cut -d, -f1,3
+
+# --bare: pure CSV output, no informational noise — pipe-friendly
+python -m signalk_cli.history query --host 10.36.10.21 --duration PT1H --bare \
+    navigation.speedOverGround | awk -F, 'NR>1 {print $2, $3}'
+
+# Different context
+python -m signalk_cli.history query --host 10.36.10.21 --duration PT1H -c vessels.urn:mrn:imo:mmsi:123456789 \
+    navigation.speedOverGround
+```
+
+---
+
+### `list-paths`
+
+List all SignalK paths that have recorded data in a given time range.
+
+```
+python -m signalk_cli.history list-paths [OPTIONS]
+```
+
+Outputs one path per line to stdout. Defaults to the last hour if no time range is given. Accepts the same `--from`/`--to`/`--duration`, `--provider`/`--no-cache`, `-c/--context`, and `--bare` options as `query`.
+
+```bash
+# Paths recorded in the last hour
+python -m signalk_cli.history list-paths --host 10.36.10.21
+
+# Paths available on a specific day
+python -m signalk_cli.historylist-paths --host 10.36.10.21 \
+    --from 2026-05-26T00:00:00Z --to 2026-05-27T00:00:00Z
+
+# Pipe into grep
+python -m signalk_cli.history list-paths --host 10.36.10.21 --duration PT24H | grep navigation
+```
+
+---
+
+### `list-providers`
+
+List all registered history provider plugins and identify the default. Supports `--bare` to suppress the "Server:" and provider-count lines.
+
+```
+python -m signalk_cli.history list-providers --host 10.36.10.21
+```
+
+Example output:
+
+```
+kip (default)
+signalk-parquet
+2 provider(s)
+```
+
+The default provider is used automatically when `--provider` is not specified on other commands. It is fetched once and cached in `~/.cache/signalk-cli/`.
+
+---
+
+### `list-contexts`
+
+List SignalK contexts (vessels, aircraft, etc.) that have recorded data in a given time range.
+
+```bash
+python -m signalk_cli.history list-contexts [OPTIONS]
+```
+
+Defaults to the last hour if no time range is given.
+
+```bash
+python -m signalk_cli.history list-contexts --host 10.36.10.21
+
+python -m signalk_cli.history list-contexts --host 10.36.10.21 \
+    --from 2026-05-26T00:00:00Z --to 2026-05-27T00:00:00Z
+```
+
+---
+
+## Time range
+
+All commands that query data accept the same three time parameters. At least one of `--from` or `--duration` must be provided (or the tool supplies a one-hour default).
+
+| Parameter | Format | Examples |
+|---|---|---|
+| `--from` | ISO 8601 timestamp | `2026-05-26T00:00:00Z` |
+| `--to` | ISO 8601 timestamp | `2026-05-27T00:00:00Z` |
+| `--duration` | ISO 8601 duration or integer seconds | `PT1H`, `PT15M`, `3600` |
+
+Typical combinations:
+
+- `--duration PT1H` — last hour ending now
+- `--from T --duration PT1H` — hour starting at T
+- `--from T1 --to T2` — explicit range
+- `--duration PT1H --to T` — hour ending at T
+
+## Provider caching
+
+The default history provider is fetched from the server once and cached per host in `~/.cache/signalk-history-cli/`. Pass `--no-cache` to force a fresh lookup, or `--provider <id>` to target a specific provider explicitly.

signalk_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+signalk_cli/__init__.py,sha256=Vl5fsJmHWc1XK1_vlWW6XU1xYHKygFrOn9PpkX-_J9w,63
+signalk_cli/__main__.py,sha256=zIQ0UJ9uUpidMQODg_Soc8MNk2iNRwvFw0ezROBr2fs,293
+signalk_cli/history/__init__.py,sha256=FalcH0mCbX5weJl3QGPAZQSUpmlegEratn2KeRoLmlY,706
+signalk_cli/history/__main__.py,sha256=fHF09yAi8r1luo8JRKHSU6juXvtxF9pedLgDQ_c_x2w,47
+signalk_cli/history/cli.py,sha256=Rrk0Xfb7F0lLMo39yiJkb-yUcE9khTZwDWi0LBGCZ3k,16000
+signalk_cli/history/history_api.py,sha256=7_iD1kZe6ESB0GPxFDN5xsb8h0yHTR4foTLN-CMtq7A,6905
+signalk_cli/history/output.py,sha256=ecBaEJ_OfCoX-Vrsso4APAgNbyibhPr7AGqz3o-ebd8,6753
+signalk_cli-1.0.0.dist-info/WHEEL,sha256=f5fWSvWsg5Knq5GWa6t1nJIug0Tqo69GqAWD_9LbBKw,81
+signalk_cli-1.0.0.dist-info/entry_points.txt,sha256=OeMyoA0iRGQTJcvimkMXnP8Z7iVuFqPKGJK5lGJn9e0,52
+signalk_cli-1.0.0.dist-info/METADATA,sha256=u1_2mDWAgBDpIFqOUyNSrxOHXminzRNS-puuDlhheRU,10453
+signalk_cli-1.0.0.dist-info/RECORD,,

signalk_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.16
+Root-Is-Purelib: true
+Tag: py3-none-any

signalk_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+myproj = signalk_cli.history:cli
+