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

{signalk_cli-2.1.0 → signalk_cli-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalk-cli
-Version: 2.1.0
+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
@@ -486,9 +486,10 @@ interchangeable:
 | `--policy [instant\|ideal\|fixed]` | `ideal` | Per-path subscribe `policy` field; see above |
 | `--period SECONDS` | `60` | Per-path subscribe `period` field, in seconds (converted to ms) |
 | `--min-period SECONDS` | — | Per-path subscribe `minPeriod` field, in seconds (converted to ms); only meaningful with `--policy instant` |
-| `--format [csv\|json\|raw\|feather]` | from extension, else csv | Output format. `json` is JSON Lines (one row object per line, suitable for a live stream). `raw` is the exact delta message text, one per line. `feather` requires `pip install 'signalk-cli[feather]'` and `--output` (cannot stream to stdout). |
+| `--format [csv\|json\|raw\|values\|feather]` | from extension, else csv | Output format. `json` is JSON Lines (one row object per line, suitable for a live stream). `raw` is the exact delta message text, one per line. `values` is the bare value only, one per line — no other columns. `feather` requires `pip install 'signalk-cli[feather]'` and `--output` (cannot stream to stdout). |
 | `--no-header` | — | Suppress the CSV header row |
 | `--include-meta` | — | Also emit rows for `meta` entries (units, description, zones, etc.), not just `values`. Adds a `kind` column (`value`/`meta`) to csv/json/feather output. Ignored for `--format raw`, which always includes meta as-is. |
+| `--source PATTERN` | — | Only include updates whose `$source` matches `PATTERN`. Repeatable, OR'd together. Substring match unless `PATTERN` contains a glob metacharacter (`*`/`?`/`[`), e.g. `--source Teltonika` or `--source '*.GP'`. Client-side, applied after receipt: `csv`/`json`/`values`/`feather` filter per-update; `raw` (whole message, verbatim) passes a message through if *any* of its updates match. |
 | `-o, --output [FILE]` | stdout | Write to a file. Omit the filename (`--output` alone) to auto-name as `signalk-stream-<server>-<timestamp>.<ext>`. Required for `--format feather`. |
 | `-f, --follow` | — | Keep streaming until interrupted (Ctrl-C) or `--count` is reached. Without this, print the next message then exit. |
 | `-n, --count N` | 1 without `--follow`, unlimited with it | Number of delta messages to output |
@@ -500,6 +501,8 @@ interchangeable:
 
 **raw**: the exact delta message JSON as received from the server, one message per line.
 
+**values**: just the `value` column, one per line — no timestamp/context/source/path/kind. Best for piping a single path's readings straight into another tool or script. With `--include-meta`, meta values are interleaved in too, indistinguishable from data values (there's no `kind` column to tell them apart) — generally only useful combined with `--source`/PATH filtering down to one thing.
+
 **feather**: Apache Arrow Feather binary format, same columns as csv/json. Requires `pip install 'signalk-cli[feather]'`. Unlike the other formats, rows are buffered in memory across all received messages and written once the session ends (`--count` reached, or Ctrl-C with `--follow`) — cannot be streamed to stdout.
 
 #### Examples
@@ -536,6 +539,13 @@ python -m signalk_cli.stream deltas --host 10.36.10.21 --count 500 --format feat
 
 # Capture until Ctrl-C to a named Feather file
 python -m signalk_cli.stream deltas --host 10.36.10.21 --follow -o capture.feather 'navigation.*'
