devicectl-core 0.1.0__py3-none-any.whl

devicectl/__init__.py

@@ -0,0 +1,18 @@
+"""Shared building blocks for single-device control programs.
+
+Two programs -- one for a wallbox on the network, one for a battery
+management system on a serial bus -- turned out to be the same program with
+different protocols underneath: a subcommand table over argparse, a
+serialising worker that owns the one connection, an event stream to a
+build-free browser UI, and a progress protocol that lets one code path drive
+both a terminal and that UI.  Everything here is the part that was the same.
+
+Nothing in this package knows what a device is.  It has no required runtime
+dependencies and imports nothing outside the standard library, so the
+protocol layer -- ``httpx``, ``pyserial``, whatever the next one needs --
+stays in the program that speaks it.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

devicectl/cli/__init__.py

@@ -0,0 +1 @@
+"""The command-line half: the subcommand table, exit codes and terminal output."""

devicectl/cli/command.py

@@ -0,0 +1,95 @@
+"""What one subcommand is: a function to run, and what it needs open first.
+
+The alternative -- a chain of ``if args.command == ...`` -- hid three
+different things in the same shape: which function runs, whether the link to
+the device is needed at all, and whether it has to be ready to use.  Two
+commands in thirty need less than the rest, and in a chain that is a special
+case buried at the top; here it is a field.
+
+The web API's ``ROUTES`` table is the same idea for the same reason.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable
+
+# Every handler takes the same two arguments whether it wants them or not, so
+# the table can stay one shape.  What arrives first depends on the Need the
+# command declares -- None, or whatever the program opened -- and each handler
+# annotates the one it actually takes.  No single signature describes all
+# three, so this one leaves the first parameter open rather than pretending
+# otherwise.
+Handler = Callable[[Any, argparse.Namespace], int]
+
+
+class Need(Enum):
+    """What has to be open before a command's handler runs.
+
+    Three levels, because every program here has found it needs exactly
+    three.  What they *mean* is the program's own: for a charger the link is
+    a connection and ready is a logged-in session; for a serial bus the link
+    is the open port and ready is one addressed unit on it.
+    """
+
+    NOTHING = "nothing"
+    """No device at all: browsing for one, or starting the web server."""
+
+    LINK = "link"
+    """The link is open, but nothing has been selected or authenticated on it."""
+
+    READY = "ready"
+    """Open, and usable: logged in, or addressed.  Almost everything."""
+
+
+@dataclass(frozen=True)
+class Command:
+    """One subcommand."""
+
+    run: Handler
+    needs: Need = Need.READY
+    per_action: Mapping[str, Need] = field(default_factory=dict)
+    """Actions of this command that need less than the command itself."""
+
+    default_action: str = ""
+    """What this command does when its ACTION is left out.
+
+    Declared here rather than in a table beside the parser, because a
+    separate table has to be kept in step with this one by hand and fails
+    silently when it is not: a default named for a command that no longer
+    exists never fires, and a command that grew actions never gets one.
+
+    Only an action that needs no further input and changes nothing belongs
+    here.  A command whose every action writes -- setting a password, say --
+    deliberately has none, so typing the bare command is a usage error
+    rather than a surprise.
+    """
+
+    fans_out: bool | Sequence[str] = False
+    """Whether this command may be run over several devices at once.
+
+    ``True`` for a command that only reads, a list of action names for one
+    where only some of its actions do (``fans_out=("show",)``), and the
+    default for everything else.  Only reads fan out: "do this to every
+    device I own" is not a thing to type by accident, and each of them wants
+    its own diff and its own confirmation anyway.
+
+    A program whose devices are addressed one at a time reads this before it
+    opens anything; :mod:`devicectl.cli.fanout` is what it does afterwards.
+    """
+
+    def need(self, action: str | None) -> Need:
+        """Return what this command needs open, given the ACTION it was called with."""
+        return self.per_action.get(action or "", self.needs)
+
+    def fans_out_for(self, action: str | None) -> bool:
+        """Whether this command fans out, given the ACTION it was called with."""
+        if isinstance(self.fans_out, bool):
+            return self.fans_out
+        return (action or "") in self.fans_out
+
+
+__all__ = ["Command", "Handler", "Need"]

devicectl/cli/exits.py

