cantcp 0.1.0__py3-none-any.whl

cantcp/__init__.py

@@ -0,0 +1,74 @@
+r"""Python library for the cantcp protocol.
+
+The package carries CAN frames only: stream framing of raw SocketCAN frames
+in a byte stream, plus parsing, encoding and decoding of Linux SocketCAN
+frames. Connection setup is plain TCP: handshakes, subscriptions, keepalives,
+statistics and health checks are not part of the protocol.
+
+Quick start:
+
+    >>> import io
+    >>> import cantcp
+    >>> stream = io.BytesIO()
+    >>> frame = cantcp.Frame(type=cantcp.Type.CLASSIC, id=0x123, data=bytes.fromhex("dead"))
+    >>> cantcp.Encoder(stream).encode_frame(frame)
+    >>> print(next(iter(cantcp.Decoder(io.BytesIO(stream.getvalue())))))
+    Frame{Type:CAN, ID:0x123, Flags:none, DLC:2, Data:dead}
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from cantcp.crc_cover import CrcCover
+from cantcp.decoder import Decoder
+from cantcp.encoder import Encoder
+from cantcp.errors import (
+    BadDLCError,
+    BadFlagsError,
+    BadIDError,
+    BadLenError,
+    BadTypeError,
+    CantcpError,
+    FrameLenError,
+    ReservedError,
+    ShortWriteError,
+    TruncatedError,
+)
+from cantcp.flags import Flag
+from cantcp.frame import Frame
+from cantcp.logger import TRACE
+from cantcp.parser import Parser
+from cantcp.policy import BadFramePolicy
+from cantcp.stats import Stats
+from cantcp.type import Type
+from cantcp.validate import validate_raw
+
+try:
+    __version__ = version("cantcp")
+except PackageNotFoundError:  # pragma: no cover - the package is not installed
+    __version__ = "0.0.0"
+
+__all__ = [
+    "TRACE",
+    "BadDLCError",
+    "BadFlagsError",
+    "BadFramePolicy",
+    "BadIDError",
+    "BadLenError",
+    "BadTypeError",
+    "CantcpError",
+    "CrcCover",
+    "Decoder",
+    "Encoder",
+    "Flag",
+    "Frame",
+    "FrameLenError",
+    "Parser",
+    "ReservedError",
+    "ShortWriteError",
+    "Stats",
+    "TruncatedError",
+    "Type",
+    "validate_raw",
+]

cantcp/crc8.py

@@ -0,0 +1,39 @@
+"""Table-driven CRC-8 with a configurable polynomial.
+
+The default polynomial 0x07 is CRC-8/SMBus: init 0x00, no input or output
+reflection, no final XOR. The table is built per instance, nothing is shared
+globally.
+"""
+
+from __future__ import annotations
+
+_TABLE_SIZE = 256
+_BITS_PER_BYTE = 8
+_BYTE_MASK = 0xFF
+_TOP_BIT = 0x80
+
+
+class _CRC8:
+    """A CRC-8 calculator with its own lookup table."""
+
+    __slots__ = ("_table",)
+
+    def __init__(self, poly: int) -> None:
+        table = []
+        for index in range(_TABLE_SIZE):
+            value = index
+            for _ in range(_BITS_PER_BYTE):
+                if value & _TOP_BIT:
+                    value = (value << 1) ^ poly
+                else:
+                    value <<= 1
+                value &= _BYTE_MASK
+            table.append(value)
+        self._table = tuple(table)
+
+    def sum(self, data: bytes) -> int:
+        """Return the CRC-8 of ``data``."""
+        value = 0
+        for byte in data:
+            value = self._table[value ^ byte]
+        return value

cantcp/crc_cover.py

@@ -0,0 +1,15 @@
+"""Which part of a packet the CRC-8 covers."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class CrcCover(Enum):
+    """The byte span covered by the CRC-8 of a packet."""
+
+    HEADER = "magic+type+frame"
+    """Magic, packet type byte and the raw frame (the default)."""
+
+    FRAME = "frame"
+    """The raw frame only."""

