# hardbyte/python-can architecture

> Architecture diagram of the GitHub repository hardbyte/python-can, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hardbyte/python-can
- Repository: https://github.com/hardbyte/python-can

## Overview

##### Main Components
- Core Library: The central “can” package contains the primary abstractions and utilities. Key modules include:
– Bus: Responsible for representing and managing CAN bus interactions.
– Message: Handling CAN frame/message definitions (arbitration IDs, data, logging, etc.).
– Notifier, Logger, and Player: Managing asynchronous notifications and logging functionalities.
– Utility modules (e.g., typechecking, threading support, bit_timing calculations).
- Interface Drivers: Under the “can/interfaces” directory there are multiple subdirectories for various CAN interface implementations such as:
– canalystii, cantact, etas, ics_neovi, ixxat, kvaser, neousys, nican, nixnet, pcan, robotell, seeedstudio, serial, slcan, socketcan, socketcand, systec, udp_multicast, usb2can, vector, and virtual.
– Each interface module encapsulates interactions with a specific hardware/software vendor’s CAN driver.
- Input/Output Utilities: The “can/io” subdirectory includes modules to support multiple logging and file formats (ASC, BLF, CSV, SQLite, etc.) for logging or replaying CAN messages.
- Supplementary Components:
– Command-line interface and entry-point management (e.g., _entry_points.py) to support direct invocation.
– Extensions for asynchronous operations (see examples in doc/asyncio.rst and examples/asyncio_demo.py).
– Testing and Documentation: Separate directories (test, doc, examples) help verify behavior and provide usage details.

##### Out Relationships and Interactions
– Instantiating and managing Bus objects.
– Providing a common API for sending, receiving, and filtering messages.
– Each CAN interface subtype (e.g., socketcan, kvaser, ixxat) implements platform‑specific logic.
– Use a “strategy” or “plugin” pattern to indicate that the core library selects an appropriate interface driver based on configuration or environment variables.
- Optionally, indicate testing and documentation as peripheral “support” layers that ensure the quality and correctness of the code but are not directly part of the core runtime.

##### Architectural Patterns and Design Principles
- Modular and Pluggable Design: Emphasize that each CAN interface is isolated into its own module. This supports extensibility (new interfaces can be added without modifying the core).
- Abstraction and Encapsulation: The library decouples the application-level API (Bus, Message, Notifier) from the underlying hardware-specific implementations.
- Use of Utility and Helper Modules: Show how separate utility modules (for bit timing, type checking, etc.) support the primary functionalities.

##### Detail Relevant Technologies and Frameworks
- Python language features (with support for CPython and PyPy) and version-specific requirements.
- Integration with external logging and file I/O utilities supporting various CAN file formats.
- The design also uses common automation and CI integrations as seen in the repository (e.g., GitHub Actions, tox configurations), though these are auxiliary to the system’s runtime architecture.

- Clear labels indicating core components such as “CAN Core Library,” “Interface Drivers,” “IO Utilities,” and “CLI/Entry Points.”
– From external user/application code into the Bus creation API.
– From the core library to various interface implementations (highlighting pluggable design).
– From the core library to logging and IO subsystems.
- Annotations or notes that mention the underlying patterns (plugin architecture, event‑driven design) as well as configuration approaches (using environment variables or file-based configuration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    subgraph "External"
        APP["Application/Client Code"]:::client
    end

    %% Core Layer
    subgraph "Core Layer"
        CAPI["CAN Core API"]:::core
        BUS["Bus Abstraction"]:::core
        MSG["Message Handling"]:::core
        NOTIF["Asynchronous Notification"]:::core
        LOG["Logging Utilities"]:::core
        PLAYER["Message Player"]:::core
    end

    %% Utility Modules
    subgraph "Utility Modules"
        BIT["Bit Timing (Utility)"]:::utility
        TYPE["Typechecking (Utility)"]:::utility
        UTIL["General Utilities"]:::utility
        TSBUS["Thread-Safe Bus"]:::utility
    end

    %% Interface Drivers
    subgraph "Interface Drivers"
        IFACE["CAN Interface Drivers"]:::driver
    end

    %% IO Utilities
    subgraph "IO Utilities"
        IO["File Formats & Replay Utilities"]:::io
    end

    %% CLI / Entry Points
    subgraph "CLI & Entry Points"
        CLI["CLI/Entry Points"]:::cli
    end

    %% Support Layer
    subgraph "Support"
        TEST["Testing Suite"]:::support
        DOC["Documentation"]:::support
    end

    %% Connections
    APP -->|"uses"| CAPI
    CAPI -->|"bus"| BUS
    CAPI -->|"message"| MSG
    CAPI -->|"notify"| NOTIF
    CAPI -->|"log"| LOG
    CAPI -->|"player"| PLAYER
    CAPI -->|"selects"| IFACE
    CAPI -->|"iolog"| IO
    CAPI -->|"utilizes"| BIT
    CAPI -->|"utilizes"| TYPE
    CAPI -->|"utilizes"| UTIL
    CAPI -->|"utilizes"| TSBUS
    APP -->|"executes"| CLI
    APP -->|"verifies"| TEST
    APP -->|"refers"| DOC

    %% Click Events
    click CAPI "https://github.com/hardbyte/python-can/tree/main/can"
    click BUS "https://github.com/hardbyte/python-can/blob/main/can/bus.py"
    click MSG "https://github.com/hardbyte/python-can/blob/main/can/message.py"
    click NOTIF "https://github.com/hardbyte/python-can/blob/main/can/notifier.py"
    click LOG "https://github.com/hardbyte/python-can/blob/main/can/logger.py"
    click BIT "https://github.com/hardbyte/python-can/blob/main/can/bit_timing.py"
    click TYPE "https://github.com/hardbyte/python-can/blob/main/can/typechecking.py"
    click UTIL "https://github.com/hardbyte/python-can/blob/main/can/util.py"
    click TSBUS "https://github.com/hardbyte/python-can/blob/main/can/thread_safe_bus.py"
    click IFACE "https://github.com/hardbyte/python-can/tree/main/can/interfaces"
    click IO "https://github.com/hardbyte/python-can/tree/main/can/io"
    click CLI "https://github.com/hardbyte/python-can/blob/main/can/_entry_points.py"
    click TEST "https://github.com/hardbyte/python-can/tree/main/test"
    click DOC "https://github.com/hardbyte/python-can/tree/main/doc"

    %% Styles
    classDef client fill:#FFF3E0,stroke:#E65100,stroke-width:2px;
    classDef core fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef utility fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef driver fill:#FFE082,stroke:#F9A825,stroke-width:2px;
    classDef io fill:#E1BEE7,stroke:#6A1B9A,stroke-width:2px;
    classDef cli fill:#FFCDD2,stroke:#B71C1C,stroke-width:2px;
    classDef support fill:#EEEEEE,stroke:#757575,stroke-width:2px;
```