@@ -0,0 +1,32 @@
+"""The exit codes every program here shares.
+
+Zero is success, 130 is the shell's convention for Ctrl-C, and 1 is
+everything else -- nothing at that address, no such setting, a value the
+device refused.  There is deliberately no code per failure kind; the message
+on stderr says which.
+
+A firmware upgrade is the usual exception.  It is the one command likely to
+be run unattended across a fleet, where "this image is for another model"
+and "it never came back" call for different reactions, so the two weights
+that mean the same thing everywhere live here and a program adds whatever
+further codes its own upgrade path can end in.
+"""
+
+from __future__ import annotations
+
+EXIT_OK = 0
+EXIT_ERROR = 1  # generic failure: nothing found, comms error, invalid input
+EXIT_INTERRUPTED = 130  # Ctrl-C, by the usual shell convention
+
+# --- firmware ------------------------------------------------------------------------------
+
+EXIT_INCOMPATIBLE = 2  # the image is not for this device
+EXIT_UPDATE_FAILED = 4  # sent, but the install reached no good state
+
+__all__ = [
+    "EXIT_ERROR",
+    "EXIT_INCOMPATIBLE",
+    "EXIT_INTERRUPTED",
+    "EXIT_OK",
+    "EXIT_UPDATE_FAILED",
+]

devicectl/cli/fanout.py

