Core API Reference

exception icspacket.core.connection.ConnectionError

Base exception for all connection-related errors.

Subclasses provide more specific context, e.g. closed connections or invalid states. Intended for use by higher-level protocol handlers to unify error handling across different transports.

exception icspacket.core.connection.ConnectionClosedError

Raised when an operation is attempted on a connection that has already been cleanly or forcibly closed.

exception icspacket.core.connection.ConnectionNotEstablished

Raised when an operation requires an active connection but none has been established yet.

Typically triggered by calling send_data() or recv_data() before connect().

exception icspacket.core.connection.ConnectionStateError

Raised when a connection is in an invalid state for the requested operation.

Examples include:

• Attempting to connect twice without closing.

• Attempting to reuse a connection marked invalid.

class icspacket.core.connection.connection

Generic base class for connection-oriented protocols.

Provides the essential API surface for establishing, validating, transmitting, and closing a connection. This base class does not assume any particular transport; concrete implementations must supply the mechanics (e.g., TCP sockets, serial lines, virtual channels).

is_connected() → bool

Check if the connection is established.

Returns:

True if the connection is currently open and usable, False otherwise.

Return type:

bool

is_valid() → bool

Verify whether the connection remains valid.

This flag is set by subclasses to indicate that the underlying transport is still operational. By default it returns the internal _valid attribute.

Returns:

True if the connection is marked valid, False otherwise.

Return type:

bool

connect(address: tuple[str, int]) → None

Establish the underlying connection.

Must be overridden by subclasses. Expected to perform protocol-specific setup such as TCP handshakes, serial port configuration, or security negotiation.

Parameters:

address (tuple[str, int]) – Target address or endpoint identifier. Typically a (host, port) tuple for TCP, but may vary by protocol.

Raises:

ConnectionError – If the connection attempt fails.

close() → None

Close the connection and update state.

Must be overridden by subclasses. Should ensure resources are released and internal flags are reset.

Raises:

ConnectionError – If closing fails or is unsupported.

send_data(octets: bytes, /) → None

Send raw data over the connection.

Must be implemented by subclasses to handle transport-specific framing and transmission.

Parameters:

octets (bytes) – Byte string to send across the connection.

Raises:

• ConnectionNotEstablished – If no active connection exists.

• ConnectionClosedError – If the connection was closed during transmission.

recv_data() → bytes

Receive raw data from the connection.

Must be implemented by subclasses. Expected to block or wait until at least one unit of data is available, depending on transport semantics.

Returns:

The received octets.

Return type:

bytes

Raises:

• ConnectionNotEstablished – If called before connection setup.

• ConnectionClosedError – If the connection was closed while awaiting data.

icspacket.core.logger.SAFE = <object object>

Sentinel object used to mark log messages that should be escaped to prevent Rich markup injection.

icspacket.core.logger.TRACE = 5

Custom logging level for trace messages, numerically below DEBUG (value = 5). These messages will appear when using -vvv verbosity.

icspacket.core.logger.TRACE_PACKETS = 4

Custom logging level to trace packets, numerically below TRACE (value = 4). These messages will appear when using -vvvv verbosity.

Added in version 0.2.0.

class icspacket.core.logger.PrefixFormatter

Custom log formatter that injects colored prefixes and safely handles message escaping.

format(record)

Format a log record by injecting a prefix and optionally escaping the message.

icspacket.core.logger.init(ts=False, level: int = 20)

Initialize the global logging system with Rich-based formatting.

Can optionally show timestamps.

Parameters:

• ts (bool) – Whether to include timestamps in log messages.

• level (int) – Logging level to configure for the root logger.

icspacket.core.logger.init_from_args(verbosity: int, quiet: bool, ts: bool)

Initialize logging from CLI-like verbosity/quiet flags.

This helper interprets CLI verbosity levels into logging levels:

• verbosity = 0 -> INFO

• verbosity = 1 -> DEBUG

• verbosity = 2 -> TRACE

• verbosity >= 3 -> TRACE_PACKETS

• quiet = True -> force ERROR regardless of verbosity

Parameters:

• verbosity (int) – CLI verbosity count (-v flags).

• quiet (bool) – Whether quiet mode is enabled (suppresses most logs).

• ts (bool) – Whether to show timestamps in log output.