multiformats.multicodec

Implementation of the multicodec spec.

Suggested usage:

>>> from multiformats import multicodec

Multicodec

class Multicodec(name, tag, code, status='draft', description='')

Bases: object

Container class for a multicodec.

Example usage:

>>> Multicodec(**{
...     'name': 'cidv1', 'tag': 'cid', 'code': '0x01',
...     'status': 'permanent', 'description': 'CIDv1'})
Multicodec(name='cidv1', tag='cid', code=1,
           status='permanent', description='CIDv1')

Parameters:

• name (str) – the multicodec name

• tag (str) – the multicodec tag

• code (int or str) – the multicodec code, as integer or 0xYZ hex-string

• status ('draft' or 'permanent', optional) – the multicodec status

• description (str, optional) – the multicodec description

property code

Multicodec code. Must be a non-negative integer.

Return type:

int

property description

Multicodec description.

Return type:

str

property hexcode

Multicodec code as a hex string (with hex digits zero-padded to even length):

Example usage:

>>> m = multicodec.get(1)
>>> m.code
1
>>> m.hexcode
'0x01'

Return type:

str

property is_private_use

Whether this multicodec code is reserved for private use, i.e. whether it is in range(0x300000, 0x400000).

Return type:

bool

property name

Multicodec name. Must satisfy the following:

re.match(r"^[a-z][a-z0-9_-]+$", name)

Return type:

str

property status

Multicodec status.

Return type:

multicodec

property tag

Multicodec tag.

Return type:

str

to_json()

Returns a JSON dictionary representation of this multicodec object.

Example usage:

>>> m = multicodec.get(1)
>>> m.to_json()
{'name': 'cidv1', 'tag': 'cid', 'code': '0x01',
 'status': 'permanent', 'description': 'CIDv1'}

Return type:

Mapping[str, str]

unwrap(multicodec_data)

Unwraps multicodec binary data to raw data:

<code><raw data> --> <raw data>

Additionally checks that the code listed by the data matches the code of this multicodec.

Example usage:

>>> multicodec_data = bytes.fromhex("c0a800fe")
>>> raw_data = ip4.unwrap(multicodec_data)
>>> multicodec_data.hex()
'04c0a800fe'
>>> raw_data.hex()
  'c0a800fe'
>>> varint.encode(0x04).hex()
'04' #       0x04 ^^^^ is the multicodec code for 'ip4'

Parameters:

multicodec_data (BytesLike) – the multicodec data to be unwrapped

Raises:

• ValueError – if the unwrapped multicodec code does not match this multicodec’s code

• ValueError – see multiformats.multicodec.unwrap_raw

• KeyError – see multiformats.multicodec.unwrap_raw

Return type:

bytes

static validate_code(code)

Validates a multicodec code and transforms it to unsigned integer format (if in hex format).

Parameters:

code (int or str) – the multicodec code, as integer or 0xYZ hex-string

Raises:

ValueError – if the code is invalid

Return type:

int

wrap(raw_data)

Wraps raw binary data into multicodec data:

<raw data> --> <code><raw data>

Example usage:

>>> ip4 = multicodec.get("ip4")
>>> ip4
Multicodec(name='ip4', tag='multiaddr', code='0x04', status='permanent', description='')
>>> raw_data = bytes([192, 168, 0, 254])
>>> multicodec_data = ip4.wrap(raw_data)
>>> raw_data.hex()
  'c0a800fe'
>>> multicodec_data.hex()
'04c0a800fe'
>>> varint.encode(0x04).hex()
'04' #       0x04 ^^^^ is the multicodec code for 'ip4'

Parameters:

raw_data (BytesLike) – the raw data to be wrapped

Raises:

ValueError – see encode

Return type:

bytes

MulticodecStatusValues

MulticodecStatusValues = ('draft', 'permanent', 'deprecated')

Collection of possible values for the Multicodec.status property.

exists

exists(name=None, *, code=None)

Checks whether there is a multicodec with the given name or code.

Example usage:

>>> multicodec.exists("identity")
True
>>> multicodec.exists(code=0x01)
True

Parameters:

• name (str or None, optional) – the multicodec name

• code (int or None, optional) – the multicodec code

Raises:

ValueError – unless exactly one of name and code is specified

Return type:

bool

get

get(name=None, *, code=None)

Gets the multicodec with given name or code.

Example usage:

>>> multicodec.get("identity")
Multicodec(name='identity', tag='multihash', code=0,
           status='permanent', description='raw binary')
>>> multicodec.get(code=0x01)
Multicodec(name='cidv1', tag='ipld', code=1,
           status='permanent', description='CIDv1')

Parameters:

• name (str or None, optional) – the multicodec name

• code (int or None, optional) – the multicodec code

Raises:

• KeyError – if no such multicodec exists

• ValueError – unless exactly one of name and code is specified

Return type:

Multicodec

multicodec

multicodec(name, *, tag=None)

An alias for get, for use with multicodec name only. If a tag is passed, ensures that the multicodec tag matches the one given.

