multiaddr package

Subpackages

Submodules

multiaddr.exceptions module

exception multiaddr.exceptions.BinaryParseError(message: str, binary: bytes, protocol: str | int, original: Exception | None = None)[source]

Bases: ParseError

MultiAddr binary representation could not be parsed

exception multiaddr.exceptions.Error[source]

Bases: Exception

exception multiaddr.exceptions.MultiaddrError(message: str = 'Multiaddr error')[source]

Bases: Exception

Base exception for multiaddr errors.

exception multiaddr.exceptions.MultiaddrLookupError[source]

Bases: LookupError, Error

exception multiaddr.exceptions.ParseError[source]

Bases: ValueError, Error

exception multiaddr.exceptions.ProtocolExistsError(proto: Any, kind: str = 'name')[source]

Bases: ProtocolRegistryError

Protocol with the given name or code already exists

exception multiaddr.exceptions.ProtocolLookupError(proto: Any, string: str)[source]

Bases: MultiaddrLookupError

MultiAddr did not contain a protocol with the requested code

multiaddr.exceptions.ProtocolManagerError

alias of ProtocolRegistryError

exception multiaddr.exceptions.ProtocolNotFoundError(value: str | int, kind: str = 'name')[source]

Bases: ProtocolRegistryError

No protocol with the given name or code found

exception multiaddr.exceptions.ProtocolRegistryError[source]

Bases: Error

exception multiaddr.exceptions.ProtocolRegistryLocked[source]

Bases: Error

Protocol registry was locked and doesn’t allow any further additions

exception multiaddr.exceptions.RecursionLimitError(message: str = 'Max recursive depth reached')[source]

Bases: ResolutionError

Raised when the maximum recursive depth is reached.

exception multiaddr.exceptions.ResolutionError(message: str = 'Resolution failed')[source]

Bases: MultiaddrError

Raised when resolution fails.

exception multiaddr.exceptions.StringParseError(message: str, string: str, protocol: str | None = None, original: Exception | None = None)[source]

Bases: ParseError

MultiAddr string representation could not be parsed

multiaddr.multiaddr module

class multiaddr.multiaddr.Multiaddr(addr: str | bytes | ~multiaddr.multiaddr.Multiaddr, *, registry: ~typing.Any = <multiaddr.protocols.ProtocolRegistry object>)[source]

Bases: Mapping[Any, Any]

Multiaddr is a representation of multiple nested internet addresses.

Multiaddr is a cross-protocol, cross-platform format for representing internet addresses. It emphasizes explicitness and self-description.

Learn more here: https://multiformats.io/multiaddr/

Multiaddrs have both a binary and string representation.

>>> from multiaddr import Multiaddr
>>> addr = Multiaddr("/ip4/1.2.3.4/tcp/80")

Multiaddr objects are immutable, so encapsulate and decapsulate return new objects rather than modify internal state.

decapsulate(addr: Multiaddr | str) → Multiaddr[source]

Remove a Multiaddr wrapping.

For example:

/ip4/1.2.3.4/tcp/80 decapsulate /ip4/1.2.3.4 = /tcp/80

decapsulate_code(code: int) → Multiaddr[source]

Remove the last occurrence of the protocol with the given code and everything after it. If the protocol code is not present, return the original multiaddr.

encapsulate(other: str | bytes | Multiaddr) → Multiaddr[source]

Wrap this Multiaddr around another.

For example:

/ip4/1.2.3.4 encapsulate /tcp/80 = /ip4/1.2.3.4/tcp/80

get_peer_id() → str | None[source]

Get the peer ID from the multiaddr.

For circuit addresses, returns the target peer ID, not the relay peer ID.

Returns:

The peer ID if found, None otherwise.

Raises:

BinaryParseError: If the binary multiaddr is invalid.

items() → a set-like object providing a view on D's items[source]
classmethod join(*addrs: str | bytes | Multiaddr) → Multiaddr[source]

Concatenate the values of the given MultiAddr strings or objects, encapsulating each successive MultiAddr value with the previous ones.

keys() → MultiAddrKeys

Returns a list of Protocols this Multiaddr includes.

protocols() → MultiAddrKeys[source]

Returns a list of Protocols this Multiaddr includes.

registry
async resolve() → list[Multiaddr][source]

