capkit 0.1.0__tar.gz → 0.2.0__tar.gz

{capkit-0.1.0 → capkit-0.2.0}/.github/workflows/ci.yml

@@ -60,4 +60,6 @@ jobs:
           entry=next(name for name in names if name.endswith('entry_points.txt'));
           text=archive.read(entry).decode();
           assert '[dbckit.readers]' in text;
+          assert 'asc = capkit.readers.vector_asc:VectorAscReader' in text;
+          assert 'log = capkit.integration:DispatchReader' in text;
           assert 'txt = capkit.integration:DispatchReader' in text"

{capkit-0.1.0 → capkit-0.2.0}/CHANGELOG.md

@@ -7,7 +7,23 @@ Versioning will follow [Semantic Versioning](https://semver.org/) from 1.0.0 onw
 
 ---
 
-## [Unreleased]
+## [0.2.0] — 2026-07-16
+
+### Added
+
+- can-utils `candump -L` reader (`candump`) with classic, remote, and CAN FD support,
+  pinned by a 300-frame fixture.
+- Vector CANalyzer/CANoe ASC reader (`vector-asc`) covering classic, remote, error,
+  and CAN FD rows plus header-derived capture start times.
+- `Frame.bitrate_switch` and `Frame.error_state_indicator` CAN FD flags.
+- Lazy, cached discovery of third-party readers through the `capkit.readers`
+  entry-point group, including validated conflict and failure reporting.
+- python-can reference writer/reader cross-checks in the development test suite.
+
+### Changed
+
+- dbckit integration now handles `.log` through the sniffing dispatcher and
+  supersedes dbckit's built-in `.asc` reader with capkit's richer implementation.
 
 ## [0.1.0] — 2026-07-16
 

{capkit-0.1.0 → capkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capkit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Read CAN bus capture logs in different formats into one common frame stream
 Project-URL: Homepage, https://canforge.io/capkit
 Project-URL: Repository, https://github.com/canforge/capkit
@@ -44,6 +44,7 @@ Requires-Dist: dbckit>=1.0; extra == 'dev'
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-can>=4.6; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Description-Content-Type: text/markdown
 
@@ -70,8 +71,8 @@ Use it to:
 | Format | Reader name | Extensions | Status | Dependency |
 |---|---|---|---|---|
 | Kvaser CanKing TXT | `kvaser-txt` | `.txt` | Supported | none |
-| candump text | `candump` | `.log` | Planned | none |
-| Vector ASC | `vector-asc` | `.asc` | Planned | none |
+| candump text | `candump` | `.log` | Supported | none |
+| Vector ASC | `vector-asc` | `.asc` | Supported | none |
 | PCAN TRC | `pcan-trc` | `.trc` | Planned | none |
 | Generic CSV | `csv-table` | `.csv` | Planned | none |
 | Vector BLF | `vector-blf` | `.blf` | Planned adapter | `python-can` |
@@ -112,7 +113,7 @@ meta = capkit.probe("trace.txt")
 print(meta.format, meta.start_time)
 
 # registered reader names
-print(capkit.available_formats())   # ['kvaser-txt']
+print(capkit.available_formats())   # ['candump', 'kvaser-txt', 'vector-asc']
 ```
 
 The public API is six names: `read`, `probe`, `available_formats`,
@@ -165,7 +166,9 @@ class MyReader:
 capkit.register_reader(MyReader)
 ```
 
-Registration is process-global and is normally performed at import time.
+Registration is process-global. Installed packages can also advertise reader
+classes through the `capkit.readers` entry-point group; capkit discovers and
+caches them on the first `read()`, `probe()`, or `available_formats()` call.
 dbckit's `.txt` entry point sniffs among all registered readers, so a reader
 whose `sniff()` uniquely matches the content of a `.txt` log is used there
 too, regardless of the extensions it claims.
@@ -200,8 +203,8 @@ for decoded in dbckit.decode_frames(db, capkit.read("trace.txt")):
 ```
 
 capkit also registers its readers in dbckit's `dbckit.readers` entry-point
-group. With both packages installed, `dbckit.decode_log()` reads `.txt` logs
-through capkit directly:
+group. With both packages installed, `dbckit.decode_log()` reads `.txt`,
+`.log`, and `.asc` logs through capkit directly:
 
 ```python
 for decoded in dbckit.decode_log(db, "trace.txt"):
@@ -212,6 +215,10 @@ for decoded in dbckit.decode_log(db, "trace.txt"):
 
 - Kvaser dialects with absolute start-time headers are not supported;
   `probe()` returns `start_time=None` for `kvaser-txt`.
+- candump error-flag records are skipped by default and rejected in strict
+  mode; decoding them as CAN error frames is not claimed.
+- Vector ASC relative timestamp directives and non-English month names are
+  rejected instead of being interpreted approximately.
 - capkit reads frames only: no DBC or signal awareness (that is dbckit's job),
   no hardware I/O, no log writing, no dataframe export, no CLI.
 

{capkit-0.1.0 → capkit-0.2.0}/README.md

@@ -21,8 +21,8 @@ Use it to:
 | Format | Reader name | Extensions | Status | Dependency |
 |---|---|---|---|---|
 | Kvaser CanKing TXT | `kvaser-txt` | `.txt` | Supported | none |
-| candump text | `candump` | `.log` | Planned | none |
-| Vector ASC | `vector-asc` | `.asc` | Planned | none |
+| candump text | `candump` | `.log` | Supported | none |
+| Vector ASC | `vector-asc` | `.asc` | Supported | none |
 | PCAN TRC | `pcan-trc` | `.trc` | Planned | none |
 | Generic CSV | `csv-table` | `.csv` | Planned | none |
 | Vector BLF | `vector-blf` | `.blf` | Planned adapter | `python-can` |
@@ -63,7 +63,7 @@ meta = capkit.probe("trace.txt")
 print(meta.format, meta.start_time)
 
 # registered reader names
-print(capkit.available_formats())   # ['kvaser-txt']
+print(capkit.available_formats())   # ['candump', 'kvaser-txt', 'vector-asc']
 ```
 
 The public API is six names: `read`, `probe`, `available_formats`,
@@ -116,7 +116,9 @@ class MyReader:
 capkit.register_reader(MyReader)
 ```
 
-Registration is process-global and is normally performed at import time.
+Registration is process-global. Installed packages can also advertise reader
+classes through the `capkit.readers` entry-point group; capkit discovers and
+caches them on the first `read()`, `probe()`, or `available_formats()` call.
 dbckit's `.txt` entry point sniffs among all registered readers, so a reader
 whose `sniff()` uniquely matches the content of a `.txt` log is used there
 too, regardless of the extensions it claims.
@@ -151,8 +153,8 @@ for decoded in dbckit.decode_frames(db, capkit.read("trace.txt")):
 ```
 
 capkit also registers its readers in dbckit's `dbckit.readers` entry-point
-group. With both packages installed, `dbckit.decode_log()` reads `.txt` logs
-through capkit directly:
+group. With both packages installed, `dbckit.decode_log()` reads `.txt`,
+`.log`, and `.asc` logs through capkit directly:
 
 ```python
 for decoded in dbckit.decode_log(db, "trace.txt"):
@@ -163,6 +165,10 @@ for decoded in dbckit.decode_log(db, "trace.txt"):
 
 - Kvaser dialects with absolute start-time headers are not supported;
   `probe()` returns `start_time=None` for `kvaser-txt`.
+- candump error-flag records are skipped by default and rejected in strict
+  mode; decoding them as CAN error frames is not claimed.
+- Vector ASC relative timestamp directives and non-English month names are
+  rejected instead of being interpreted approximately.
 - capkit reads frames only: no DBC or signal awareness (that is dbckit's job),
   no hardware I/O, no log writing, no dataframe export, no CLI.
 

capkit-0.2.0/ROADMAP.md

@@ -0,0 +1,45 @@
+# Roadmap
+
+capkit 0.2.0 is [on PyPI](https://pypi.org/project/capkit/); the release checklist is complete
+and retired (the release process lives in [docs/releasing.md](docs/releasing.md)). Readers are
+fixture-first: a format lands only with a real capture under `tests/fixtures/<format>/`.
+
+## Planned readers
+
+- [ ] PCAN TRC (`.trc`)
+- [ ] Configurable generic CSV (`.csv`)
+- [ ] SocketCAN pcap/pcapng (`.pcap`, `.pcapng`)
+- [ ] Vector BLF (`.blf`) and ASAM MF4 (`.mf4`) through optional adapters
+- [ ] Additional Kvaser dialects (absolute start-time headers) as real fixtures arrive
+
+## Reading pipeline
+
+- [ ] File-object and stdin input alongside paths, so live captures pipe straight in
+  (`candump can0 | ...`)
+- [ ] Transparent reading of gzip-compressed logs (stdlib `gzip`; captures are large)
+- [ ] Collected-error mode between the two current extremes: skip unrecognized lines but
+  report them (count and line numbers) instead of skipping silently or raising on the
+  first
+
+## Stream operations
+
+- [ ] Filters: by ID set, channel, and time window
+- [ ] Merge several logs into one time-ordered stream (multi-bus and multi-file captures)
+- [ ] Explicit, opt-in timestamp rebasing helper — `read()` itself keeps returning
+  timestamps exactly as recorded
+- [ ] J1939 arbitration-ID decomposition (priority, PGN, source address): pure per-frame
+  arithmetic with no DBC awareness, which is where dbckit's J1939 helpers deliberately
+  stop
+
+## CLI (`capkit[cli]`)
+
+- [ ] `probe`, `head`, and `stats` commands (unique IDs, per-ID counts, time span)
+- [ ] `convert` between supported formats once writers exist
+
+## Deferred additions
+
+- [ ] Writers and format conversion
+- [ ] Dataframe export (pandas/polars) — recipes first, optional helpers only if the
+  recipes prove insufficient
+- [ ] python-can `Message` interop helpers
+- [ ] Benchmark suite pinning parse throughput on large logs

{capkit-0.1.0 → capkit-0.2.0}/capkit/model/frame.py

@@ -19,6 +19,8 @@ class Frame:
     is_error_frame: bool = False
     is_rx: bool | None = None
     dlc: int | None = None
+    bitrate_switch: bool = False
+    error_state_indicator: bool = False
 
 
 @dataclass(frozen=True, slots=True)

{capkit-0.1.0 → capkit-0.2.0}/capkit/readers/__init__.py

@@ -1,19 +1,24 @@
 """Reader registry and format-resolution logic."""
 from __future__ import annotations
 
+from importlib import metadata
 from pathlib import Path
 from typing import cast
 
 from capkit.readers.base import Reader, read_sample
+from capkit.readers.candump import CandumpReader
 from capkit.readers.kvaser_txt import KvaserTxtReader
+from capkit.readers.vector_asc import VectorAscReader
 
 _READERS: dict[str, type[Reader]] = {
+    CandumpReader.name: cast(type[Reader], CandumpReader),
     KvaserTxtReader.name: cast(type[Reader], KvaserTxtReader),
+    VectorAscReader.name: cast(type[Reader], VectorAscReader),
 }
+_ENTRY_POINTS_LOADED = False
 
 
-def register_reader(reader_type: type[Reader]) -> None:
-    """Register a zero-argument reader class for process-wide format resolution."""
+def _validate_reader(reader_type: object) -> tuple[str, type[Reader]]:
     if not isinstance(reader_type, type):
         raise TypeError("register_reader() requires a reader class, not an instance.")
 
@@ -22,9 +27,6 @@ def register_reader(reader_type: type[Reader]) -> None:
         raise TypeError("Reader type must define a non-empty string 'name'.")
 
     normalized = name.strip().lower()
-    if normalized in _READERS:
-        raise ValueError(f"Log format '{normalized}' is already registered.")
-
     extensions = getattr(reader_type, "extensions", None)
     if (
         not isinstance(extensions, tuple)
@@ -38,16 +40,75 @@ def register_reader(reader_type: type[Reader]) -> None:
     try:
         reader = reader_type()
     except Exception as error:
-        raise TypeError(f"Reader type '{normalized}' must be zero-argument constructible.") from error
+        raise TypeError(
+            f"Reader type '{normalized}' must be zero-argument constructible: {error}"
+        ) from error
 
     if any(not callable(getattr(reader, method, None)) for method in ("sniff", "probe", "read")):
         raise TypeError(f"Reader type '{normalized}' must define callable sniff(), probe(), and read() methods.")
 
-    _READERS[normalized] = reader_type
+    return normalized, cast(type[Reader], reader_type)
+
+
+def register_reader(reader_type: type[Reader]) -> None:
+    """Register a zero-argument reader class for process-wide format resolution."""
+    normalized, validated_type = _validate_reader(reader_type)
+    if normalized in _READERS:
+        raise ValueError(f"Log format '{normalized}' is already registered.")
+    _READERS[normalized] = validated_type
+
+
+def _distribution_name(entry_point: metadata.EntryPoint) -> str:
+    distribution = getattr(entry_point, "dist", None)
+    name = getattr(distribution, "name", None)
+    if isinstance(name, str) and name:
+        return name
+    distribution_metadata = getattr(distribution, "metadata", None)
+    if distribution_metadata is not None:
+        try:
+            metadata_name = distribution_metadata["Name"]
+        except (KeyError, TypeError):
+            pass
+        else:
+            if isinstance(metadata_name, str) and metadata_name:
+                return metadata_name
+    return "unknown"
+
+
+def _entry_point_context(entry_point: metadata.EntryPoint) -> str:
+    return (
+        f"capkit.readers entry point '{entry_point.name}' "
+        f"from distribution '{_distribution_name(entry_point)}'"
+    )
+
+
+def _load_entry_point_readers() -> None:
+    global _ENTRY_POINTS_LOADED
+    if _ENTRY_POINTS_LOADED:
+        return
+
+    discovered: dict[str, type[Reader]] = {}
+    for entry_point in metadata.entry_points(group="capkit.readers"):
+        context = _entry_point_context(entry_point)
+        try:
+            loaded = entry_point.load()
+            normalized, reader_type = _validate_reader(loaded)
+        except Exception as error:
+            raise RuntimeError(f"Failed to load {context}: {error}") from error
+
+        if normalized in _READERS or normalized in discovered:
+            raise RuntimeError(
+                f"Reader {context} conflicts with already registered log format '{normalized}'."
+            )
+        discovered[normalized] = reader_type
+
+    _READERS.update(discovered)
+    _ENTRY_POINTS_LOADED = True
 
 
 def registered_formats() -> list[str]:
     """Return sorted registered reader names."""
+    _load_entry_point_readers()
     return sorted(_READERS)
 
 
@@ -61,6 +122,7 @@ def _reader_type_for(
     format: str | None = None,
     sniff_only: bool = False,
 ) -> type[Reader]:
+    _load_entry_point_readers()
     if not _READERS:
         raise ValueError("No log formats are registered.")
 
@@ -101,4 +163,4 @@ def create_reader(
     return cast(Reader, reader_type(**(options or {})))
 
 
-__all__ = ["KvaserTxtReader", "Reader", "register_reader"]
+__all__ = ["CandumpReader", "KvaserTxtReader", "Reader", "VectorAscReader", "register_reader"]

capkit-0.2.0/capkit/readers/candump.py

@@ -0,0 +1,98 @@
+"""Reader for the can-utils ``candump -L`` text format."""
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from pathlib import Path
+from re import Match
+
+from capkit.model import Frame, LogMeta
+from capkit.readers.base import read_sample
+
+
+class CandumpReader:
+    """Read the can-utils log format emitted by ``candump -L``."""
+
+    name = "candump"
+    extensions = (".log",)
+
+    _ERROR_FLAG = 0x20000000
+    _FRAME_RE = re.compile(
+        r"^\s*"
+        r"\((?P<timestamp>\d+(?:\.\d+)?)\)"
+        r"\s+(?P<interface>\S+)"
+        r"\s+(?P<identifier>[0-9A-Fa-f]{3}|[0-9A-Fa-f]{8})"
+        r"(?:"
+        r"##(?P<fd_flags>[0-9A-Fa-f])(?P<fd_data>(?:[0-9A-Fa-f]{2})*)"
+        r"|#(?:[Rr](?P<remote_dlc>[0-9A-Fa-f]?)|(?P<data>(?:[0-9A-Fa-f]{2})*))"
+        r")"
+        r"(?:\s+(?P<direction>[RrTt]))?"
+        r"\s*$"
+    )
+
+    def __init__(self, *, strict: bool = False) -> None:
+        self.strict = strict
+
+    @staticmethod
+    def _channel(interface: str) -> int | None:
+        match = re.search(r"(\d+)$", interface)
+        return int(match.group(1)) if match is not None else None
+
+    @staticmethod
+    def _is_rx(direction: str | None) -> bool | None:
+        if direction is None:
+            return None
+        return direction.upper() == "R"
+
+    @classmethod
+    def _is_error_frame(cls, match: Match[str]) -> bool:
+        return bool(int(match.group("identifier"), 16) & cls._ERROR_FLAG)
+
+    def sniff(self, sample: str) -> bool:
+        """Recognize a complete can-utils log record."""
+        return any(self._FRAME_RE.fullmatch(line) is not None for line in sample.splitlines())
+
+    def probe(self, path: Path) -> LogMeta:
+        """Return candump metadata after validating a bounded sample."""
+        if not self.sniff(read_sample(path)):
+            raise ValueError(f"File '{path.name}' is not a candump log.")
+        return LogMeta(format=self.name)
+
+    def _frame(self, match: Match[str]) -> Frame:
+        identifier = match.group("identifier")
+        fd_flags = match.group("fd_flags")
+        remote_dlc = match.group("remote_dlc")
+        is_fd = fd_flags is not None
+        is_remote = remote_dlc is not None
+        flags = int(fd_flags, 16) if fd_flags is not None else 0
+        data_hex = match.group("fd_data") if is_fd else match.group("data")
+
+        return Frame(
+            timestamp=float(match.group("timestamp")),
+            arbitration_id=int(identifier, 16),
+            data=bytes.fromhex(data_hex or ""),
+            channel=self._channel(match.group("interface")),
+            is_extended_frame=len(identifier) == 8,
+            is_fd=is_fd,
+            is_remote_frame=is_remote,
+            is_rx=self._is_rx(match.group("direction")),
+            dlc=int(remote_dlc, 16) if remote_dlc else None,
+            bitrate_switch=bool(flags & 0x1),
+            error_state_indicator=bool(flags & 0x2),
+        )
+
+    def read(self, path: Path) -> Iterator[Frame]:
+        """Lazily parse can-utils frame records from *path*."""
+        with path.open(encoding="latin-1") as stream:
+            for line_number, raw_line in enumerate(stream, start=1):
+                line = raw_line.rstrip("\r\n")
+                if not line.strip():
+                    continue
+
+                match = self._FRAME_RE.fullmatch(line)
+                if match is None or self._is_error_frame(match):
+                    if self.strict:
+                        raise ValueError(f"Unrecognized candump line {line_number}: {line!r}.")
+                    continue
+
+                yield self._frame(match)