libp2p.io package

Submodules

libp2p.io.abc module

class libp2p.io.abc.Closer

Bases: ABC

abstract async close() → None

class libp2p.io.abc.EncryptedMsgReadWriter(conn: Any | None = None)

Bases: MsgReadWriteCloser, Encrypter

Read/write message with encryption/decryption.

conn: Any | None

get_remote_address() → tuple[str, int] | None

Get remote address if supported by the underlying connection.

class libp2p.io.abc.Encrypter

Bases: ABC

abstract decrypt(data: bytes) → bytes

abstract encrypt(data: bytes) → bytes

class libp2p.io.abc.MsgReadWriteCloser

Bases: MsgReader, MsgWriter, Closer

class libp2p.io.abc.MsgReader

Bases: ABC

abstract async read_msg() → bytes

class libp2p.io.abc.MsgWriter

Bases: ABC

abstract async write_msg(msg: bytes) → None

class libp2p.io.abc.ReadCloser

Bases: Reader, Closer

class libp2p.io.abc.ReadWriteCloser

Bases: Reader, Writer, Closer

abstract get_remote_address() → tuple[str, int] | None

Return the remote address of the connected peer.

Returns:

A tuple of (host, port) or None if not available

class libp2p.io.abc.ReadWriter

Bases: Reader, Writer

class libp2p.io.abc.Reader

Bases: ABC

abstract async read(n: int | None = None) → bytes

class libp2p.io.abc.WriteCloser

Bases: Writer, Closer

class libp2p.io.abc.Writer

Bases: ABC

abstract async write(data: bytes) → None

libp2p.io.exceptions module

exception libp2p.io.exceptions.ConnectionClosedError(message: str, close_code: int | None = None, close_reason: str = '', transport: str = '')

Bases: IOException

Raised when a connection is closed by the peer.

Carries structured close information so that upstream code can make decisions based on exception type (except ConnectionClosedError) rather than fragile string matching on the message.

exception libp2p.io.exceptions.DecryptionFailedException

Bases: MsgioException

exception libp2p.io.exceptions.IOException

Bases: BaseLibp2pError

exception libp2p.io.exceptions.IncompleteReadError(message: str, expected_bytes: int = 0, received_bytes: int = 0)

Bases: IOException

Fewer bytes were read than requested.

property is_clean_close: bool

Returns True if this represents a clean connection closure.

exception libp2p.io.exceptions.MessageTooLarge

Bases: MsgioException

exception libp2p.io.exceptions.MissingLengthException

Bases: MsgioException

exception libp2p.io.exceptions.MissingMessageException

Bases: MsgioException

exception libp2p.io.exceptions.MsgioException

Bases: IOException

libp2p.io.msgio module

msgio is an implementation of https://github.com/libp2p/go-msgio.

from that repo: “a simple package to r/w length-delimited slices.”

NOTE: currently missing the capability to indicate lengths by “varint” method.

class libp2p.io.msgio.BaseMsgReadWriter(read_write_closer: ReadWriteCloser)

Bases: MsgReadWriteCloser

async close() → None

abstract encode_msg(msg: bytes) → bytes

abstract async next_msg_len() → int

async read_msg() → bytes

read_write_closer: ReadWriteCloser

size_len_bytes: int

async write_msg(msg: bytes) → None

class libp2p.io.msgio.FixedSizeLenMsgReadWriter(read_write_closer: ReadWriteCloser)

Bases: BaseMsgReadWriter

encode_msg(msg: bytes) → bytes

async next_msg_len() → int

size_len_bytes: int

class libp2p.io.msgio.VarIntLengthMsgReadWriter(read_write_closer: ReadWriteCloser)

Bases: BaseMsgReadWriter

encode_msg(msg: bytes) → bytes

max_msg_size: int

async next_msg_len() → int

libp2p.io.msgio.encode_msg_with_length(msg_bytes: bytes, size_len_bytes: int) → bytes

async libp2p.io.msgio.read_length(reader: Reader, size_len_bytes: int) → int

libp2p.io.trio module

class libp2p.io.trio.TrioTCPStream(stream: SocketStream)

Bases: ReadWriteCloser

async close() → None

get_remote_address() → tuple[str, int] | None

Return the remote address as (host, port) tuple.

This method caches the remote address on first successful retrieval to handle cases where the socket might become unavailable later (e.g., during connection teardown or in certain error states).

Returns:

A tuple of (host, port) or None if the address cannot be determined.

async read(n: int | None = None) → bytes

read_lock: Lock

stream: SocketStream

async write(data: bytes) → None

Handle write operations gracefully when resources are closed.

write_lock: Lock

libp2p.io.utils module

async libp2p.io.utils.read_exactly(reader: Reader, n: int, retry_count: int = 100) → bytes

Read exactly n bytes from the reader.

This function attempts to read exactly n bytes from the reader, retrying up to retry_count times if partial data is received. If the connection closes before n bytes are received, raises IncompleteReadError with enhanced error messages that include transport context (if available).

The error message includes:

• The expected and actual number of bytes received

• Transport type and connection duration (if reader provides conn_state())

• Context about possible causes (peer closure, network issues, transport-specific problems)

Args:

reader: The reader to read from n: Number of bytes to read retry_count: Maximum number of retries if partial data is received

Returns:

bytes: Exactly n bytes of data

Raises:

IncompleteReadError: If the connection closes before n bytes are received.

The error message includes transport context if available via reader.conn_state().

Note

Relies on exceptions to break out on erroneous conditions, like EOF.

Module contents