Resolve this multiaddr if it contains a resolvable protocol.

Returns:

A list of resolved multiaddrs

split(maxsplit: int = -1) → list[Multiaddr][source]

Returns the list of individual path components this MultiAddr is made up of.

to_bytes() → bytes[source]

Returns the byte array representation of this Multiaddr.

value_for_protocol(proto: Any) → Any | None[source]

Return the value (if any) following the specified protocol

Returns

Union[object, NoneType]

The parsed protocol value for the given protocol code or None if the given protocol does not require any value

Raises

~multiaddr.exceptions.BinaryParseError

The stored MultiAddr binary representation is invalid

~multiaddr.exceptions.ProtocolLookupError

MultiAddr does not contain any instance of this protocol

values() → an object providing a view on D's values[source]

multiaddr.protocols module

Multiaddr Protocol Codes and Registry

This module defines all supported multiaddr protocol codes, their names, and their encodings.

Key features: - Protocol code constants (e.g., P_IP4, P_TCP, P_DNSADDR) - Protocol class for protocol metadata - ProtocolRegistry for fast lookup and aliasing - Reference to the multicodec table for protocol codes

Common protocol codes:

P_IP4 = 0x04 # IPv4 P_IP6 = 0x29 # IPv6 P_TCP = 0x06 # TCP P_UDP = 0x0111 # UDP P_DNS = 0x35 # DNS (any) P_DNS4 = 0x36 # DNS (IPv4) P_DNS6 = 0x37 # DNS (IPv6) P_DNSADDR = 0x38 # DNSADDR (libp2p) P_P2P = 0x01A5 # Peer ID P_TLS = 0x01C0 # TLS P_HTTP = 0x01E0 # HTTP P_HTTPS = 0x01BB # HTTPS …

For a full list, see the PROTOCOLS list and the multicodec table: https://github.com/multiformats/multicodec/blob/master/table.csv

Example usage:

from multiaddr.protocols import P_TCP, protocol_with_code print(P_TCP) # 6 proto = protocol_with_code(P_TCP) print(proto.name) # ‘tcp’

class multiaddr.protocols.Protocol(code: int, name: str, codec: str | None)[source]

Bases: object

code
codec
name
property path: bool
property size: int
property vcode: bytes

multiaddr.transforms module

multiaddr.transforms.bytes_iter(buf: bytes) → Generator[tuple[int, Protocol, CodecBase, bytes], None, None][source]
multiaddr.transforms.bytes_to_string(buf: bytes) → str[source]

Convert a binary multiaddr to its string representation

Raises

~multiaddr.exceptions.BinaryParseError

The given bytes are not a valid multiaddr.

multiaddr.transforms.size_for_addr(codec: CodecBase, buf_io: BytesIO) → int[source]
multiaddr.transforms.string_iter(string: str) → Generator[tuple[Protocol, CodecBase | None, str | None], None, None][source]

Iterate over the parts of a string multiaddr.

Args:

string: The string multiaddr to iterate over

Yields:

A tuple of (protocol, codec, value) for each part of the multiaddr

multiaddr.transforms.string_to_bytes(string: str) → bytes[source]

multiaddr.utils module

multiaddr.utils.get_multiaddr_options(ma: Multiaddr) → dict[str, Any] | None[source]

Extract options from a multiaddr (similar to toOptions() in JS).

Returns a dictionary with ‘family’, ‘host’, ‘transport’, and ‘port’ keys, or None if the multiaddr doesn’t represent a thin waist address.

multiaddr.utils.get_network_addrs(family: int) → list[str][source]

Get all network addresses for a given IP family (4 for IPv4, 6 for IPv6).

multiaddr.utils.get_thin_waist_addresses(ma: Multiaddr | None = None, port: int | None = None) → list[Multiaddr][source]

Get all thin waist addresses on the current host that match the family of the passed multiaddr and optionally override the port.

Wildcard IP4/6 addresses will be expanded into all available interfaces.

Args:

ma: The multiaddr to process. If None, returns empty list. port: Optional port to override the port in the multiaddr.

Returns:

List of Multiaddr objects representing thin waist addresses.

Check if an IP address is link-local.

multiaddr.utils.is_wildcard(ip: str) → bool[source]

Check if an IP address is a wildcard address.

Module contents