interfaces
Core protocol interfaces for the coding experiments library.
This module defines the abstract interfaces (protocols) for all major components in the transmission pipeline: encoders, decoders, senders, channels, and receivers.
- class codinglab.interfaces.Encoder(*args, **kwargs)[source]
Bases:
Protocol[SourceChar,ChannelChar]Protocol for encoding source messages into channel symbols.
An encoder transforms sequences of source alphabet symbols into sequences of channel alphabet symbols, typically with the goal of compression, error correction, or format adaptation.
- abstractmethod encode(message)[source]
Encode a source message into channel symbols.
- Parameters:
message (
Sequence[TypeVar(SourceChar)]) – Sequence of source symbols to encode- Return type:
- Returns:
Sequence of channel symbols representing the encoded message
- Raises:
ValueError – If the message contains symbols not in the encoder’s alphabet
- abstract property code_table: Dict[SourceChar, Sequence[ChannelChar]] | None
Get the encoding table if available.
- Returns:
Dictionary mapping source symbols to their channel code sequences, or None if no explicit code table exists
- __init__(*args, **kwargs)
- class codinglab.interfaces.Decoder(*args, **kwargs)[source]
Bases:
Protocol[SourceChar,ChannelChar]Protocol for decoding channel symbols back into source messages.
A decoder performs the inverse operation of an encoder, reconstructing source messages from sequences of channel symbols.
- abstractmethod decode(encoded)[source]
Decode channel symbols back into a source message.
- Parameters:
encoded (
Sequence[TypeVar(ChannelChar)]) – Sequence of channel symbols to decode- Return type:
- Returns:
Sequence of source symbols representing the decoded message
- Raises:
ValueError – If the encoded sequence cannot be decoded
KeyError – If a code sequence is not found in the decoding table
- abstract property code_table: Dict[SourceChar, Sequence[ChannelChar]] | None
Get the encoding table if available.
- Returns:
Dictionary mapping source symbols to their channel code sequences, or None if no explicit code table exists
- __init__(*args, **kwargs)
- class codinglab.interfaces.Sender(*args, **kwargs)[source]
Bases:
Protocol[SourceChar,ChannelChar]Protocol for message sources with encoding capability.
A sender generates source messages and encodes them for transmission through a channel. It maintains state about the last generated message.
- abstract property alphabet: Sequence[SourceChar]
Get the source alphabet used by this sender.
- Returns:
Sequence of source symbols that can appear in messages
- abstractmethod message_stream(stream_len)[source]
Generate a stream of encoded messages.
- Parameters:
stream_len (
int) – Number of messages to generate- Yields:
Encoded messages wrapped in Message containers
- Raises:
ValueError – If stream_len <= 0
- Return type:
- __init__(*args, **kwargs)
- class codinglab.interfaces.Channel(*args, **kwargs)[source]
Bases:
Protocol[ChannelChar]Protocol for communication channels.
A channel transmits messages from sender to receiver, potentially introducing noise, delays, or other channel effects.
- abstractmethod transmit_stream(messages)[source]
Transmit a stream of messages through the channel.
- Parameters:
messages (
Iterator[Message[TypeVar(ChannelChar)]]) – Iterator of encoded messages to transmit- Yields:
Transmitted messages (potentially modified by channel effects)
- Return type:
Note
The channel may maintain state between messages (e.g., for modeling channel memory effects)
- __init__(*args, **kwargs)
- class codinglab.interfaces.Receiver(decoder)[source]
Bases:
Protocol[SourceChar,ChannelChar]Protocol for message receivers with decoding capability.
A receiver accepts messages from a channel, decodes them, and provides access to the received messages.
- Parameters:
decoder (Decoder[SourceChar, ChannelChar])
- abstractmethod receive_stream(messages)[source]
Receive and process a stream of messages.
- Parameters:
messages (
Iterator[Message[TypeVar(ChannelChar)]]) – Iterator of messages received from a channel- Yields:
True for each successfully received and decoded message, False for messages that failed to decode
- Return type:
Note
The receiver may perform validation, error checking, or other processing on received messages