Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,15 @@ All notable changes to this project are documented here. The format follows

## [Unreleased]

### Added

- DEBUG logging of every action, one line each, never the output: `flipperone.linux` (a command or a file read, its
exit code, time and sizes; streams, file copies), `flipperone.cli` (an MCU or probe command, its time and reply size;
streams and watches). `flipperone.wire` (the bytes) stays as it was.
- DEBUG logging of each command's output, as a record after its line, indented, stderr under `err:`:
`flipperone.linux.output`, `flipperone.cli.output`; `log_output_limit` of `Linux` and of the CLI devices (64 KiB by
default) caps each stream, the rest is counted.

## [0.1.0] - 2026-11-15

### Added
Expand Down
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,12 @@ with connect.linux_over_ssh("10.0.0.1", password="...") as linux:
The subsystem classes take any transport: `Mcu(stream)` runs over a serial port, an SSH channel or your own stream;
`Linux(shell)` over SSH or your own shell. `flipperone.connect` only pairs them the usual way.

Nothing is printed. At DEBUG the library logs every action in one line, never its output: `flipperone.linux`
(commands, file reads, streams, copies: exit code, time, sizes) and `flipperone.cli` (MCU and probe commands: time,
reply size); `flipperone.linux.output` and `flipperone.cli.output` add each command's output after its line (up to
`log_output_limit` bytes per stream, 64 KiB by default). `flipperone.wire` logs the bytes themselves at DEBUG: silence
it, or the output loggers, on its own (`logging.getLogger("flipperone.wire").setLevel(logging.WARNING)`).

## Documentation

- [docs/transport.md](docs/transport.md) — streams, shells, finding ports
Expand Down
30 changes: 27 additions & 3 deletions src/flipperone/_cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@
from contextlib import contextmanager
from dataclasses import dataclass

from ._output import DEFAULT_LIMIT
from ._output import record as output_record
from .errors import CliError, CommandNotFound, FlipperOneError, PortNotFound, SyncTimeout, UsageError
from .transport.base import Stream

Expand All @@ -30,6 +32,8 @@
_NOT_FOUND = re.compile(r"could not find command `([^`]*)`")

wire = logging.getLogger("flipperone.wire")
log = logging.getLogger("flipperone.cli") # DEBUG: one line per command (the device, the command, time, size)
output_log = logging.getLogger("flipperone.cli.output") # DEBUG: each command's reply, after its line

Connect = Callable[[], Stream]

Expand Down Expand Up @@ -93,8 +97,10 @@ class CliDevice:

def __init__(self, connect: Stream | Connect, *, timeout_s: float = 2.0, sync_timeout_s: float = 3.0,
settle_s: float = 0.3, reconnect_timeout_s: float = 20.0,
sleep: Callable[[float], None] = time.sleep, clock: Callable[[], float] = time.monotonic):
sleep: Callable[[float], None] = time.sleep, clock: Callable[[], float] = time.monotonic,
log_output_limit: int = DEFAULT_LIMIT):
self.timeout_s = timeout_s
self.log_output_limit = log_output_limit # bytes of a reply the flipperone.cli.output logger keeps
self.sync_timeout_s = sync_timeout_s
self.settle_s = settle_s
self.reconnect_timeout_s = reconnect_timeout_s
Expand Down Expand Up @@ -163,9 +169,16 @@ def reconnect(self, timeout: float | None = None) -> None:

def run(self, line: str, timeout: float | None = None) -> Result:
"""Run one command line and return its reply once the prompt is back."""
started = self._clock()
self._send(line)
raw = self._read_until(PROMPT, timeout or self.timeout_s, f"the prompt after '{line}'")
try:
raw = self._read_until(PROMPT, timeout or self.timeout_s, f"the prompt after '{line}'")
except Exception as e:
log.debug("%s: %s -> %s: %s", type(self).__name__, line, type(e).__name__, e)
raise
text = clean(raw, line)
log.debug("%s: %s -> %.2f s, %d B", type(self).__name__, line, self._clock() - started, len(text))
self._log_reply(line, text)
m = _NOT_FOUND.search(text)
if m:
raise CommandNotFound(f"{self.name}: could not find command `{m.group(1)}`")
Expand All @@ -177,7 +190,16 @@ def stream(self, line: str, seconds: float) -> Result:
raw = self._read_for(seconds)
self._write(ETX)
raw += self._read_until(PROMPT, self.timeout_s, f"the prompt after stopping '{line}'")
return Result(line, raw, clean(raw, line))
text = clean(raw, line)
log.debug("%s: %s (for %g s) -> %d B", type(self).__name__, line, seconds, len(text))
self._log_reply(line, text)
return Result(line, raw, text)

