capkit 0.1.0__tar.gz

capkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+    branches: ["main", "master"]
+
+jobs:
+  test:
+    name: "Test (Python ${{ matrix.python-version }})"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Type-check
+        run: mypy capkit
+
+      - name: Test and coverage gate
+        run: python -m pytest --cov=capkit --cov-fail-under=90 -q
+
+  build:
+    name: Build check
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install build frontend
+        run: python -m pip install build
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Verify wheel metadata
+        run: >-
+          python -c "from pathlib import Path;
+          import zipfile;
+          wheel=next(Path('dist').glob('*.whl'));
+          archive=zipfile.ZipFile(wheel);
+          names=archive.namelist();
+          assert 'capkit/py.typed' in names;
+          entry=next(name for name in names if name.endswith('entry_points.txt'));
+          text=archive.read(entry).decode();
+          assert '[dbckit.readers]' in text;
+          assert 'txt = capkit.integration:DispatchReader' in text"

capkit-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: "Build distributions"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build
+        run: pip install build
+      - name: Build sdist and wheel
+        run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: "Publish to PyPI"
+    runs-on: ubuntu-latest
+    needs: build
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish (trusted publishing / OIDC)
+        uses: pypa/gh-action-pypi-publish@release/v1

capkit-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+.DS_Store
+
+.claude/
+.venv/
+__pycache__/
+*.py[cod]
+
+.env
+.env.*
+!.env.example
+
+.tox/
+.nox/
+.hypothesis/
+
+.pytest_cache/
+.coverage
+coverage.xml
+junit.xml
+htmlcov/
+
+.mypy_cache/
+.ruff_cache/
+
+dist/
+build/
+*.egg-info/
+
+DEFINITION.md

capkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to capkit are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning will follow [Semantic Versioning](https://semver.org/) from 1.0.0 onward.
+
+---
+
+## [Unreleased]
+
+## [0.1.0] — 2026-07-16
+
+Initial public release.
+
+### Added
+
+- Frozen, slotted `Frame` and `LogMeta` models; no runtime dependencies.
+- Lazy `read()`, header-only `probe()`, and `available_formats()`.
+- Public `register_reader()` for validated, process-wide custom reader classes.
+- Kvaser CanKing TXT reader (`kvaser-txt`) with noise-skipping and strict modes,
+  pinned by an anonymized excerpt of a real capture.
+- Generic `.txt` dispatch through the `dbckit.readers` entry-point group.
+- `py.typed` typing metadata.
+- CI on Python 3.11–3.14: pytest with coverage ≥ 90%, ruff, mypy, and a wheel
+  metadata build check.
+- Tag-driven release workflow publishing to PyPI with trusted publishing (OIDC).

capkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 André Delgado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

capkit-0.1.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: capkit
+Version: 0.1.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
+Project-URL: Changelog, https://github.com/canforge/capkit/blob/main/CHANGELOG.md
+Author-email: André Delgado <andre@adelgado.io>
+License: MIT License
+        
+        Copyright (c) 2026 André Delgado
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: CAN,automotive,canbus,kvaser,log
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+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: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# capkit
+
+[![PyPI](https://img.shields.io/pypi/v/capkit)](https://pypi.org/project/capkit/)
+[![CI](https://github.com/canforge/capkit/actions/workflows/ci.yml/badge.svg)](https://github.com/canforge/capkit/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/capkit)](https://pypi.org/project/capkit/)
+[![License: MIT](https://img.shields.io/pypi/l/capkit)](LICENSE)
+
+`capkit` is a Python library that reads **CAN bus capture logs into one common
+frame stream**. Every supported format parses into the same frozen `Frame`
+dataclass, so code that consumes frames never depends on which tool captured
+the log.
+
+Use it to:
+
+- read captures from different tools as one lazy stream of typed `Frame` objects
+- probe a file for header metadata without scanning the frame body
+- detect the log format from the file extension or the file content
+- skip real-world log noise by default, or reject it with `strict=True`
+- feed frames into [dbckit](https://github.com/canforge/dbckit) for DBC signal decoding
+
+| 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 |
+| PCAN TRC | `pcan-trc` | `.trc` | Planned | none |
+| Generic CSV | `csv-table` | `.csv` | Planned | none |
+| Vector BLF | `vector-blf` | `.blf` | Planned adapter | `python-can` |
+| ASAM MF4 | `asam-mf4` | `.mf4` | Planned adapter | `asammdf` |
+
+See [format support](docs/format-support.md) for the exact dialect each reader
+accepts, and the [roadmap](ROADMAP.md) for sequencing.
+
+## Install
+
+```bash
+pip install capkit
+```
+
+Requires Python `>=3.11`. capkit has no runtime dependencies.
+
+## Design
+
+- `Frame` and `LogMeta` are frozen, slotted dataclasses.
+- `read()` is lazy and keeps constant parser state, so file size does not matter.
+- Timestamps are returned exactly as recorded in the source, never rebased or
+  converted to absolute time.
+- A format is added only when a real captured fixture pins its dialect under
+  `tests/fixtures/`; unsupported dialects fail clearly instead of parsing
+  approximately.
+
+## Quick Start
+
+```python
+import capkit
+
+# stream frames
+for frame in capkit.read("trace.txt"):
+    print(frame.timestamp, hex(frame.arbitration_id), frame.data.hex())
+
+# header metadata only
+meta = capkit.probe("trace.txt")
+print(meta.format, meta.start_time)
+
+# registered reader names
+print(capkit.available_formats())   # ['kvaser-txt']
+```
+
+The public API is six names: `read`, `probe`, `available_formats`,
+`register_reader`, `Frame`, and `LogMeta`.
+
+## Features
+
+### Format detection
+
+An explicit `format=` names a reader and takes precedence over the file
+extension:
+
+```python
+frames = capkit.read("capture.bin", format="kvaser-txt")
+```
+
+Without `format=`, capkit matches the extension against registered readers and
+sniffs the first 4 KiB when the extension is unknown or ambiguous.
+
+### Add your own reader
+
+Register a zero-argument reader class to make it available to `read()`,
+`probe()`, and format detection:
+
+```python
+from collections.abc import Iterator
+from pathlib import Path
+
+import capkit
+
+
+class MyReader:
+    name: str = "my-format"
+    extensions: tuple[str, ...] = (".mylog",)
+
+    def __init__(self, *, strict: bool = False) -> None:
+        self.strict = strict
+
+    def sniff(self, sample: str) -> bool:
+        return sample.startswith("MYLOG")
+
+    def probe(self, path: Path) -> capkit.LogMeta:
+        return capkit.LogMeta(format=self.name)
+
+    def read(self, path: Path) -> Iterator[capkit.Frame]:
+        # Parse path lazily and yield capkit.Frame objects here.
+        yield from ()
+
+
+capkit.register_reader(MyReader)
+```
+
+Registration is process-global and is normally performed at import time.
+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.
+
+### Dirty logs and strict mode
+
+Readers skip headers, trailers, comments, blank lines, and unrelated noise by
+default. Pass `strict=True` to raise a line-numbered `ValueError` on the first
+unrecognized nonblank line instead:
+
+```python
+frames = capkit.read("trace.txt", strict=True)
+```
+
+A frame record whose DLC disagrees with its data bytes raises in both modes;
+corrupt frames are never silently dropped.
+
+## Use with dbckit
+
+[dbckit](https://github.com/canforge/dbckit) decodes CAN frames against a DBC
+database. capkit and dbckit are separate packages — neither depends on or
+imports the other — with adjacent jobs: capkit turns bytes on disk into frames,
+dbckit turns frames plus a DBC into signals.
+
+```python
+import capkit
+import dbckit
+
+db = dbckit.load("truck.dbc")
+for decoded in dbckit.decode_frames(db, capkit.read("trace.txt")):
+    print(decoded.timestamp, decoded.signals)
+```
+
+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:
+
+```python
+for decoded in dbckit.decode_log(db, "trace.txt"):
+    print(decoded.signals)
+```
+
+## Scope and Caveats
+
+- Kvaser dialects with absolute start-time headers are not supported;
+  `probe()` returns `start_time=None` for `kvaser-txt`.
+- 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.
+
+## Documentation
+
+- [Format support](docs/format-support.md) — supported formats and the exact
+  dialect each reader accepts
+- [API reference](docs/api-reference.md) — the public API contract
+- [Recipes](docs/recipes.md) — counting IDs, filtering, time windows, CSV
+  export, and dataframes in a few lines of standard library
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+The `dev` extra includes dbckit so the entry-point integration tests run; the
+core and contract suites pass without it.
+
+## License
+
+MIT

capkit-0.1.0/README.md

@@ -0,0 +1,191 @@
+# capkit
+
+[![PyPI](https://img.shields.io/pypi/v/capkit)](https://pypi.org/project/capkit/)
+[![CI](https://github.com/canforge/capkit/actions/workflows/ci.yml/badge.svg)](https://github.com/canforge/capkit/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/capkit)](https://pypi.org/project/capkit/)
+[![License: MIT](https://img.shields.io/pypi/l/capkit)](LICENSE)
+
+`capkit` is a Python library that reads **CAN bus capture logs into one common
+frame stream**. Every supported format parses into the same frozen `Frame`
+dataclass, so code that consumes frames never depends on which tool captured
+the log.
+
+Use it to:
+
+- read captures from different tools as one lazy stream of typed `Frame` objects
+- probe a file for header metadata without scanning the frame body
+- detect the log format from the file extension or the file content
+- skip real-world log noise by default, or reject it with `strict=True`
+- feed frames into [dbckit](https://github.com/canforge/dbckit) for DBC signal decoding
+
+| 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 |
+| PCAN TRC | `pcan-trc` | `.trc` | Planned | none |
+| Generic CSV | `csv-table` | `.csv` | Planned | none |
+| Vector BLF | `vector-blf` | `.blf` | Planned adapter | `python-can` |
+| ASAM MF4 | `asam-mf4` | `.mf4` | Planned adapter | `asammdf` |
+
+See [format support](docs/format-support.md) for the exact dialect each reader
+accepts, and the [roadmap](ROADMAP.md) for sequencing.
+
+## Install
+
+```bash
+pip install capkit
+```
+
+Requires Python `>=3.11`. capkit has no runtime dependencies.
+
+## Design
+
+- `Frame` and `LogMeta` are frozen, slotted dataclasses.
+- `read()` is lazy and keeps constant parser state, so file size does not matter.
+- Timestamps are returned exactly as recorded in the source, never rebased or
+  converted to absolute time.
+- A format is added only when a real captured fixture pins its dialect under
+  `tests/fixtures/`; unsupported dialects fail clearly instead of parsing
+  approximately.
+
+## Quick Start
+
+```python
+import capkit
+
+# stream frames
+for frame in capkit.read("trace.txt"):
+    print(frame.timestamp, hex(frame.arbitration_id), frame.data.hex())
+
+# header metadata only
+meta = capkit.probe("trace.txt")
+print(meta.format, meta.start_time)
+
+# registered reader names
+print(capkit.available_formats())   # ['kvaser-txt']
+```
+
+The public API is six names: `read`, `probe`, `available_formats`,
+`register_reader`, `Frame`, and `LogMeta`.
+
+## Features
+
+### Format detection
+
+An explicit `format=` names a reader and takes precedence over the file
+extension:
+
+```python
+frames = capkit.read("capture.bin", format="kvaser-txt")
+```
+
+Without `format=`, capkit matches the extension against registered readers and
+sniffs the first 4 KiB when the extension is unknown or ambiguous.
+
+### Add your own reader
+
+Register a zero-argument reader class to make it available to `read()`,
+`probe()`, and format detection:
+
+```python
+from collections.abc import Iterator
+from pathlib import Path
+
+import capkit
+
+
+class MyReader:
+    name: str = "my-format"
+    extensions: tuple[str, ...] = (".mylog",)
+
+    def __init__(self, *, strict: bool = False) -> None:
+        self.strict = strict
+
+    def sniff(self, sample: str) -> bool:
+        return sample.startswith("MYLOG")
+
+    def probe(self, path: Path) -> capkit.LogMeta:
+        return capkit.LogMeta(format=self.name)
+
+    def read(self, path: Path) -> Iterator[capkit.Frame]:
+        # Parse path lazily and yield capkit.Frame objects here.
+        yield from ()
+
+
+capkit.register_reader(MyReader)
+```
+
+Registration is process-global and is normally performed at import time.
+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.
+
+### Dirty logs and strict mode
+
+Readers skip headers, trailers, comments, blank lines, and unrelated noise by
+default. Pass `strict=True` to raise a line-numbered `ValueError` on the first
+unrecognized nonblank line instead:
+
+```python
+frames = capkit.read("trace.txt", strict=True)
+```
+
+A frame record whose DLC disagrees with its data bytes raises in both modes;
+corrupt frames are never silently dropped.
+
+## Use with dbckit
+
+[dbckit](https://github.com/canforge/dbckit) decodes CAN frames against a DBC
+database. capkit and dbckit are separate packages — neither depends on or
+imports the other — with adjacent jobs: capkit turns bytes on disk into frames,
+dbckit turns frames plus a DBC into signals.
+
+```python
+import capkit
+import dbckit
+
+db = dbckit.load("truck.dbc")
+for decoded in dbckit.decode_frames(db, capkit.read("trace.txt")):
+    print(decoded.timestamp, decoded.signals)
+```
+
+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:
+
+```python
+for decoded in dbckit.decode_log(db, "trace.txt"):
+    print(decoded.signals)
+```
+
+## Scope and Caveats
+
+- Kvaser dialects with absolute start-time headers are not supported;
+  `probe()` returns `start_time=None` for `kvaser-txt`.
+- 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.
+
+## Documentation
+
+- [Format support](docs/format-support.md) — supported formats and the exact
+  dialect each reader accepts
+- [API reference](docs/api-reference.md) — the public API contract
+- [Recipes](docs/recipes.md) — counting IDs, filtering, time windows, CSV
+  export, and dataframes in a few lines of standard library
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+The `dev` extra includes dbckit so the entry-point integration tests run; the
+core and contract suites pass without it.
+
+## License
+
+MIT

capkit-0.1.0/ROADMAP.md

@@ -0,0 +1,71 @@
+# Roadmap
+
+Readers are fixture-first: a format lands only with a real capture under
+`tests/fixtures/<format>/`.
+
+## Publish 0.1.0 to PyPI
+
+- [x] **1. Add `.github/workflows/release.yml`**: trigger on `v*` tags; build sdist + wheel;
+  publish with `pypa/gh-action-pypi-publish` using OIDC (`permissions: id-token: write`,
+  environment `pypi`) — no API tokens
+- [ ] **2. Register the trusted publisher on pypi.org** *(manual)*: add a *pending publisher*
+  for `canforge/capkit`, workflow `release.yml`, environment `pypi`, and create the protected
+  `pypi` environment in the GitHub repository settings
+- [ ] **3. Optional TestPyPI dry run**: point a copy of the workflow at TestPyPI, publish,
+  `pip install -i https://test.pypi.org/simple/ capkit`
+- [x] **4. Date the `0.1.0` changelog section** and match the `pyproject.toml` version
+- [x] **5. Merge to `main` and push**
+- [ ] **6. Tag and release**: `git tag -a v0.1.0 -m "Release 0.1.0" && git push origin v0.1.0` —
+  the workflow builds and publishes
+- [ ] **7. Verify the release**
+  - [ ] In a clean venv: `pip install capkit` then
+    `python -c "import capkit; print(capkit.available_formats())"`
+  - [ ] With dbckit installed alongside, `dbckit.decode_log(db, "trace.txt")` resolves
+    capkit's `.txt` entry point
+  - [ ] PyPI page shows license, links, and README correctly
+
+## Planned readers
+
+- [ ] candump text (`.log`)
+- [ ] Vector ASC (`.asc`)
+- [ ] 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
+
+- [ ] A `capkit.readers` entry-point group, so installed third-party formats are
+  discovered automatically without import-time registration
+- [ ] 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
+- [ ] CAN FD flags on `Frame` (bit-rate switch, error-state indicator) when the first FD
+  fixture lands
+
+## 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/__init__.py

@@ -0,0 +1,13 @@
+"""Read CAN log files into a common stream of frame objects."""
+from __future__ import annotations
+
+from capkit.io import available_formats, probe, read
+from capkit.model import Frame, LogMeta
+from capkit.readers import register_reader
+
+__all__ = [
+    # model
+    "Frame", "LogMeta",
+    # io
+    "read", "probe", "available_formats", "register_reader",
+]