Example usage:

>>> from multiformats.multicodec import multicodec
>>> multicodec("identity")
Multicodec(name='identity', tag='multihash', code=0,
           status='permanent', description='raw binary')

Parameters:

• name (str) – the multicodec name

• tag (str or None, optional) – the optional multicodec tag

Raises:

KeyError – see get

Return type:

Multicodec

register

register(codec, *, overwrite=False)

Registers a given multicodec.

Example usage:

>>> m = Multicodec("my-multicodec", "my-tag", 0x300001, "draft", "...")
>>> multicodec.register(m)
>>> multicodec.exists(code=0x300001)
True
>>> multicodec.get(code=0x300001).name
'my-multicodec'
>>> multicodec.get(code=0x300001).is_private_use
True

Parameters:

• codec (Multicodec) – the multicodec to register

• overwrite (bool, optional) – whether to overwrite a multicodec with existing code (optional, default False)

Raises:

• ValueError – if overwrite is False and a multicodec with the same name or code already exists

• ValueError – if overwrite is True and a multicodec with the same name but different code already exists

Return type:

None

table

table(*, tag=None, status=None)

Iterates through the registered multicodecs, in order of ascending code.

Example usage:

>>> len(list(multicodec.table())) # multicodec.table() returns an iterator
482
>>> selected = multicodec.table(tag=["cid", "cid", "multiaddr"], status="permanent")
>>> [m.code for m in selected]
[1, 4, 6, 41, 53, 54, 55, 56, 81, 85, 112, 113, 114, 120,
 144, 145, 146, 147, 148, 149, 150, 151, 152, 176, 177,
 178, 192, 193, 290, 297, 400, 421, 460, 477, 478, 479, 512]

Parameters:

• tag (None, str, set or sequence of str, optional) – one or more tags to be selected (if None, all tags are included)

• status (None, str, set or sequence of str, optional) – one or more statuses to be selected (if None, all statuses are included)

Return type:

Iterator[Multicodec]

unregister

unregister(name=None, *, code=None)

Unregisters the multicodec with given name or code.

Example usage:

>>> multicodec.unregister(code=0x01) # cidv1
>>> multicodec.unregister(code=0x01)
False

Parameters:

• name (str or None, optional) – the multicodec name

• code (int or None, optional) – the multicodec code

Raises:

• KeyError – if no such multicodec exists

• ValueError – unless exactly one of name and code is specified

Return type:

None

unwrap

unwrap(multicodec_data)

Unwraps multicodec binary data to multicodec and raw data:

Example usage:

>>> multicodec_data = bytes.fromhex("04c0a800fe")
>>> codec, raw_data = multicodec.unwrap(multicodec_data)
>>> multicodec_data.hex()
'04c0a800fe'
>>> raw_data.hex()
  'c0a800fe'
>>> codec
Multicodec(name='ip4', tag='multiaddr', code='0x04', status='permanent', description='')

Parameters:

multicodec_data (BytesLike) – the binary data prefixed with multicodec code

Raises:

KeyError – if the code does not correspond to a know multicodec

Return type:

Tuple[Multicodec, bytes]

unwrap_raw

unwrap_raw(multicodec_data)

Similar to unwrap, but returns a triple of multicodec code, number of bytes read and remaining bytes.

Example usage:

>>> multicodec_data = bytes.fromhex("04c0a800fe")
>>> code, num_bytes_read, remaining_bytes = multicodec.unwrap_raw(multicodec_data)
>>> code
4
>>> num_bytes_read
1
>>> remaining_bytes
<memory at 0x000001BE46B17640>
>>> multicodec_data.hex()
'04c0a800fe'
>>> bytes(remaining_bytes).hex()
  'c0a800fe'

Parameters:

multicodec_data (BytesLike) – the binary data prefixed with multicodec code

Raises:

KeyError – if the code does not correspond to a know multicodec

Return type:

Tuple[int, int, Union[memoryview, BufferedIOBase]]

validate_multicodec

validate_multicodec(codec)

Validates an instance of Multicodec. If the multicodec is registered (i.e. valid), no error is raised.

Parameters:

codec (Multicodec) – the instance to be validated

Raises:

• KeyError – if no multicodec with the given name is registered

• ValueError – if a multicodec with the given name is registered, but is different from the one given

Return type:

None

wrap

wrap(codec, raw_data)

Wraps raw binary data into multicodec data:

<raw data> --> <code><raw data>

Example usage:

>>> raw_data = bytes([192, 168, 0, 254])
>>> multicodec_data = multicodec.wrap("ip4", raw_data)
>>> raw_data.hex()
  'c0a800fe'
>>> multicodec_data.hex()
'04c0a800fe'
>>> varint.encode(0x04).hex()
'04' #       0x04 ^^^^ is the multicodec code for 'ip4'

Parameters:

• codec (str, int or Multicodec) – the multicodec that the raw data refers to

• raw_data (BytesLike) – the raw binary data

Raises:

KeyError – see get

Return type:

bytes