def _log_reply(self, line: str, text: str) -> None:
if output_log.isEnabledFor(logging.DEBUG):
entry = output_record(f"{type(self).__name__}: {line}", text, limit=self.log_output_limit)
if entry:
output_log.debug("%s", entry)

def watch(self, line: str, handler: Callable[[str], bool], timeout: float) -> bool:
"""Run a command that keeps printing and give each line to ``handler`` as it arrives, until the handler
Expand All @@ -198,6 +220,8 @@ def watch(self, line: str, handler: Callable[[str], bool], timeout: float) -> bo
break
self._write(ETX)
self._read_until(PROMPT, self.timeout_s, f"the prompt after stopping '{line}'")
log.debug("%s: %s (watched, %g s at most) -> %s", type(self).__name__, line, timeout,
"the handler stopped it" if done else "timed out")
return done

@contextmanager
Expand Down
23 changes: 23 additions & 0 deletions src/flipperone/_output.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# SPDX-License-Identifier: GPL-3.0-or-later
"""A command's output as a log record: what the ``*.output`` loggers write at DEBUG."""

from __future__ import annotations

DEFAULT_LIMIT = 64 * 1024 # bytes of one stream (stdout or stderr) kept in a record; the rest is only counted
INDENT = " "


def clip(text: str, limit: int) -> str:
"""``text`` cut to ``limit`` bytes (UTF-8), with how many were left out."""
data = text.encode()
if len(data) <= limit:
return text
return data[:limit].decode(errors="ignore") + f"\n... {len(data) - limit} B more"


def record(label: str, out: str, err: str = "", limit: int = DEFAULT_LIMIT) -> str | None:
"""``label:`` then the output indented, ``err:`` and stderr after it when there is any; None when both are empty."""
def indented(text: str) -> str:
return "\n".join(INDENT + line for line in clip(text, limit).rstrip("\n").split("\n"))
parts = ([indented(out)] if out else []) + ([INDENT + "err:", indented(err)] if err else [])
return f"{label}:\n" + "\n".join(parts) if parts else None
38 changes: 33 additions & 5 deletions src/flipperone/linux/linux.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,18 @@

from __future__ import annotations

import logging
import shlex
from collections.abc import Callable, Iterable
from pathlib import Path

from .._output import DEFAULT_LIMIT
from .._output import record as output_record
from ..transport.base import CommandResult, Shell, Stream

log = logging.getLogger("flipperone.linux") # DEBUG: one line per action (what, exit code, time, sizes), no output
output_log = logging.getLogger("flipperone.linux.output") # DEBUG: each command's stdout and stderr, after its line

MARK = "===FLIPPERONE:" # separates files in a read_many reply; not something sysfs content holds


Expand All @@ -17,26 +23,44 @@ class Linux:

``shell``: an :class:`~flipperone.transport.ssh.SshShell` (see :func:`flipperone.connect.linux_over_ssh`) or any
other :class:`~flipperone.transport.base.Shell`. ``command_timeout_s``: the default for :meth:`run`.
``log_output_limit``: bytes of a command's stdout (and of its stderr) the ``flipperone.linux.output`` logger keeps.
"""

def __init__(self, shell: Shell, *, command_timeout_s: float = 20.0):
def __init__(self, shell: Shell, *, command_timeout_s: float = 20.0, log_output_limit: int = DEFAULT_LIMIT):
self.shell = shell
self.command_timeout_s = command_timeout_s
self.log_output_limit = log_output_limit

def run(self, command: str, *, timeout: float | None = None, check: bool = False,
on_line: Callable[[str], None] | None = None) -> CommandResult:
"""Run a shell command line. ``check``: raise :class:`~flipperone.errors.CommandFailed` on a non-zero exit.
``on_line`` gets each line of stdout as it arrives; the result still holds all of it."""
result = self.shell.run(command, self.command_timeout_s if timeout is None else timeout, on_line)
return result.check() if check else result
return self._run(command, command, timeout, check, on_line)

def sudo(self, command: str, *, timeout: float | None = None, check: bool = False,
on_line: Callable[[str], None] | None = None) -> CommandResult:
""":meth:`run` as root through ``sudo -n`` (the user needs passwordless sudo)."""
return self.run(f"sudo -n sh -c {shlex.quote(command)}", timeout=timeout, check=check, on_line=on_line)
return self._run(f"sudo -n sh -c {shlex.quote(command)}", f"sudo {command}", timeout, check, on_line)

def _run(self, command: str, label: str, timeout: float | None, check: bool,
on_line: Callable[[str], None] | None) -> CommandResult:
"""``command`` run, logged as ``label`` (what the caller asked for, not the wrapping)."""
try:
result = self.shell.run(command, self.command_timeout_s if timeout is None else timeout, on_line)
except Exception as e:
log.debug("%s -> %s: %s", label, type(e).__name__, e)
raise
log.debug("%s -> exit %d, %.2f s, out %d B%s", label, result.code, result.duration_s, len(result.out),
f", err {len(result.err)} B" if result.err else "")
if output_log.isEnabledFor(logging.DEBUG):
text = output_record(label, result.out, result.err, self.log_output_limit)
if text:
output_log.debug("%s", text)
return result.check() if check else result

def open_stream(self, command: str, *, sudo: bool = False) -> Stream:
"""A command as a duplex byte stream (its stdin and stdout); closing the stream ends it."""
log.debug("stream %s%s", "sudo " if sudo else "", command)
if sudo:
command = f"sudo -n sh -c {shlex.quote(command)}"
return self.shell.open_stream(command)
Expand All @@ -53,7 +77,9 @@ def read_many(self, paths: Iterable[str], *, sudo: bool = False) -> dict[str, st
script = ("for p in " + " ".join(shlex.quote(p) for p in paths)
+ f"; do if [ -r \"$p\" ]; then printf '%s\\n' '{MARK}'\"$p\"; cat -- \"$p\" 2>/dev/null; "
f"printf '\\n'; else printf '%s\\n' '{MARK}'\"$p\"':missing'; fi; done")
result = self.sudo(script) if sudo else self.run(script)
label = f"{'sudo ' if sudo else ''}read {' '.join(paths)}"
command = f"sudo -n sh -c {shlex.quote(script)}" if sudo else script
result = self._run(command, label, None, False, None)
return parse_read_many(result.out, paths)

def glob(self, pattern: str) -> list[str]:
Expand All @@ -65,10 +91,12 @@ def exists(self, path: str) -> bool:
return self.run(f"test -e {shlex.quote(path)}").ok

def put(self, local: Path, remote: str) -> None:
log.debug("put %s -> %s (%d B)", local, remote, local.stat().st_size)
self.shell.put(local, remote)

def get(self, remote: str, local: Path) -> None:
self.shell.get(remote, local)
log.debug("get %s -> %s (%d B)", remote, local, local.stat().st_size)

def close(self) -> None:
self.shell.close()
Expand Down
22 changes: 22 additions & 0 deletions tests/test_output_log.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# SPDX-License-Identifier: GPL-3.0-or-later
import logging

from flipperone._output import clip, record
from flipperone.linux import Linux
from flipperone.testing import FakeShell


def test_record_indents_stdout_then_stderr_and_clips():
assert record("uname -r", "7.4.0\n") == "uname -r:\n 7.4.0"
assert record("x", "a\nb", "oops") == "x:\n a\n b\n err:\n oops"
assert record("x", "", "") is None
assert clip("abcdef", 4) == "abcd\n... 2 B more"


def test_linux_logs_the_action_and_its_output(caplog):
shell = FakeShell({"uname -r": "7.4.0\n"})
with caplog.at_level(logging.DEBUG, logger="flipperone"):
Linux(shell, log_output_limit=3).run("uname -r")
lines = [(r.name, r.getMessage()) for r in caplog.records]
assert lines[0][0] == "flipperone.linux" and lines[0][1].startswith("uname -r -> exit 0, ")
assert lines[1] == ("flipperone.linux.output", "uname -r:\n 7.4\n ... 3 B more")
Loading