@@ -0,0 +1,142 @@
+"""Running one read over every device the command line named.
+
+One device is the ordinary case and stays exactly as it was: no heading, no
+wrapper, the same bytes on standard output.  Several is the interesting one.
+A handler prints its own output, which is right for one and wrong for four:
+``--json`` over four devices should answer with one document keyed by
+device, not with four documents concatenated into something no parser will
+take.  So the printing is diverted for the duration, and the handler never
+learns that it fanned out.
+
+Only reads fan out.  A command that reconfigures or restarts a device keeps
+its single target, because "do this to every one I own" is not a thing to
+type by accident, and each of them wants its own diff and its own
+confirmation anyway.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Callable, TypeVar
+
+from devicectl.cli.exits import EXIT_ERROR, EXIT_OK
+from devicectl.cli.main import Translator
+from devicectl.cli.output import collect_json, error, render_json, stop_collecting
+from devicectl.errors import DeviceError
+
+DeviceT = TypeVar("DeviceT")
+
+# How wide the heading rule is drawn over a section.
+HEADING_WIDTH = 56
+
+
+def parse_range(text: str | int, limit: range, *, what: str = "id") -> list[int] | None:
+    """Parse one address, a comma list, a range, or ``all``.
+
+    ``None`` means "every address there is", which usually cannot be
+    resolved until something is open, so it is left for the caller to sweep
+    for.  Order is kept and repeats are dropped, so ``2,1,2`` reads two
+    devices in the order asked for.
+    """
+    if isinstance(text, int):  # a caller that already had a number
+        text = str(text)
+    text = text.strip().lower()
+    if text in ("all", "*"):
+        return None
+    out: list[int] = []
+    for part in text.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        if "-" in part[1:]:  # a range, e.g. 1-4; a leading - is not one
+            low, _, high = part.partition("-")
+            out.extend(range(int(low), int(high) + 1))
+        else:
+            out.append(int(part))
+    if not out:
+        raise ValueError(f"cannot read --{what} {text!r}")
+    for value in out:
+        if value not in limit:
+            raise ValueError(
+                f"--{what} {value} is outside {limit.start}..{limit.stop - 1}"
+            )
+    return list(dict.fromkeys(out))
+
+
+def fan_out(
+    devices: Sequence[DeviceT],
+    one: Callable[[DeviceT], int],
+    *,
+    key: Callable[[DeviceT], str],
+    heading: Callable[[DeviceT], str],
+    as_json: bool = False,
+    translate: Translator | None = None,
+) -> int:
+    """Run ``one(device)`` over each device and combine the results.
+
+    With one device this is exactly what the handler did before.  With
+    several, each section gets a heading, and ``--json`` comes back as one
+    object keyed by ``key`` rather than as several documents in a row.
+
+    The exit code is the first failure, so a bank with one silent device
+    says so, and the others are still read.  ``translate`` says what a
+    program's own transport failures mean, exactly as it does for
+    :func:`devicectl.cli.main.run`: over several devices they have to be
+    caught here instead, or the first charger that does not answer would
+    take the other three with it.
+    """
+    if not devices:
+        return EXIT_OK
+    if len(devices) == 1:
+        return one(devices[0])
+    combined: dict[str, Any] = {}
+    worst = EXIT_OK
+    for index, device in enumerate(devices):
+        if as_json:
+            collected = collect_json()
+            try:
+                code = _guarded(one, device, heading(device), translate)
+            finally:
+                stop_collecting()
+            combined[key(device)] = (
+                collected[0] if len(collected) == 1 else list(collected)
+            )
+        else:
+            if index:
+                print()
+            title = heading(device)
+            print(f"=== {title} " + "=" * max(0, HEADING_WIDTH - len(title)))
+            print()
+            code = _guarded(one, device, title, translate)
+        worst = worst or code
+    if as_json:
+        render_json(combined)
+    return worst
+
+
+def _guarded(
+    one: Callable[[Any], int],
+    device: Any,
+    title: str,
+    translate: Translator | None = None,
+) -> int:
+    """Run one device's read, turning a silent device into a message and a code.
+
+    Anything neither the shared error nor the program's ``translate``
+    recognises is left to propagate: a bug is a bug on four devices too, and
+    it deserves its traceback rather than a heading and a 1.
+    """
+    try:
+        return one(device)
+    except DeviceError as exc:
+        error(f"{title}: {exc}")
+        return EXIT_ERROR
+    except Exception as exc:
+        message = translate(exc) if translate is not None else None
+        if message is None:
+            raise
+        error(f"{title}: {message}")
+        return EXIT_ERROR
+
+
+__all__ = ["fan_out", "parse_range"]

devicectl/cli/main.py

@@ -0,0 +1,69 @@
+"""Turning an expected failure into one line on stderr and an exit code.
+
+Every module raises its own subclass of
+:class:`~devicectl.errors.DeviceError`, and none of them needs a handler of
+its own: they all end the same way.  So a program's ``main`` is its dispatch
+wrapped in :func:`run`, which is the only place a failure is printed.
+
+A program that has a transport of its own -- HTTP, a serial port -- passes a
+``translate`` to say what its exceptions mean, because "cannot reach the
+charger: [Errno 111]" is a better line than the ``OSError`` underneath it.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Callable
+
+from devicectl.cli.exits import EXIT_ERROR, EXIT_INTERRUPTED
+from devicectl.cli.output import error
+from devicectl.errors import DeviceError
+
+Translator = Callable[[BaseException], str | None]
+
+
+def run(
+    dispatch: Callable[[], int],
+    *,
+    translate: Translator | None = None,
+    interrupted: str = "Interrupted.",
+) -> int:
+    """Run ``dispatch``, reporting an expected failure rather than raising it.
+
+    ``translate`` is asked first and returns the line to print, or ``None``
+    to let the shared handling decide.  Anything neither recognises is left
+    to propagate: an unexpected exception is a bug, and a bug deserves its
+    traceback.
+    """
+    try:
+        return dispatch()
+    except KeyboardInterrupt:
+        # A newline first: Ctrl+C echoes at the cursor, wherever a progress
+        # line had left it.
+        print(f"\n{interrupted}", file=sys.stderr)
+        return EXIT_INTERRUPTED
+    except BaseException as exc:
+        message = translate(exc) if translate is not None else None
+        if message is None:
+            message = _message_for(exc)
+        if message is None:
+            raise
+        error(message)
+        return EXIT_ERROR
+
+
+def _message_for(exc: BaseException) -> str | None:
+    """Return the line for a failure any program of this kind can have."""
+    if isinstance(exc, DeviceError):
+        return str(exc)
+    if isinstance(exc, KeyError):
+        # Something named on the command line that does not exist.  A
+        # KeyError's str() is the repr of its key, which reads as a quoted
+        # word rather than as a sentence, so unwrap it.
+        return str(exc.args[0]) if exc.args else str(exc)
+    if isinstance(exc, OSError):
+        return str(exc)
+    return None
+
+
+__all__ = ["Translator", "run"]

devicectl/cli/output.py

