multiformats.multiaddr

Implementation of the multiaddr spec.

Suggested usage:

>>> from multiformats import multiaddr

Addr

class Addr(proto, value)[source]

Bases: object

Container class for a single protocol address in a multiaddr.

>>> a = Addr('ip4', '192.168.1.1')
>>> a
Addr('ip4', '192.168.1.1')
>>> str(a)
'/ip4/192.168.1.1'

The slash notation provides a more literate way to construct protocol addresses:

>>> a = ip4/"192.168.1.1"
>>> a
Addr('ip4', '192.168.1.1')

Bytes for protocol addresses are computed according to the TLV multiaddr format:

>>> bytes(ip4/"127.0.0.1").hex()
'047f000001'
>>> varint.encode(ip4.code).hex()
'04'
>>> bytes([127, 0, 0, 1]).hex()
  '7f000001'

Parameters:

proto (str, int, Multicodec or Proto) – the protocol for this address (by name, code, multicodec or protocol object)
value (str or BytesLike) – the address value (as a human-readable string or in its binary form)

property proto

The address protocol.

Example usage:

>>> a = Addr('ip4', '192.168.1.1')
>>> a.proto
Proto('ip4')

Return type:: Proto

property value

The address value, as a string.

Example usage:

>>> a = Addr('ip4', '192.168.1.1')
>>> a.value
'192.168.1.1'

Return type:: str

property value_bytes

The address value, as bytes.

Example usage:

>>> a = Addr('ip4', '192.168.1.1')
>>> a.value_bytes
b'\xc0\xa8\x01\x01'
>>> list(a.value_bytes)
[192, 168, 1, 1]

Return type:: bytes

Multiaddr

class Multiaddr(*addrs)[source]

Bases: Sequence[Addr | Proto]

Container class for a multiaddr.

Example usage:

>>> ip4 = multiaddr.proto("ip4")
>>> udp = multiaddr.proto("udp")
>>> quic = multiaddr.proto("quic")
>>> ma = ip4/"127.0.0.1"/udp/9090/quic
>>> ma
Multiaddr(Addr('ip4', '127.0.0.1'), Addr('udp', '9090'), Proto('quic'))
>>> str(ma)
'/ip4/127.0.0.1/udp/9090/quic'

Bytes for multiaddrs are computed according to the (TLV)+ multiaddr format:

>>> bytes(ip4/"127.0.0.1").hex()
'047f000001'
>>> bytes(udp/9090).hex()
          '91022382'
>>> bytes(quic).hex()
                  'cc03'
>>> bytes(ma).hex()
'047f00000191022382cc03'

Parameters:

addrs (sequence of Proto or Addr) – a sequence of protocols (not requiring address) and protocol addresses

Raises:

ValueError – if a Proto instance appears at a place other than the last for a protocol requiring an address
ValueError – if a procool name appears more than once

index(value, start=0, stop=None)[source]

Returns the unique index at which a protocol/address appears in the multiaddress:

>>> ma = ip4/"127.0.0.1"/udp/9090/quic
>>> str(ma)
'/ip4/127.0.0.1/udp/9090/quic'
>>> udp in ma
True
>>> ma.index(udp)
1
>>> ma[ma.index(udp)]
Addr('udp', '9090')
>>> ip4/"127.0.0.1" in ma
True
>>> ma.index(ip4/"127.0.0.1" in ma)
0

Parameters:

value (Proto or Addr) – the protocol or protocol address being looked for
start (int, optional) – the optional starting index (include) for the search range
stop (int or None, optional) – the optional stoppping index (excluded) for the search range

>>> ip4/"127.0.0.1" in ma
True
>>> ma.index(ip4/"127.0.0.1")
0
>>> ma.index(ip4/"127.0.0.1", start=1)
MultiaddrValueError: Address Addr('ip4', '127.0.0.1') does not appear in sub-multiaddr /udp/9090/quic of multiaddr /ip4/127.0.0.1/udp/9090/quic

Raises:: ValueError – if the protocol/address does not appear:

>>> ip6 = Proto("ip6")
>>> ip6 in ma
False
>>> ma.index(ip6)
MultiaddrValueError: Protocol 'ip6' does not appear in multiaddr /ip4/127.0.0.1/udp/9090/quic
>>> ip4/"127.0.0.2" in ma
False
>>> ma.index(ip4/"127.0.0.2")
MultiaddrValueError: Address Addr('ip4', '127.0.0.2') does not appear in multiaddr /ip4/127.0.0.1/udp/9090/quic

Return type:: int

property is_incomplete

Whether this multiaddress is incomplete, i.e. it still requires an address for the last protocol in the sequence.

>>> ma = ip4/"127.0.0.1"/udp
>>> ma.is_incomplete
True
>>> str(ma)
'/ip4/127.0.0.1/udp'
>>> ma2 = ma/9090
>>> str(ma2)
'/ip4/127.0.0.1/udp/9090'
>>> ma2.is_incomplete
False

Incomplete multiaddrs don’t admit a byte representation:

>>> bytes(ma)
MultiaddrValueError: Missing address value for last protocol, cannot compute bytes.
>>> bytes(ma2).hex()
'047f00000191022382'

Return type:: bool

Proto

class Proto(codec)[source]

