devicectl-core 0.1.0__py3-none-any.whl

devicectl/cli/parser.py

@@ -0,0 +1,80 @@
+"""Filling in what the command line left out.
+
+Two small rewrites of ``argv`` before argparse ever sees it.  Both exist for
+the same reason: the options a command needs live on its *action* parsers,
+so a word left out is not merely a missing word -- it takes the options with
+it, and argparse's complaint names the wrong thing.
+
+Both leave a leading word alone, so a mistyped command or action still gets
+argparse's "invalid choice" rather than being quietly handed somewhere else,
+and both leave ``-h`` alone, because it has to reach the parser that lists
+the choices.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+# Options that must reach the root parser rather than a subcommand.
+ROOT_OPTIONS = ("-h", "--help", "--version")
+
+HELP_OPTIONS = ("-h", "--help")
+
+
+def insert_default_action(
+    argv: Sequence[str], defaults: Mapping[str, str]
+) -> list[str]:
+    """Return ``argv`` with a command's default ACTION filled in, if missing.
+
+    ``<prog> tags`` becomes ``<prog> tags list``, and options meant for that
+    default action are handed through to it (``<prog> scn --peers`` becomes
+    ``<prog> scn status --peers``).
+    """
+    argv = list(argv)
+    if not argv or argv[0] not in defaults:
+        return argv
+    rest = argv[1:]
+    if rest and (not rest[0].startswith("-") or rest[0] in HELP_OPTIONS):
+        return argv
+    return [argv[0], defaults[argv[0]], *rest]
+
+
+def insert_default_command(argv: Sequence[str], command: str) -> list[str]:
+    """Return ``argv`` with ``command`` filled in when no command was typed.
+
+    For a program with an obvious thing to do when run bare -- serving its
+    web interface, usually -- because a page of usage text is not what
+    somebody who typed the bare name came for.  Options meant for it are
+    handed through, so ``<prog> --port 8080`` reaches that command rather
+    than being told ``--port`` belongs to a subcommand.
+    """
+    argv = list(argv)
+    if not argv:
+        return [command]
+    first = argv[0]
+    if first in ROOT_OPTIONS or not first.startswith("-"):
+        return argv
+    return [command, *argv]
+
+
+def default_actions(commands: Mapping[str, Any]) -> dict[str, str]:
+    """Read every command's default ACTION out of the command table.
+
+    The alternative is a second table listing them, which has to be kept in
+    step with the first by hand and silently does nothing 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.
+    """
+    return {
+        name: command.default_action
+        for name, command in commands.items()
+        if getattr(command, "default_action", "")
+    }
+
+
+__all__ = [
+    "default_actions",
+    "insert_default_action",
+    "insert_default_command",
+]

devicectl/cli/report.py

@@ -0,0 +1,86 @@
+"""Drawing a slow operation's progress on a terminal.
+
+The one live stderr line, redrawn as things move and ended with a newline
+when the phase is over.  Two things turn it off: a pipe, where nothing would
+ever erase the escape codes, and a debug or trace mode, whose log lines
+would shred it.  Both fall back to plain lines, which is also what a log
+file wants.
+
+What a transfer *counts* is the program's own -- bytes for one, 128-byte
+blocks for another -- so :meth:`Reporter.sending` is left to the subclass.
+Everything around it, including closing off a half-drawn line when a failure
+lands on top of it, is here.
+"""
+
+from __future__ import annotations
+
+import sys
+from types import TracebackType
+
+from devicectl.progress import end_live, write_live
+from devicectl.report import Reporter
+
+
+class TerminalReporter(Reporter):
+    """Report a slow operation's progress to the terminal.
+
+    Use it as a context manager: leaving the block closes off a live line
+    that a failure would otherwise have left half-drawn, with the error
+    message landing on top of it.
+    """
+
+    def __init__(self, *, quiet: bool = False) -> None:
+        """Report to stderr, drawing a live line unless ``quiet`` or a pipe.
+
+        ``quiet`` is what a program's ``--debug`` or ``--trace`` passes: its
+        own logging is going to the same stream, and the two cannot share a
+        line that is redrawn in place.
+        """
+        self.quiet = quiet
+        self.live = not quiet and sys.stderr.isatty()
+        self._drawn = False  # a live line is on screen, awaiting its newline
+        self._last_draw = 0.0
+
+    def __enter__(self) -> "TerminalReporter":
+        """Return the reporter; nothing is drawn until something happens."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """End any live line, so the next thing printed starts on its own."""
+        self._close()
+
+    def _close(self) -> None:
+        """Finish the live line, if one is on screen."""
+        if self._drawn:
+            end_live()
+            self._drawn = False
+
+    def _draw(self, text: str) -> None:
+        """Put ``text`` on the live line (no-op when there is no live line)."""
+        if not self.live:
+            return
+        write_live(text)
+        self._drawn = True
+
+    def step(self, message: str) -> None:
+        """Print the new phase on a line of its own."""
+        self._close()
+        print(f"{message}...")
+
+    def detail(self, message: str) -> None:
+        """Print a detail, indented under the phase it belongs to."""
+        self._close()
+        print(f"  {message}")
+
+    def warn(self, message: str) -> None:
+        """Print a warning to stderr."""
+        self._close()
+        print(f"warning: {message}", file=sys.stderr)
+
+
+__all__ = ["TerminalReporter"]

devicectl/cli/target.py

@@ -0,0 +1,26 @@
+"""Choosing between sources of the same setting.
+
+Which device a command talks to can be answered by the command line, by a
+named table in the config file, by that file's own defaults, or by whatever
+the program can discover for itself.  Each program resolves that its own way,
+but they all resolve it by asking the same question of one value after
+another, and this is that question.
+"""
+
+from __future__ import annotations
+
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def first_set(*values: T | None, default: T) -> T:
+    """Return the first value that was actually given, else ``default``.
+
+    Sources are passed most specific first, so a precedence rule reads as one
+    line instead of a stack of conditionals.
+    """
+    return next((value for value in values if value is not None), default)
+
+
+__all__ = ["first_set"]

devicectl/clock.py

@@ -0,0 +1,57 @@
+"""How far a device's clock is from this computer's, in words.
+
+Both programs show it, on the same card of the same dashboard, and each had
+its own sentence for it: one said "3.5 hours ahead of this computer", the
+other printed a bare "03h 30m" beside a label and left the direction out
+altogether.  One phrase now, with the direction in it and the computer left
+out of it -- the page is often read on a different machine from the one the
+program runs on, and "this computer" is then the wrong one.
+"""
+
+from __future__ import annotations
+
+from devicectl.progress import SECONDS_PER_DAY, SECONDS_PER_HOUR, SECONDS_PER_MINUTE
+
+# Closer than this and the two clocks are the same clock.  A reading takes a
+# round trip, and a device that answers in a second and a half is not a
+# device a second and a half out.
+DRIFT_NOISE_S = 2.0
+
+SECONDS_PER_YEAR = 365 * SECONDS_PER_DAY
+
+IN_SYNC = "in sync"
+
+# The scale matters: a device that has never been set is not seconds out but
+# years, since it boots with its clock at whatever its firmware was built on.
+_UNITS = (
+    (SECONDS_PER_MINUTE, 1, "second", 0),
+    (SECONDS_PER_HOUR, SECONDS_PER_MINUTE, "minute", 0),
+    (SECONDS_PER_DAY, SECONDS_PER_HOUR, "hour", 1),
+    (SECONDS_PER_YEAR, SECONDS_PER_DAY, "day", 1),
+    (None, SECONDS_PER_YEAR, "year", 1),
+)
+
+
+def format_drift(seconds: float | None) -> str | None:
+    """Say ``12 seconds ahead``, ``2.5 years behind`` or ``in sync``.
+
+    Positive is a device clock ahead of this computer's.  None -- a device
+    that reports no time -- is handed back as None, because what to say
+    instead is the caller's: a charger and a battery do not fail to have a
+    clock for the same reason.
+    """
+    if seconds is None:
+        return None
+    size = abs(seconds)
+    if size < DRIFT_NOISE_S:
+        return IN_SYNC
+    for below, per, word, digits in _UNITS:
+        if below is None or size < below:
+            amount = round(size / per, digits)
+            said = f"{amount:.{digits}f}"
+            plural = "" if amount == 1 else "s"
+            return f"{said} {word}{plural} {'ahead' if seconds > 0 else 'behind'}"
+    raise AssertionError("unreachable: the last unit has no upper bound")
+
+
+__all__ = ["DRIFT_NOISE_S", "IN_SYNC", "format_drift"]

devicectl/devtools/__init__.py

@@ -0,0 +1,6 @@
+"""Checks on the browser half that no off-the-shelf linter performs.
+
+Each is a module with a ``main`` and runs as ``python -m
+devicectl.devtools.<name> <static-root>``, so a program's test suite is a
+few lines pointing it at its own ``web/static``.
+"""