+
+# Only updates from one sensor (substring match on $source)
+python -m signalk_cli.stream deltas --host 10.36.10.21 --follow --source Teltonika 'navigation.*'
+
+# Bare speed values from one sensor, piped straight into another tool
+python -m signalk_cli.stream deltas --host 10.36.10.21 --follow --format values \
+    --source Teltonika --bare navigation.speedOverGround
 ```
 
 ---

{signalk_cli-2.1.0 → signalk_cli-2.2.0}/README.md

@@ -458,9 +458,10 @@ interchangeable:
 | `--policy [instant\|ideal\|fixed]` | `ideal` | Per-path subscribe `policy` field; see above |
 | `--period SECONDS` | `60` | Per-path subscribe `period` field, in seconds (converted to ms) |
 | `--min-period SECONDS` | — | Per-path subscribe `minPeriod` field, in seconds (converted to ms); only meaningful with `--policy instant` |
-| `--format [csv\|json\|raw\|feather]` | from extension, else csv | Output format. `json` is JSON Lines (one row object per line, suitable for a live stream). `raw` is the exact delta message text, one per line. `feather` requires `pip install 'signalk-cli[feather]'` and `--output` (cannot stream to stdout). |
+| `--format [csv\|json\|raw\|values\|feather]` | from extension, else csv | Output format. `json` is JSON Lines (one row object per line, suitable for a live stream). `raw` is the exact delta message text, one per line. `values` is the bare value only, one per line — no other columns. `feather` requires `pip install 'signalk-cli[feather]'` and `--output` (cannot stream to stdout). |
 | `--no-header` | — | Suppress the CSV header row |
 | `--include-meta` | — | Also emit rows for `meta` entries (units, description, zones, etc.), not just `values`. Adds a `kind` column (`value`/`meta`) to csv/json/feather output. Ignored for `--format raw`, which always includes meta as-is. |
+| `--source PATTERN` | — | Only include updates whose `$source` matches `PATTERN`. Repeatable, OR'd together. Substring match unless `PATTERN` contains a glob metacharacter (`*`/`?`/`[`), e.g. `--source Teltonika` or `--source '*.GP'`. Client-side, applied after receipt: `csv`/`json`/`values`/`feather` filter per-update; `raw` (whole message, verbatim) passes a message through if *any* of its updates match. |
 | `-o, --output [FILE]` | stdout | Write to a file. Omit the filename (`--output` alone) to auto-name as `signalk-stream-<server>-<timestamp>.<ext>`. Required for `--format feather`. |
 | `-f, --follow` | — | Keep streaming until interrupted (Ctrl-C) or `--count` is reached. Without this, print the next message then exit. |
 | `-n, --count N` | 1 without `--follow`, unlimited with it | Number of delta messages to output |
@@ -472,6 +473,8 @@ interchangeable:
 
 **raw**: the exact delta message JSON as received from the server, one message per line.
 
+**values**: just the `value` column, one per line — no timestamp/context/source/path/kind. Best for piping a single path's readings straight into another tool or script. With `--include-meta`, meta values are interleaved in too, indistinguishable from data values (there's no `kind` column to tell them apart) — generally only useful combined with `--source`/PATH filtering down to one thing.
+
 **feather**: Apache Arrow Feather binary format, same columns as csv/json. Requires `pip install 'signalk-cli[feather]'`. Unlike the other formats, rows are buffered in memory across all received messages and written once the session ends (`--count` reached, or Ctrl-C with `--follow`) — cannot be streamed to stdout.
 
 #### Examples
@@ -508,6 +511,13 @@ python -m signalk_cli.stream deltas --host 10.36.10.21 --count 500 --format feat
 
 # Capture until Ctrl-C to a named Feather file
 python -m signalk_cli.stream deltas --host 10.36.10.21 --follow -o capture.feather 'navigation.*'
+
+# Only updates from one sensor (substring match on $source)
+python -m signalk_cli.stream deltas --host 10.36.10.21 --follow --source Teltonika 'navigation.*'
+
+# Bare speed values from one sensor, piped straight into another tool
+python -m signalk_cli.stream deltas --host 10.36.10.21 --follow --format values \
+    --source Teltonika --bare navigation.speedOverGround
 ```
 
 ---

{signalk_cli-2.1.0 → signalk_cli-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "signalk-cli"
-version = "2.1.0"
+version = "2.2.0"
 description = "Query SignalK v2 APIs and export data as CSV, JSON or Apache Arrow Feather"
 readme = "README.md"
 requires-python = ">=3.13"

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

@@ -1,6 +1,6 @@
 [project]
 name = "signalk-cli"
-version = "2.1.0"
+version = "2.2.0"
 description = "Query SignalK v2 APIs and export data as CSV, JSON or Apache Arrow Feather"
 readme = "README.md"
 requires-python = ">=3.13"

{signalk_cli-2.1.0 → signalk_cli-2.2.0}/src/signalk_cli/stream/cli.py

@@ -13,11 +13,13 @@ import niquests
 from ..net import api_error, bare_option, host_option, resolve_host, stderr_ctx
 from .output import (
     FEATHER_EXTENSIONS,
+    delta_matches_source,
     extract_delta_rows,
     write_csv_delta,
     write_csv_header,
     write_feather_rows,
     write_json_delta,
+    write_values_delta,
 )
 from .stream_api import (
     SUBSCRIBE_POLICIES,
@@ -103,10 +105,13 @@ def cli():
     "--format",
     "fmt",
     default=None,
-    type=click.Choice(["csv", "json", "raw", "feather"], case_sensitive=False),
+    type=click.Choice(
+        ["csv", "json", "raw", "feather", "values"], case_sensitive=False
+    ),
     help="Output format (default: inferred from --output extension, else csv). "
     "json is JSON Lines (one row object per line). raw is the exact delta "
-    "message text, one per line. feather requires "
+    "message text, one per line. values is the bare value only, one per "
+    "line — no timestamp/context/source/path/kind columns. feather requires "
     "pip install 'signalk-cli[feather]' and --output (cannot stream to stdout).",
 )
 @click.option("--no-header", is_flag=True, help="Suppress header row (CSV only)")
@@ -117,6 +122,19 @@ def cli():
     "not just 'values'. Adds a 'kind' column (value/meta) to csv/json/feather "
     "output. Ignored for --format raw, which always includes meta as-is.",
 )
+@click.option(
+    "--source",
+    "source",
+    multiple=True,
+    metavar="PATTERN",
+    help="Only include updates whose $source matches PATTERN. Repeatable "
+    "(OR'd together). PATTERN is a substring match unless it contains a "
+    "glob metacharacter (*/?/[), in which case it's matched as a glob, "
+    "e.g. --source Teltonika or --source '*.GP'. Filtering is client-side, "
+    "applied after receipt — for --format raw (whole message, verbatim) a "
+    "message passes if ANY of its updates match; other formats filter "
+    "per-update.",
+)
 @click.option(
     "--output",
     "-o",
@@ -156,6 +174,7 @@ def deltas(
     fmt,
     no_header,
     include_meta,
+    source,
     output,
     follow,
     count,
@@ -164,7 +183,8 @@ def deltas(
     """Stream live delta updates from the SignalK v1 Streaming API.
 
     Connects via WebSocket and prints delta messages as they arrive, in
-    csv, json (JSON Lines), raw, or Feather format.
+    csv, json (JSON Lines), raw, values (bare value only), or Feather
+    format.
 
     Always sends an explicit subscribe message for --context, covering
     PATH arguments if given, otherwise every path ('*'). PATH arguments
@@ -196,6 +216,10 @@ def deltas(
 
       # Capture 100 messages to a Feather file (requires signalk-cli[feather])
       signalk_cli.stream deltas --host 10.36.10.21 --count 100 -o capture.feather
+
+      # Bare speed values from one sensor, piped straight into another tool
+      signalk_cli.stream deltas --host 10.36.10.21 --follow --format values \\
+          --source Teltonika --bare navigation.speedOverGround
     """
     with stderr_ctx(bare):
         host = resolve_host(host, no_cache)
@@ -224,6 +248,8 @@ def deltas(
                 if fmt == "feather"
                 else ".json"
                 if fmt in ("json", "raw")
+                else ".txt"
+                if fmt == "values"
                 else ".csv"
             )
             output = f"signalk-stream-{server_name}-{ts}{ext}"
@@ -280,20 +306,29 @@ def deltas(
                 message_count += 1
                 if fmt == "feather":
                     feather_rows.extend(
-                        extract_delta_rows(delta, include_meta=include_meta)
+                        extract_delta_rows(
+                            delta, include_meta=include_meta, sources=source
+                        )
                     )
                     row_total = len(feather_rows)
                 elif fmt == "raw":
-                    click.echo(raw, file=sink)
+                    if delta_matches_source(delta, source):
+                        click.echo(raw, file=sink)
                 elif fmt == "json":
                     row_total += write_json_delta(
-                        delta, sink, include_meta=include_meta
+                        delta, sink, include_meta=include_meta, sources=source
+                    )
+                elif fmt == "values":
+                    row_total += write_values_delta(
+                        delta, sink, include_meta=include_meta, sources=source
                     )
                 else:
                     if not header_written and not no_header:
                         write_csv_header(sink, include_meta=include_meta)
                         header_written = True
-                    row_total += write_csv_delta(delta, sink, include_meta=include_meta)
+                    row_total += write_csv_delta(
+                        delta, sink, include_meta=include_meta, sources=source
+                    )
         except KeyboardInterrupt:
             pass
         except niquests.RequestException as e:

{signalk_cli-2.1.0 → signalk_cli-2.2.0}/src/signalk_cli/stream/output.py

@@ -1,6 +1,7 @@
 """Row extraction and CSV/JSON/Feather writers for SignalK delta messages."""
 
 import csv
+import fnmatch
 import json
 from typing import IO
 
@@ -15,8 +16,42 @@ def _normalize_value(value: object) -> str:
     return str(value)
 
 
+def _update_source(update: dict) -> str:
+    return update.get("$source") or json.dumps(update.get("source", {}))
+
+
+def source_matches(source: str, patterns: tuple[str, ...]) -> bool:
+    """Match a `$source` string against `--source` filter patterns (OR'd).
+
+    No patterns means no filtering (always matches). A pattern containing
+    glob metacharacters (`*`/`?`/`[`) is matched as-is via `fnmatch`;
+    otherwise it's treated as a substring match, e.g. "Teltonika" matches
+    the source "Teltonika.GP".
+    """
+    if not patterns:
+        return True
+    return any(
+        fnmatch.fnmatch(source, p if any(c in p for c in "*?[") else f"*{p}*")
+        for p in patterns
+    )
+
+
+def delta_matches_source(delta: dict, patterns: tuple[str, ...]) -> bool:
+    """True if any update in the delta has a `$source` matching `patterns`.
+
+    Used for `--format raw`, which echoes the whole message verbatim and so
+    can only filter at message granularity, not per-update.
+    """
+    if not patterns:
+        return True
+    return any(
+        source_matches(_update_source(update), patterns)
+        for update in delta.get("updates", [])
+    )
+
+
 def extract_delta_rows(
-    delta: dict, *, include_meta: bool = False
+    delta: dict, *, include_meta: bool = False, sources: tuple[str, ...] = ()
 ) -> list[tuple[str, ...]]:
     """Flatten a single delta message into rows.
 
@@ -26,12 +61,18 @@ def extract_delta_rows(
     update's "meta" entries are included too — per the Streaming API spec,
     "meta" entries have the same path/value shape but "value" is a metadata
     object (units, description, zones, etc.), not a telemetry reading.
+
+    `sources`, if given, drops entire updates whose `$source` doesn't match
+    any pattern (see `source_matches`) — filtering is per-update, since
+    that's the granularity at which SignalK attaches a source.
     """
     context = delta.get("context", "")
     rows: list[tuple[str, ...]] = []
     for update in delta.get("updates", []):
+        source = _update_source(update)
+        if not source_matches(source, sources):
+            continue
         timestamp = update.get("timestamp", "")
-        source = update.get("$source") or json.dumps(update.get("source", {}))
         for entry in update.get("values", []):
             path = entry.get("path", "")
             value = _normalize_value(entry.get("value"))
@@ -60,9 +101,15 @@ def write_csv_header(sink: IO[str], *, include_meta: bool = False) -> None:
     sink.flush()
 
 
-def write_csv_delta(delta: dict, sink: IO[str], *, include_meta: bool = False) -> int:
+def write_csv_delta(
+    delta: dict,
+    sink: IO[str],
+    *,
+    include_meta: bool = False,
+    sources: tuple[str, ...] = (),
+) -> int:
     """Write one delta's rows as CSV lines. Returns the number of rows written."""
-    rows = extract_delta_rows(delta, include_meta=include_meta)
+    rows = extract_delta_rows(delta, include_meta=include_meta, sources=sources)
     writer = csv.writer(sink)
     for row in rows:
         writer.writerow(row)
@@ -70,9 +117,15 @@ def write_csv_delta(delta: dict, sink: IO[str], *, include_meta: bool = False) -
     return len(rows)
 
 
-def write_json_delta(delta: dict, sink: IO[str], *, include_meta: bool = False) -> int:
+def write_json_delta(
+    delta: dict,
+    sink: IO[str],
+    *,
+    include_meta: bool = False,
+    sources: tuple[str, ...] = (),
+) -> int:
     """Write one delta's rows as JSON Lines (one row object per line). Returns row count."""
-    rows = extract_delta_rows(delta, include_meta=include_meta)
+    rows = extract_delta_rows(delta, include_meta=include_meta, sources=sources)
     columns = _columns(include_meta)
     for row in rows:
         sink.write(json.dumps(dict(zip(columns, row))))
@@ -81,6 +134,26 @@ def write_json_delta(delta: dict, sink: IO[str], *, include_meta: bool = False)
     return len(rows)
 
 
+def write_values_delta(
+    delta: dict,
+    sink: IO[str],
+    *,
+    include_meta: bool = False,
+    sources: tuple[str, ...] = (),
+) -> int:
+    """Write one delta's bare values, one per line — no other columns.
+
+    For `--format values`: useful for piping a single path's readings
+    straight into another tool/script. Returns the number of values written.
+    """
+    rows = extract_delta_rows(delta, include_meta=include_meta, sources=sources)
+    for row in rows:
+        sink.write(row[-1])
+        sink.write("\n")
+    sink.flush()
+    return len(rows)
+
+
 def write_feather_rows(
     rows: list[tuple[str, ...]], output: str, *, include_meta: bool = False
 ) -> int: