pycan-plot 0.0.1__tar.gz

pycan_plot-0.0.1/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+dist/
+.pytest_cache/
+docs/superpowers/

pycan_plot-0.0.1/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: pycan-plot
+Version: 0.0.1
+Summary: Plot CAN signals from a candump log using a KCD database
+Author-email: Alexander Becker <nabla@radiation.systems>
+License-Expression: GPL-3.0-or-later
+Requires-Python: >=3.9
+Requires-Dist: cantools
+Requires-Dist: click
+Requires-Dist: matplotlib
+Requires-Dist: rich
+Description-Content-Type: text/markdown
+
+# pycan-plot
+
+Graph CAN signals from a recorded `candump` log, decoded through a KCD
+database.
+
+## Installation
+
+```console
+pip install -e .
+```
+
+## Usage
+
+```console
+pycan-plot capture.log -d database.kcd -s Status.Voltage -s Status.Mode -o plot.png
+```
+
+Signals are named `Message.Signal`, exactly as they appear in the KCD.
+With no `-o`, an interactive window opens instead.
+
+| Option | Meaning |
+|---|---|
+| `-d`, `--kcd` | KCD database (required) |
+| `-s`, `--signal` | `Message.Signal` to plot; repeatable |
+| `-p`, `--prefix` | Hex stack-position prefix ORed onto each message ID (default `0x0`) |
+| `-t`, `--time-window` | `START..END`; each end is relative seconds (`12.5`) or a clock time (`08:25:40`), and either may be omitted |
+| `-o`, `--output` | Output file; format taken from the extension (`.png`, `.svg`, `.pdf`) |
+| `--show` | Open an interactive window; implied when `-o` is absent |
+| `--split` | One subplot per signal instead of overlaying them |
+| `--line` | Interpolate between samples instead of holding each value |
+
+Signals are drawn as steps by default, because a CAN signal holds its last
+received value until the next frame arrives. `--line` overrides that.
+
+Examples:
+
+```console
+# One module in stack position 2, clipped to twenty seconds of the capture
+pycan-plot capture.log -d db.kcd -s Status.Voltage -p 0x02000000 -t 10..30 -o v.png
+
+# Two signals on separate stacked axes, clipped by wall-clock time
+pycan-plot capture.log -d db.kcd -s Status.Voltage -s Status.Mode \
+    --split -t 08:25:40..08:26:10 -o both.svg
+```
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 1 | log, KCD, or output file could not be read or written |
+| 2 | CLI usage error (unknown message or signal, bad `-t`, bad `-p`) |
+| 3 | no samples found for any requested signal |
+
+Exit code 3 reports which stack-position prefixes *were* present for the
+requested messages — usually the fastest way to spot a wrong `-p`.
+
+## Fish tab completion
+
+An editable install writes the completion script automatically. To do it by
+hand:
+
+```fish
+_PYCAN_PLOT_COMPLETE=fish_source pycan-plot | source                                      # current shell
+_PYCAN_PLOT_COMPLETE=fish_source pycan-plot > ~/.config/fish/completions/pycan-plot.fish  # persistent
+```
+
+Completion covers log files, KCD files, message and signal names pulled live
+from the KCD on the command line, and — once the log file is given — the
+stack-position prefixes actually present in that log.
+
+## License
+
+`pycan-plot` is distributed under the terms of the GPL-3.0-or-later license.

pycan_plot-0.0.1/README.md

@@ -0,0 +1,74 @@
+# pycan-plot
+
+Graph CAN signals from a recorded `candump` log, decoded through a KCD
+database.
+
+## Installation
+
+```console
+pip install -e .
+```
+
+## Usage
+
+```console
+pycan-plot capture.log -d database.kcd -s Status.Voltage -s Status.Mode -o plot.png
+```
+
+Signals are named `Message.Signal`, exactly as they appear in the KCD.
+With no `-o`, an interactive window opens instead.
+
+| Option | Meaning |
+|---|---|
+| `-d`, `--kcd` | KCD database (required) |
+| `-s`, `--signal` | `Message.Signal` to plot; repeatable |
+| `-p`, `--prefix` | Hex stack-position prefix ORed onto each message ID (default `0x0`) |
+| `-t`, `--time-window` | `START..END`; each end is relative seconds (`12.5`) or a clock time (`08:25:40`), and either may be omitted |
+| `-o`, `--output` | Output file; format taken from the extension (`.png`, `.svg`, `.pdf`) |
+| `--show` | Open an interactive window; implied when `-o` is absent |
+| `--split` | One subplot per signal instead of overlaying them |
+| `--line` | Interpolate between samples instead of holding each value |
+
+Signals are drawn as steps by default, because a CAN signal holds its last
+received value until the next frame arrives. `--line` overrides that.
+
+Examples:
+
+```console
+# One module in stack position 2, clipped to twenty seconds of the capture
+pycan-plot capture.log -d db.kcd -s Status.Voltage -p 0x02000000 -t 10..30 -o v.png
+
+# Two signals on separate stacked axes, clipped by wall-clock time
+pycan-plot capture.log -d db.kcd -s Status.Voltage -s Status.Mode \
+    --split -t 08:25:40..08:26:10 -o both.svg
+```
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 1 | log, KCD, or output file could not be read or written |
+| 2 | CLI usage error (unknown message or signal, bad `-t`, bad `-p`) |
+| 3 | no samples found for any requested signal |
+
+Exit code 3 reports which stack-position prefixes *were* present for the
+requested messages — usually the fastest way to spot a wrong `-p`.
+
+## Fish tab completion
+
+An editable install writes the completion script automatically. To do it by
+hand:
+
+```fish
+_PYCAN_PLOT_COMPLETE=fish_source pycan-plot | source                                      # current shell
+_PYCAN_PLOT_COMPLETE=fish_source pycan-plot > ~/.config/fish/completions/pycan-plot.fish  # persistent
+```
+
+Completion covers log files, KCD files, message and signal names pulled live
+from the KCD on the command line, and — once the log file is given — the
+stack-position prefixes actually present in that log.
+
+## License
+
+`pycan-plot` is distributed under the terms of the GPL-3.0-or-later license.

pycan_plot-0.0.1/hatch_build.py

@@ -0,0 +1,23 @@
+"""Hatchling build hook — installs the fish completion on editable installs.
+
+The hook runs inside an isolated build environment where neither this package
+nor its dependencies are importable, so it reaches into `src/` for the
+dependency-free `_fish` module rather than importing `pycan_plot` proper.
+"""
+import os
+import sys
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict) -> None:
+        if version != "editable":
+            return
+        try:
+            sys.path.insert(0, os.path.join(self.root, "src"))
+            from pycan_plot._fish import install_fish_script
+
+            install_fish_script(os.path.expanduser("~"))
+        except Exception:
+            pass  # never block an install over completions

pycan_plot-0.0.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pycan-plot"
+dynamic = ["version"]
+description = "Plot CAN signals from a candump log using a KCD database"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "GPL-3.0-or-later"
+authors = [
+  { name = "Alexander Becker", email = "nabla@radiation.systems" },
+]
+dependencies = [
+  "click",
+  "cantools",
+  "matplotlib",
+  "rich",
+]
+
+[project.scripts]
+pycan-plot = "pycan_plot.main:main"
+
+[tool.hatch.version]
+path = "src/pycan_plot/__about__.py"
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pycan_plot"]
+
+[tool.hatch.envs.test]
+dependencies = [
+  "pytest",
+]
+[tool.hatch.envs.test.scripts]
+run = "pytest {args:tests}"
+
+[tool.hatch.envs.types]
+extra-dependencies = [
+  "mypy>=1.0.0",
+]
+[tool.hatch.envs.types.scripts]
+check = "mypy --install-types --non-interactive {args:src/pycan_plot tests}"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pycan_plot-0.0.1/src/pycan_plot/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

pycan_plot-0.0.1/src/pycan_plot/_completion.py

@@ -0,0 +1,168 @@
+"""Click shell-completion callbacks.
+
+Completions are computed live from the KCD named on the command line, so
+there is no generated table to keep in sync with the database. Every
+callback swallows exceptions: a malformed KCD must never break the user's
+shell.
+"""
+import re
+from pathlib import Path
+from typing import List, Optional
+
+import cantools
+from click.shell_completion import CompletionItem
+
+_ID_LINE = re.compile(r"^\(\d+(?:\.\d+)?\)\s+\S+\s+([0-9A-Fa-f]+)#")
+_PREFIX_MASK = 0x1F000000
+#: How many lines of the log to sample when completing -p.
+_PREFIX_SCAN_LINES = 50_000
+
+
+def _complete_paths(incomplete: str, suffix: str) -> List[CompletionItem]:
+    """Offer directories plus files ending in `suffix`, keeping the token's
+    user-visible form (`~/foo`, `./foo`, `foo`) rather than absolutising it."""
+    raw = incomplete or ""
+    expanded = Path(raw).expanduser() if raw else Path(".")
+    if raw.endswith("/") and expanded.is_dir():
+        directory, prefix = expanded, ""
+    else:
+        directory, prefix = expanded.parent, expanded.name
+    if not directory.exists():
+        return []
+
+    if raw.startswith("~"):
+        home = Path.home()
+
+        def display(p: Path) -> str:
+            try:
+                return "~/" + str(p.relative_to(home))
+            except ValueError:
+                return str(p)
+    else:
+        def display(p: Path) -> str:
+            return str(p)
+
+    items = []
+    for entry in sorted(directory.iterdir()):
+        if not entry.name.startswith(prefix):
+            continue
+        shown = display(entry)
+        if entry.is_dir():
+            items.append(CompletionItem(shown + "/", type="plain"))
+        elif entry.suffix == suffix:
+            items.append(CompletionItem(shown))
+    return items
+
+
+def _kcd_from_ctx(ctx) -> Optional[str]:
+    """During completion the -d value may still be sitting in ctx.args."""
+    kcd = ctx.params.get("kcd_file")
+    if kcd:
+        return kcd
+    for arg in ctx.args:
+        if str(arg).endswith(".kcd"):
+            return str(arg)
+    return None
+
+
+def _logfile_from_ctx(ctx) -> Optional[str]:
+    logfile = ctx.params.get("logfile")
+    if logfile:
+        return logfile
+    for arg in ctx.args:
+        if str(arg).endswith(".log"):
+            return str(arg)
+    return None
+
+
+def _load_db(ctx):
+    kcd = _kcd_from_ctx(ctx)
+    if not kcd:
+        return None
+    try:
+        return cantools.database.load_file(str(Path(kcd).expanduser()))
+    except Exception:
+        return None
+
+
+def complete_kcd(ctx, param, incomplete) -> List[CompletionItem]:
+    try:
+        return _complete_paths(incomplete, ".kcd")
+    except Exception:
+        return []
+
+
+def complete_logfile(ctx, param, incomplete) -> List[CompletionItem]:
+    try:
+        return _complete_paths(incomplete, ".log")
+    except Exception:
+        return []
+
+
+def complete_signal(ctx, param, incomplete) -> List[CompletionItem]:
+    """`Message.Signal` is a single token, so complete it in two phases:
+    message names (with a trailing dot) until the dot is typed, then that
+    message's signals as full `Message.Signal` strings."""
+    try:
+        db = _load_db(ctx)
+        if db is None:
+            return []
+        if "." not in incomplete:
+            return [
+                CompletionItem(m.name + ".")
+                for m in db.messages
+                if m.name.startswith(incomplete)
+            ]
+        message_name, partial = incomplete.split(".", 1)
+        try:
+            message = db.get_message_by_name(message_name)
+        except KeyError:
+            return []
+        return [
+            CompletionItem(f"{message_name}.{s.name}")
+            for s in message.signals
+            if s.name.startswith(partial)
+        ]
+    except Exception:
+        return []
+
+
+def complete_prefix(ctx, param, incomplete) -> List[CompletionItem]:
+    """Offer the stack-position prefixes actually present in the log."""
+    try:
+        logfile = _logfile_from_ctx(ctx)
+        if not logfile:
+            return []
+        seen = set()
+        with open(Path(logfile).expanduser(), "r") as fh:
+            for count, line in enumerate(fh):
+                if count >= _PREFIX_SCAN_LINES:
+                    break
+                match = _ID_LINE.match(line)
+                if match:
+                    seen.add(int(match.group(1), 16) & _PREFIX_MASK)
+        return [
+            CompletionItem(f"0x{p:08X}")
+            for p in sorted(seen)
+            if f"0x{p:08X}".lower().startswith(incomplete.lower())
+        ]
+    except Exception:
+        return []
+
+
+def fish_source() -> str:
+    """The fish completion script, generated by Click itself."""
+    from click.shell_completion import FishComplete
+
+    from pycan_plot.main import main
+
+    return FishComplete(main, {}, "pycan-plot", "_PYCAN_PLOT_COMPLETE").source()
+
+
+def install_fish(quiet: bool = False) -> None:
+    """Write the fish completion script into the user's fish config."""
+    from pycan_plot._fish import install_fish_script
+
+    dest = install_fish_script(str(Path.home()))
+    if not quiet:
+        print(f"Installed → {dest}")

pycan_plot-0.0.1/src/pycan_plot/_fish.py

@@ -0,0 +1,45 @@
+"""The fish completion script text, with no third-party imports.
+
+This module is deliberately dependency-free: the hatchling build hook imports
+it from an isolated build environment where neither `pycan_plot`'s
+dependencies nor the package itself are installed yet.
+
+The script is generic boilerplate — it delegates every completion back to the
+running command via `_PYCAN_PLOT_COMPLETE=fish_complete`, and embeds no option
+or signal names. That is what makes hard-coding it safe. `test_completion.py`
+asserts it still matches what the installed Click generates, so a change in
+Click's template is caught rather than silently shipped stale.
+"""
+
+FISH_SCRIPT = '''function _pycan_plot_completion;
+    set -l response (env _PYCAN_PLOT_COMPLETE=fish_complete COMP_WORDS=(commandline -cp) COMP_CWORD=(commandline -t) pycan-plot);
+
+    for completion in $response;
+        set -l metadata (string split "," $completion);
+
+        if test $metadata[1] = "dir";
+            __fish_complete_directories $metadata[2];
+        else if test $metadata[1] = "file";
+            __fish_complete_path $metadata[2];
+        else if test $metadata[1] = "plain";
+            echo $metadata[2];
+        end;
+    end;
+end;
+
+complete --no-files --command pycan-plot --arguments "(_pycan_plot_completion)";
+'''
+
+#: Where the script belongs in a user's fish configuration.
+FISH_RELATIVE_DEST = ".config/fish/completions/pycan-plot.fish"
+
+
+def install_fish_script(home: str) -> str:
+    """Write FISH_SCRIPT under `home` and return the path written."""
+    import os
+
+    dest = os.path.join(home, FISH_RELATIVE_DEST)
+    os.makedirs(os.path.dirname(dest), exist_ok=True)
+    with open(dest, "w") as fh:
+        fh.write(FISH_SCRIPT)
+    return dest

pycan_plot-0.0.1/src/pycan_plot/candump.py

@@ -0,0 +1,62 @@
+"""Parsing of `candump`-format text logs.
+
+A line looks like:
+
+    (1786364740.740423) can0 0107800C#00000000
+
+That is: a parenthesised epoch timestamp, the interface name, then the
+arbitration ID and payload separated by `#`. IDs of 3 hex digits are
+standard, 8 hex digits extended — we do not distinguish them, since a KCD
+frame ID comparison covers both. Lines using `##` (CAN FD) or `#R`
+(remote frames) carry nothing we can plot and are counted as malformed.
+"""
+import os
+import re
+from typing import Iterator, NamedTuple, Union
+
+_LINE = re.compile(
+    r"^\((?P<ts>\d+(?:\.\d+)?)\)\s+"   # (timestamp)
+    r"\S+\s+"                          # interface
+    r"(?P<id>[0-9A-Fa-f]+)"            # arbitration ID
+    r"#(?P<data>[0-9A-Fa-f]*)\s*$"     # payload (possibly empty)
+)
+
+
+class Frame(NamedTuple):
+    timestamp: float
+    arb_id: int
+    data: bytes
+
+
+class CandumpReader:
+    """Iterable over the frames in a candump log.
+
+    Malformed lines are skipped rather than raised on; after iteration
+    finishes, `malformed` holds how many were skipped. Blank lines are
+    ignored entirely and do not count as malformed. Re-iterating restarts
+    the count from zero.
+    """
+
+    def __init__(self, path: Union[str, os.PathLike]) -> None:
+        self.path = path
+        self.malformed = 0
+
+    def __iter__(self) -> Iterator[Frame]:
+        self.malformed = 0
+        with open(self.path, "r") as fh:
+            for line in fh:
+                if not line.strip():
+                    continue
+                match = _LINE.match(line)
+                if match is None:
+                    self.malformed += 1
+                    continue
+                payload = match.group("data")
+                if len(payload) % 2:
+                    self.malformed += 1
+                    continue
+                yield Frame(
+                    float(match.group("ts")),
+                    int(match.group("id"), 16),
+                    bytes.fromhex(payload),
+                )

pycan_plot-0.0.1/src/pycan_plot/errors.py

@@ -0,0 +1,25 @@
+"""Exceptions that carry the tool's documented exit codes."""
+
+
+class PlotError(Exception):
+    """Base for errors that map onto a process exit code."""
+
+    exit_code = 1
+
+
+class InputError(PlotError):
+    """A file could not be read, parsed, or written."""
+
+    exit_code = 1
+
+
+class UsageError(PlotError):
+    """The command line asked for something that cannot be satisfied."""
+
+    exit_code = 2
+
+
+class NoDataError(PlotError):
+    """Not one requested signal produced a single sample."""
+
+    exit_code = 3

pycan_plot-0.0.1/src/pycan_plot/extract.py

@@ -0,0 +1,104 @@
+"""The single streaming pass over a candump log.
+
+Only frames whose arbitration ID matches a requested message (with the
+stack-position prefix already ORed in) are decoded; everything else costs
+one dict lookup. That is what keeps a multi-million-line log tractable.
+"""
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Set
+
+from pycan_plot.selection import SignalRef
+from pycan_plot.timespec import TimeWindow
+
+#: Stack position lives in bits [28:24] of a v1 extended ID.
+PREFIX_MASK = 0x1F000000
+
+
+@dataclass
+class Series:
+    """All samples collected for one requested signal."""
+
+    ref: SignalRef
+    times: List[float] = field(default_factory=list)
+    values: List[float] = field(default_factory=list)
+
+    @property
+    def label(self) -> str:
+        return self.ref.label
+
+    @property
+    def unit(self) -> Optional[str]:
+        return self.ref.signal.unit
+
+    @property
+    def choices(self) -> Optional[Dict[int, Any]]:
+        return self.ref.signal.choices
+
+
+@dataclass
+class ExtractResult:
+    series: Dict[str, Series]
+    malformed: int = 0
+    observed_prefixes: Dict[int, Set[int]] = field(default_factory=dict)
+    frames_scanned: int = 0
+
+
+def extract(
+    reader: Iterable,
+    refs: Sequence[SignalRef],
+    prefix: int,
+    window: TimeWindow,
+) -> ExtractResult:
+    """Stream `reader` once and collect samples for every ref in `refs`."""
+    series = {ref.label: Series(ref) for ref in refs}
+
+    # Frames we must decode, keyed by the fully-prefixed ID.
+    wanted: Dict[int, List[SignalRef]] = {}
+    # Base IDs we watch for the wrong-prefix hint, whatever their prefix.
+    watched_bases: Set[int] = set()
+    for ref in refs:
+        wanted.setdefault(ref.base_frame_id | prefix, []).append(ref)
+        watched_bases.add(ref.base_frame_id)
+
+    result = ExtractResult(series=series)
+    result.observed_prefixes = {base: set() for base in watched_bases}
+
+    start: Optional[float] = None
+    end: Optional[float] = None
+    bounds_resolved = False
+
+    for frame in reader:
+        result.frames_scanned += 1
+        if not bounds_resolved:
+            # Bounds are relative to the first frame in the log, not the
+            # first matching one, so resolve them as soon as we see any frame.
+            start, end = window.resolve(frame.timestamp)
+            bounds_resolved = True
+
+        base = frame.arb_id & ~PREFIX_MASK
+        if base in result.observed_prefixes:
+            result.observed_prefixes[base].add(frame.arb_id & PREFIX_MASK)
+
+        refs_here = wanted.get(frame.arb_id)
+        if refs_here is None:
+            continue
+        if start is not None and frame.timestamp < start:
+            continue
+        if end is not None and frame.timestamp > end:
+            continue
+
+        try:
+            decoded = refs_here[0].message.decode(frame.data, decode_choices=False)
+        except Exception:
+            # Short, over-long or otherwise undecodable payload: count and move on.
+            result.malformed += 1
+            continue
+
+        for ref in refs_here:
+            if ref.signal.name not in decoded:
+                continue  # a muxed signal that this frame does not carry
+            series[ref.label].times.append(frame.timestamp)
+            series[ref.label].values.append(float(decoded[ref.signal.name]))
+
+    result.malformed += getattr(reader, "malformed", 0)
+    return result