@@ -0,0 +1,299 @@
+"""Printing: tables, label/value blocks, the one timestamp format, the one prompt.
+
+Every command that shows something goes through here, so column widths, JSON
+shape and clock formatting stay the same across dozens of commands without
+each one deciding for itself.  :func:`confirm` is here for the same reason:
+the commands that can wreck something should all ask about it the same way.
+
+Messages on stderr open with ``error:`` when the command failed, ``warning:``
+when it carried on regardless, and ``note:`` for an advisory -- so a script
+reading stderr can tell the three apart without parsing prose.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import unicodedata
+from pathlib import Path
+from typing import Any, Callable
+
+from devicectl.cli.exits import EXIT_ERROR, EXIT_OK
+
+# How clock readings are printed: seconds matter, sub-seconds do not.
+CLOCK_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+# Longest a value may be before the table view abbreviates it.
+TABLE_VALUE_MAX = 40
+
+# The answers that mean yes.  Anything else, including silence, is no.
+YES = ("y", "yes")
+
+# The character widths `unicodedata` calls double.
+WIDE = ("W", "F")
+
+
+def confirm(question: str) -> bool:
+    """Ask a yes/no question; anything but an explicit yes is a no.
+
+    End-of-file counts as a no, so a command left to run unattended stops
+    rather than raising at the prompt.  Every command that asks also takes
+    ``-y`` to skip the question; declining exits non-zero, because nothing
+    that was asked for was done.
+    """
+    try:
+        return input(f"{question} [y/N] ").strip().lower() in YES
+    except EOFError:
+        return False
+
+
+def display_width(text: str) -> int:
+    """Return how many terminal columns ``text`` occupies.
+
+    A CJK character takes two columns while ``len`` counts it as one, so a
+    table padded by ``len`` comes out visibly ragged wherever one appears --
+    and a recovered protocol table is exactly where one appears.
+    """
+    return sum(2 if unicodedata.east_asian_width(c) in WIDE else 1 for c in text)
+
+
+def _pad(text: str, width: int) -> str:
+    """Left-align ``text`` in ``width`` terminal columns."""
+    return text + " " * max(0, width - display_width(text))
+
+
+def print_table(headers: list[str], rows: list[list[str]]) -> None:
+    """Print a left-aligned table with columns sized to their widest cell."""
+    if not rows:
+        return
+    widths = [display_width(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], display_width(cell))
+    print("  ".join(_pad(h, widths[i]) for i, h in enumerate(headers)).rstrip())
+    for row in rows:
+        print("  ".join(_pad(c, widths[i]) for i, c in enumerate(row)).rstrip())
+
+
+def print_rows(title: str, rows: list[tuple[str, str]]) -> None:
+    """Print a titled block of aligned label/value lines."""
+    if not rows:
+        return
+    if title:
+        print(f"{title}:\n")
+    width = max(display_width(label) for label, _ in rows)
+    for label, value in rows:
+        print(f"  {_pad(label, width)}  {value}")
+
+
+def print_sections(
+    title: str, sections: list[tuple[str, list[tuple[str, str]]]]
+) -> None:
+    """Print a titled block of label/value lines under headings.
+
+    For a reading a web page splits into cards: the headings are the cards'
+    titles, so a row can carry the card's short name for it ("Average" under
+    *Cells*) and still say what it is.  The values line up across sections,
+    so the block reads as one list.  An empty section is left out.
+    """
+    sections = [(heading, rows) for heading, rows in sections if rows]
+    if not sections:
+        return
+    if title:
+        print(f"{title}:")
+    width = max(display_width(label) for _, rows in sections for label, _ in rows)
+    for heading, rows in sections:
+        print(f"\n  {heading}")
+        for label, value in rows:
+            print(f"    {_pad(label, width)}  {value}")
+
+
+# Where a --json document goes while a command is running over several
+# devices.
+#
+# A handler prints its own JSON, which is right for one device and wrong for
+# four: a fan-out should answer with one document keyed by device, not with
+# four documents concatenated into something no parser will take.
+# :mod:`devicectl.cli.fanout` redirects the printing here for the duration,
+# so every --json command fans out without each of them learning how.
+_collector: list[Any] | None = None
+
+
+def collect_json() -> list[Any]:
+    """Divert :func:`print_json` into a list until :func:`stop_collecting`."""
+    global _collector
+    _collector = []
+    return _collector
+
+
+def stop_collecting() -> None:
+    """Send :func:`print_json` back to standard output."""
+    global _collector
+    _collector = None
+
+
+def print_json(doc: Any) -> None:
+    """Print a document as the one JSON shape every command emits."""
+    if _collector is not None:
+        _collector.append(doc)
+        return
+    render_json(doc)
+
+
+def render_json(doc: Any) -> None:
+    """Print a document, whatever the collector is doing.  For fanout's own use."""
+    print(json.dumps(doc, indent=2, default=_jsonable))
+
+
+def shorten(value: Any, limit: int = TABLE_VALUE_MAX) -> str:
+    """Return a short one-line rendering of a value, for tables and diffs."""
+    text = str(value)
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def note(message: str) -> None:
+    """Print an advisory to stderr, so a script's own output is undisturbed."""
+    print(f"note: {message}", file=sys.stderr)
+
+
+def warn(message: str) -> None:
+    """Print a warning to stderr: the command carried on regardless."""
+    print(f"warning: {message}", file=sys.stderr)
+
+
+def error(message: str) -> None:
+    """Print a failure to stderr, with the prefix argparse itself uses."""
+    print(f"error: {message}", file=sys.stderr)
+
+
+def aborted() -> None:
+    """Say that a confirmation was declined.  Not a malfunction."""
+    print("Aborted.", file=sys.stderr)
+
+
+# --- the two ends of a file argument --------------------------------------------------------
+#
+# Two rules, and neither of them is ours: they are what a person who has used
+# a Unix command line before already expects.
+#
+# A file argument of ``-`` is the standard stream -- output where a file
+# would be written, input where one would be read.  It is obeyed wherever it
+# is typed, terminal or not: somebody who types it means it, and an explicit
+# argument that is quietly ignored is the kind of surprise that makes a
+# program feel untrustworthy on the day it is met.
+#
+# Nothing a person did not ask for is overwritten.  Every path that would
+# land on an existing file goes through :func:`may_overwrite`, which asks;
+# ``-y``/``--yes`` is how a script says yes in advance.
+
+
+# What a file argument spells when it means the standard stream.
+STDIO = "-"
+
+
+def is_stdio(file: str | Path | None) -> bool:
+    """Whether a file argument names the standard stream rather than a file."""
+    return file is not None and str(file) == STDIO
+
+
+def may_overwrite(path: Path, *, yes: bool = False) -> bool:
+    """Whether ``path`` may be written, asking first if something is there.
+
+    Says "Aborted." itself on a no, because every caller said exactly that.
+    """
+    if not path.exists() or yes:
+        return True
+    if confirm(f"'{path}' already exists. Overwrite?"):
+        return True
+    aborted()
+    return False
+
+
+def read_in(file: str | Path | None) -> str:
+    """Return the text of ``file``, or of standard input when it is ``-``.
+
+    The reading half of :func:`write_out`, and the reason every command that
+    takes a file takes a pipe as well: ``curl ... | alfenctl import -``.  A
+    missing file raises :class:`OSError`, which callers with something to add
+    ("cannot read the tag list: ...") catch, and the rest let the error
+    funnel print.
+
+    Binary inputs keep their own path: a firmware package is identified partly
+    by its filename, and a stream has none.
+    """
+    if file is None or is_stdio(file):
+        return sys.stdin.read()
+    return Path(file).read_text(encoding="utf-8")
+
+
+def write_out(
+    payload: str | bytes,
+    file: str | Path | None,
+    *,
+    default_name: str | Callable[[], str],
+    yes: bool = False,
+    summary: str = "",
+) -> int:
+    """Write ``payload`` where the caller asked, and return an exit code.
+
+    ``-`` is standard output, on a terminal as much as through a pipe.  With
+    no file named at all there is nothing to obey, so the two differ: a pipe
+    gets the bytes, and a terminal gets ``default_name`` in the working
+    directory, because a dump nobody redirected would only scroll past.
+
+    ``default_name`` may be a callable, for the callers that have to ask the
+    device its name to build one: a piped export then never asks.
+
+    ``summary`` says what was written ("412 log lines"), for the callers that
+    would rather count than just name the path.
+    """
+    target: str | Path | None = file
+    if target is None and sys.stdout.isatty():
+        target = default_name if isinstance(default_name, str) else default_name()
+    if target is None or is_stdio(target):
+        if isinstance(payload, str):
+            sys.stdout.write(payload)
+        else:
+            sys.stdout.buffer.write(payload)
+        return EXIT_OK
+    path = Path(str(target))
+    if not may_overwrite(path, yes=yes):
+        return EXIT_ERROR
+    if isinstance(payload, str):
+        path.write_text(payload, encoding="utf-8")
+    else:
+        path.write_bytes(payload)
+    print(f"Wrote {summary} to {path}" if summary else f"Wrote {path}", file=sys.stderr)
+    return EXIT_OK
+
+
+def _jsonable(value: Any) -> Any:
+    """Render the few non-JSON types a decoded field can hold."""
+    if isinstance(value, (bytes, bytearray)):
+        return value.hex()
+    return str(value)
+
+
+__all__ = [
+    "CLOCK_FORMAT",
+    "STDIO",
+    "TABLE_VALUE_MAX",
+    "aborted",
+    "collect_json",
+    "confirm",
+    "display_width",
+    "error",
+    "is_stdio",
+    "may_overwrite",
+    "note",
+    "print_json",
+    "print_rows",
+    "print_sections",
+    "print_table",
+    "read_in",
+    "render_json",
+    "shorten",
+    "stop_collecting",
+    "warn",
+    "write_out",
+]