multiformats.multiaddr.raw

Implementation of raw encodings used by multiaddr protocols.

For expected address bytestring sizes, see the multiaddr table.

ProtoImpl

ProtoImpl

Type alias for raw protocol implementation, as a triple (raw_encoder, raw_decoder, addr_size).

RawDecoder

RawDecoder

Type alias for raw address value decoders.

alias of Callable[[bytes | bytearray | memoryview], str]

RawEncoder

RawEncoder

Type alias for raw address value encoders.

alias of Callable[[str], bytes]

exists

exists(name)[source]

Checks whether the protocol with given name has an implementation.

Example usage:

>>> multiaddr.raw.exists("ip4")
True

Parameters:: name (str) – the protocol implementation name
Return type:: bool

get

get(name)[source]

Gets the implementation (raw_encoder, raw_decoder, addr_size) for a protocol with given name.

The addr_size component is the size in bytes for the binary representation of protocol addresses:

for protocols with no address, addr_size is 0
for protocols with addresses of variable binary size, addr_size is None
for all other protocols, addr_size is a positive int

Example usage:

>>> multiaddr.raw.get("ip4")
(
 <function ip4_encoder at 0x000002DDE1655550>,
 <function ip4_decoder at 0x000002DDE16555E0>,
 4
)

Parameters:: name (str) – the protocol implementation name
Raises:: KeyError – if no such protocol implementation exists
Return type:: ProtoImpl

register

register(name, raw_encoder, raw_decoder, addr_size, *, overwrite=False)[source]

Registers an implementation for the protocol by given name.

If addr_size is 0, raw_encoder and raw_decoder should both be None (because the protocol admits no address).

It is expected that raw_encoder raises MultiaddrValueError if the string passed to it is not a valid string representatio for an address of this protocol. It is expected that raw_decoder raises MultiaddrValueError if the bytestring passed to it is not a valid binary representation for an address of this protocol.

Example usage for protocol requiring address value:

def ip4_encoder(s: str) -> bytes:
    validate(s, str)
    return IPv4Address(s).packed

def ip4_decoder(b: BytesLike) -> str:
    validate(b, BytesLike)
    _validate_size('ip4', b, 4)
    return str(IPv4Address(b))

multiformats.raw.register("ip4", ip4_encoder, ip4_decoder, 4)

Example usage for protocol not requiring address value:

multiformats.raw.register("quic", None, None, 0)

Parameters:

name (str) – the protocol implementation name
raw_encoder (raw or None) – the raw encoder
raw_decoder (raw or None) – the raw decoder
addr_size (int or None) – the expected address size for protocol addresses, in bytes (0 if no address is expected, None if address size is variable)
overwrite (bool) – whether to overwrite an existing implementation with the same name

Raises:

ValueError – if addr_size is a negative integer
ValueError – if addr_size is 0 and either one of raw_encoder or raw_decoder is not None
ValueError – if overwrite is False and an implementation with the same name already exists

Return type:

None

unregister

unregister(name)[source]

Unregisters the implementatio for the protocol by given name.

Example usage:

>>> multiformats.raw.unregister("ip4")
>>> multiformats.raw.exists("ip4")
False

Parameters:: name (str) – the protocol implementation name
Raises:: KeyError – if no such protocol implementation exists
Return type:: None