Bases: object

Container class for a single protocol segment of a multiaddr.

>>> ip4 = Proto("ip4")
>>> ip4
Proto("ip4")
>>> str(ip4)
'/ip4'

For protocols that don’t require an address value, bytes are computed as the varint encoding of protocol code:

>>> quic = Proto('quic')
>>> quic.code
460
>>> varint.encode(quic.code).hex()
'cc03'
>>> bytes(quic).hex()
'cc03'

Parameters:: codec (str, int or Multicodec) – the multicodec for this protocol (by name, code, or as object)

addr(value)[source]

Returns an address for this protocol.

Example usage:

>>> ip4.addr("192.168.1.1")
Addr('ip4', '192.168.1.1')
>>> ip4.addr(bytes([192, 168, 1, 1]))
Addr('ip4', '192.168.1.1')

The same address can be obtained with slash syntax:

>>> ip4/"192.168.1.256"
Addr('ip4', '192.168.1.256')
>>> ip4/b'\xc0\xa8\x01\x01'
Addr('ip4', '192.168.1.1')

Parameters:: value (Union[str, varint])
Return type:: Addr

property addr_size

The address size (in bytes) for this protocol:

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:

>>> ip4.addr_size
4

Return type:: Optional[int]

property admits_addr

Whether this protocol admits an address.

>>> ip4.admits_addr
True

Return type:: bool

property code

Protocol code.

Example usage:

>>> ip4.code
4
# 4 = 0x04

Return type:: int

property codec

The multicodec for this protocol.

Example usage:

>>> ip4.codec
Multicodec(name='ip4', tag='multiaddr', code='0x04',
           status='permanent', description='')

Return type:: Multicodec

property implementation

The implementation for this protocol, as a triple of raw encoder, raw decoder and address size.

Example usage:

>>> ip4.implementation
(
 <function ip4_encoder at 0x000002B4C9956310>,
 <function ip4_decoder at 0x000002B4C99563A0>,
 4
)

Return type:: ProtoImpl

is_addr_valid(addr_value)[source]

Validates an address value.

Example usage:

>>> ip4.is_addr_valid("192.168.1.1")
True
>>> ip4.is_addr_valid(bytes([192, 168, 1, 1]))
True

The same result can be obtained with container syntax:

>>> "192.168.1.1" in ip4
True
>>> bytes([192, 168, 1, 1]) in ip4
True

Parameters:: addr_value (Union[str, varint])
Return type:: bool

property name

Protocol name.

Example usage:

>>> ip4.name
'ip4'

Return type:: str

property raw_decoder

The raw decoder for this protocol.

Example usage:

>>> ip4.raw_decoder
<function ip4_decoder at 0x000002B4C99563A0>

Return type:: RawDecoder or None

property raw_encoder

The raw encoder for this protocol.

Example usage:

>>> ip4.raw_encoder
<function ip4_encoder at 0x000002B4C9956310>

Return type:: RawEncoder or None

validate(addr_value)[source]

If successful, returns a pair of the string and bytes representations of the address value.

Example usage:

>>> ip4.validate("192.168.1.1")
('192.168.1.1', b'\xc0\xa8\x01\x01')
>>> ip4.validate("192.168")
MultiaddrValueError: Expected 4 octets in '192.168'

Raises:: ValueError – if not self.is_valid(addr_value)
Parameters:: addr_value (Union[str, varint])
Return type:: Tuple[str, bytes]

byteslike

byteslike = (<class 'bytes'>, <class 'bytearray'>, <class 'memoryview'>)

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

decode

decode(b)[source]

Decodes a multiaddr from its (TLV)+ binary encoding.

Example usage:

>>> b = bytes.fromhex('047f00000191022382cc03')
>>> multiaddr.decode(b)
Multiaddr(Addr('ip4', '127.0.0.1'), Addr('udp', '9090'), Proto('quic'))

Parameters:: b (BytesLike) – the multiaddress in binary form
Return type:: Multiaddr

parse

parse(s, allow_incomplete=False)[source]

Parses a multiaddr from its human-readable string representation.

Example usage:

>>> s = '/ip4/127.0.0.1/udp/9090/quic'
>>> multiaddr.parse(s)
Multiaddr(Addr('ip4', '127.0.0.1'), Addr('udp', '9090'), Proto('quic'))

Example usage with incomplete multiaddr:

>>> s = '/ip4/127.0.0.1/udp'
>>> multiaddr.parse(s)
MultiaddrValueError: Decoded multiaddr is incomplete: /ip4/127.0.0.1/udp
>>> multiaddr.parse(s, allow_incomplete=True)
Multiaddr(Addr('ip4', '127.0.0.1'), Proto('udp'))

Parameters:

s (str) – the multiaddress in human-readable string form
allow_incomplete (bool) – whether to allow incomplete multiaddresses

Raises:

ValueError – if allow_incomplete is False and the parsed multiaddress is incomplete

Return type:

Multiaddr

proto

proto(name)[source]

Convenience function to construct a Proto instance.

Example usage:

>>> ip4 = multiaddr.proto("ip4")
>>> ip4
Proto("ip4")

Parameters:: name (str, int or Multicodec) – the protocol name, multicodec code or multicodec object
Return type:: Proto