cantcp/decoder.py

@@ -0,0 +1,138 @@
+"""The Decoder object: reading framed CAN frames from a binary stream."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+from typing import BinaryIO
+
+from cantcp.crc_cover import CrcCover
+from cantcp.errors import CantcpError
+from cantcp.frame import Frame
+from cantcp.parser import _FD_PACKET_LEN, Parser
+from cantcp.policy import BadFramePolicy
+from cantcp.stats import Stats
+
+
+class Decoder:
+    """Read framed CAN packets from a binary stream.
+
+        [magic 2 bytes][type 1 byte][struct can_frame 16 | canfd_frame 72][CRC-8 1]
+
+    Garbage and packets rejected by the CRC are dropped, stream counters are
+    collected and every call returns one raw frame. A decoder is not safe for
+    concurrent use: use one decoder per stream.
+
+        >>> import io
+        >>> raw = bytes(16)
+        >>> decoder = Decoder(io.BytesIO(Parser().encode(raw)))
+        >>> decoder.decode() == raw
+        True
+        >>> decoder.decode() is None
+        True
+
+    Iteration yields parsed :class:`cantcp.Frame` objects:
+
+        >>> import io
+        >>> stream = io.BytesIO(Parser().encode(bytes(16)))
+        >>> print(next(iter(Decoder(stream))))
+        Frame{Type:CAN, ID:0x0, Flags:none, DLC:0, Data:}
+    """
+
+    __slots__ = ("_buffer", "_failure", "_parser", "_reader")
+
+    def __init__(
+        self,
+        reader: BinaryIO,
+        *,
+        magic: bytes = b"\xc3\x3c",
+        crc_poly: int = 0x07,
+        crc_cover: CrcCover = CrcCover.HEADER,
+        bad_frame_policy: BadFramePolicy = BadFramePolicy.SKIP,
+        logger: logging.Logger | None = None,
+        log_level: int = logging.INFO,
+    ) -> None:
+        """Create a decoder reading from ``reader``.
+
+        Options configure the internal parser exactly like
+        :class:`cantcp.Parser`. The reader is owned by the caller: the decoder
+        never closes it.
+        """
+        self._reader = reader
+        self._parser = Parser(
+            magic=magic,
+            crc_poly=crc_poly,
+            crc_cover=crc_cover,
+            bad_frame_policy=bad_frame_policy,
+            logger=logger,
+            log_level=log_level,
+        )
+        self._buffer = bytearray()
+        self._failure: CantcpError | None = None
+
+    def decode(self) -> bytes | None:
+        """Return the next raw frame or ``None`` at the end of the stream.
+
+        The returned bytes are independent of the decoder buffer and stay
+        valid after the next call. A packet cut off in the middle raises
+        :class:`cantcp.TruncatedError`; errors of the underlying reader are
+        propagated unchanged. After a terminal error every call raises the
+        same error, like a spent scanner.
+        """
+        return self._next_raw()
+
+    def decode_frame(self) -> Frame | None:
+        """Return the next frame parsed into a :class:`cantcp.Frame`.
+
+        The parsing is as strict as :meth:`cantcp.Frame.from_raw`: a CAN FD
+        length the 4-bit DLC field cannot encode raises
+        :class:`cantcp.BadLenError` even though the splitter accepted the
+        packet. ``None`` reports the end of the stream.
+        """
+        raw = self._next_raw()
+        if raw is None:
+            return None
+        return Frame.from_raw(raw)
+
+    def __iter__(self) -> Iterator[Frame]:
+        """Iterate over the frames of the stream."""
+        return self
+
+    def __next__(self) -> Frame:
+        """Return the next frame or raise :class:`StopIteration` at the end."""
+        frame = self.decode_frame()
+        if frame is None:
+            raise StopIteration
+        return frame
+
+    @property
+    def stats(self) -> Stats:
+        """A copy of the stream counters."""
+        return self._parser.stats
+
+    def reset_stats(self) -> None:
+        """Zero the stream counters."""
+        self._parser.reset_stats()
+
+    def _next_raw(self) -> bytes | None:
+        """Return the next raw frame, reading from the stream as needed."""
+        if self._failure is not None:
+            raise self._failure
+        final = False
+        while True:
+            try:
+                advance, token = self._parser.split(bytes(self._buffer), final)
+            except CantcpError as exc:
+                self._failure = exc
+                raise
+            if advance:
+                del self._buffer[:advance]
+            if token is not None:
+                return token
+            if final:
+                return None
+            chunk = self._reader.read(_FD_PACKET_LEN)
+            if not chunk:
+                final = True
+                continue
+            self._buffer.extend(chunk)

cantcp/encoder.py

@@ -0,0 +1,87 @@
+"""The Encoder object: writing framed CAN frames to a binary stream."""
+
+from __future__ import annotations
+
+import logging
+from typing import BinaryIO
+
+from cantcp.crc_cover import CrcCover
+from cantcp.errors import ShortWriteError
+from cantcp.frame import Frame
+from cantcp.parser import Parser
+from cantcp.policy import BadFramePolicy
+
+
+class Encoder:
+    """Write framed CAN packets to a binary stream.
+
+        [magic 2 bytes][type 1 byte][struct can_frame 16 | canfd_frame 72][CRC-8 1]
+
+    The encoder wraps :meth:`cantcp.Parser.encode`: the frame length selects
+    the packet type, the CRC-8 and its coverage follow the parser
+    configuration, so a packet written by an encoder is always accepted by a
+    decoder created with the same options. An encoder is not safe for
+    concurrent use: use one encoder per stream.
+
+        >>> import io
+        >>> stream = io.BytesIO()
+        >>> Encoder(stream).encode(bytes(16))
+        >>> stream.getvalue().hex()
+        'c33c010000000000000000000000000000000064'
+    """
+
+    __slots__ = ("_parser", "_writer")
+
+    def __init__(
+        self,
+        writer: BinaryIO,
+        *,
+        magic: bytes = b"\xc3\x3c",
+        crc_poly: int = 0x07,
+        crc_cover: CrcCover = CrcCover.HEADER,
+        bad_frame_policy: BadFramePolicy = BadFramePolicy.SKIP,
+        logger: logging.Logger | None = None,
+        log_level: int = logging.INFO,
+    ) -> None:
+        """Create an encoder writing to ``writer``.
+
+        Options configure the internal parser exactly like
+        :class:`cantcp.Parser`; ``bad_frame_policy``, ``logger`` and
+        ``log_level`` are accepted for symmetry with the reader side and do
+        not affect writing. The writer is owned by the caller: the encoder
+        never closes it.
+        """
+        self._writer = writer
+        self._parser = Parser(
+            magic=magic,
+            crc_poly=crc_poly,
+            crc_cover=crc_cover,
+            bad_frame_policy=bad_frame_policy,
+            logger=logger,
+            log_level=log_level,
+        )
+
+    def encode(self, frame: bytes) -> None:
+        """Write one packet carrying the raw ``frame``.
+
+        Validation errors of :meth:`cantcp.Parser.encode`
+        (:class:`cantcp.FrameLenError`, :class:`cantcp.BadDLCError`,
+        :class:`cantcp.BadLenError`) leave the stream untouched. A write that
+        stored fewer bytes than requested raises
+        :class:`cantcp.ShortWriteError`; a write error is propagated unchanged
+        and leaves the stream in an unknown state.
+        """
+        packet = self._parser.encode(frame)
+        written = self._writer.write(packet)
+        if written is None or written < len(packet):
+            raise ShortWriteError()
+
+    def encode_frame(self, frame: Frame) -> None:
+        """Write one packet carrying ``frame``.
+
+        The frame is marshalled with :meth:`cantcp.Frame.to_raw`; its errors
+        (:class:`cantcp.BadTypeError`, :class:`cantcp.BadIDError`,
+        :class:`cantcp.BadFlagsError`, :class:`cantcp.BadDLCError`,
+        :class:`cantcp.BadLenError`) leave the stream untouched.
+        """
+        self.encode(frame.to_raw())

cantcp/errors.py

@@ -0,0 +1,85 @@
+"""Errors raised by the cantcp package.
+
+Every protocol error is a subclass of :class:`CantcpError` with a static
+message; the texts are identical to the Go implementation of the library, so
+logs of both languages match. Catch a concrete class with ``except`` or the
+base class to handle all of them:
+
+    from cantcp import BadDLCError, CantcpError
+
+    try:
+        frame.to_raw()
+    except BadDLCError as exc:
+        print(exc)  # cantcp: can_dlc > 8
+    except CantcpError:
+        ...  # any other protocol error
+"""
+
+from __future__ import annotations
+
+
+class CantcpError(Exception):
+    """Base class for all errors raised by the cantcp package."""
+
+
+class FrameLenError(CantcpError):
+    """A frame is neither 16 (can_frame) nor 72 (canfd_frame) bytes."""
+
+    def __init__(self) -> None:
+        super().__init__("cantcp: frame length is not 16 or 72 bytes")
+
+
+class BadDLCError(CantcpError):
+    """A classic can_frame whose can_dlc is greater than 8."""
+
+    def __init__(self) -> None:
+        super().__init__("cantcp: can_dlc > 8")
+
+
+class BadLenError(CantcpError):
+    """An invalid CAN FD length: greater than 64 or not encodable in DLC."""
+
+    def __init__(self) -> None:
+        super().__init__("cantcp: invalid canfd length")
+
+
+class BadTypeError(CantcpError):
+    """An unknown frame type: not classic CAN and not CAN FD."""
+
+    def __init__(self) -> None:
+        super().__init__("cantcp: unknown frame type")
+
+
+class BadFlagsError(CantcpError):
+    """Flags that are not valid for the frame type."""
+
+    def __init__(self) -> None:
+        super().__init__("cantcp: flags are not valid for the frame type")
+
+
+class BadIDError(CantcpError):
+    """An identifier that does not fit the addressing mode."""
+
+    def __init__(self) -> None:
+        super().__init__("cantcp: identifier does not fit the addressing mode")
+
+
+class ReservedError(CantcpError):
+    """Non-zero reserved or padding bytes of a frame."""
+
+    def __init__(self) -> None:
+        super().__init__("cantcp: reserved bytes are not zero")
+
+
+class TruncatedError(CantcpError):
+    """An incomplete packet at the end of the stream."""
+
+    def __init__(self) -> None:
+        super().__init__("cantcp: stream truncated in the middle of a packet")
+
+
+class ShortWriteError(CantcpError):
+    """A write wrote fewer bytes than requested."""
+
+    def __init__(self) -> None:
+        super().__init__("cantcp: short write")

cantcp/flags.py

@@ -0,0 +1,31 @@
+"""The Flag bits of a Frame."""
+
+from __future__ import annotations
+
+from enum import IntFlag
+
+
+class Flag(IntFlag):
+    """Flag bits of a Frame, combined with bitwise OR.
+
+    ``EFF``, ``RTR`` and ``ERR`` come from the CAN identifier word; ``BRS``
+    and ``ESI`` come from the CAN FD flags byte. The constants are the
+    argument of :meth:`cantcp.Frame.set_flags`:
+
+        frame.set_flags(Flag.EFF | Flag.RTR)
+    """
+
+    EFF = 1 << 0
+    """Extended (29-bit) identifier."""
+
+    RTR = 1 << 1
+    """Remote transmission request (classic CAN only)."""
+
+    ERR = 1 << 2
+    """Error frame (carries no addressing mode)."""
+
+    BRS = 1 << 3
+    """CAN FD bit rate switch."""
+
+    ESI = 1 << 4
+    """CAN FD error state indicator."""