multiformats.multibase

Implementation of the multibase spec.

Suggested usage:

>>> from multiformats import multibase

Multibase

class Multibase(name, code, status='draft', description='')[source]

Bases: object

Container class for a multibase encoding.

Example usage:

>>> Multibase(name="base16", code="f",
              status="default", description="hexadecimal")

Parameters:

name (str) – the multibase name
code (str) – the multibase code, as single-char string or 0x... hex-string of a non-empty bytestring
status ('draft', 'candidate' or 'default', optional) – the multibase status
description (str, optional) – the multibase description

property code

Multibase code. Must either have length 1 or satisfy:

re.match(r"^0x$", code)

Return type:: str

property code_printable

Printable version of Multibase.code:

if the code is a single non-printable ASCII character, returns the hex string of its byte
otherwise, returns the code itself

Example usage:

>>> identity = multibase.get(code="\x00")
>>> identity.code
'\x00'
>>> identity.code_printable
'0x00'

Return type:: str

decode(s)[source]

Decodes a multibase string into bytes: it first checks that the multibase prefix matches the value specified by Multibase.code, then uses Multibase.raw_decoder on the string without prefix and returns the bytes.

Example usage:

>>> base32 = multibase.get("base32")
>>> base32.decode("bjbswy3dpeblw64tmmqqq")
b'Hello World!'

Parameters:

s (str) – the string to be decoded

Raises:

ValueError – if the code from the string is different from the one of this multibase
ValueError – see from_str
KeyError – see from_str

Return type:

bytes

property description

Multibase description.

Return type:: str

encode(b)[source]

Encodes bytes into a multibase string: it first uses Multibase.raw_encoder, and then prepends the multibase prefix given by Multibase.code and returns the resulting multibase string.

Example usage:

>>> base32 = multibase.get("base32")
>>> base32.encode(b"Hello World!")
'bjbswy3dpeblw64tmmqqq'

Parameters:: b (varint) – the bytes to be encoded
Return type:: str

property name

Multibase name. Must satisfy the following:

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

In the multibase table, this is listed under encoding.

Return type:: str

property raw_decoder

Returns the raw encoder for this encoding: given a string without the multibase prefix, it produces the decoded data.

Return type:: raw

property raw_encoder

Returns the raw encoder for this encoding: given bytes, it produces the encoded string without the multibase prefix.

Return type:: raw

property status

Multibase status.

Return type:: multibase

to_json()[source]

Returns a JSON dictionary representation of this Multibase object.

Example usage:

>>> base32 = multibase.get("base32")
>>> base32.to_json()
{'name': 'base32', 'code': 'b',
 'status': 'default',
 'description': 'rfc4648 case-insensitive - no padding'}

Return type:: Mapping[str, str]

static validate_code(code)[source]

Validates a multibase code and transforms it to single-character format (if in hex format).

Example usage:

>>> Multibase.validate_code("0x00")
'\x00'
>>> Multibase.validate_code("hi")
MultibaseValueError: Multibase codes must be single-character strings
or the hex digits '0xYZ' of a single byte.

Parameters:: code (str) – the multibase code, as single character or 0x... hex-string of a non-empty bytestring
Raises:: ValueError – if the code is invalid
Return type:: str

MultibaseStatusValues

MultibaseStatusValues = ('draft', 'final', 'reserved', 'experimental', 'candidate', 'default'): Collection of possible values for the Multibase.status property.

decode

decode(s)[source]

Decodes the given multibase string into bytes. The encoding is inferred using the from_str function. Decoding is then performed by Multibase.decode method.

Example usage:

>>> multibase.decode("mSGVsbG8gd29ybGQh")
b'Hello world!'

Parameters:: s (str) – the string to be decoded
Return type:: bytes

decode_raw

decode_raw(s)[source]

Similar to decode, but returns a (base, bytestr) pair of the multibase and decoded bytestring.

Example usage:

>>> base, bytestr = multibase.decode_raw("mSGVsbG8gd29ybGQh")
>>> base
Multibase(name='base64', code='m',
          status='default', description='rfc4648 no padding')
>>> bytestr
b'Hello world!'

Parameters:: s (str) – the string to be decoded
Return type:: Tuple[Multibase, bytes]

encode

encode(data, base)[source]

Encodes the given bytes into a multibase string using the given encoding.

If the encoding is passed by name, the get function is used to retrieve it. Multibase encoding is performed by the multiformats.multibase.Multibase.encode method.

Example usage:

>>> multibase.encode(b"Hello world!", "base64")
'mSGVsbG8gd29ybGQh'

Parameters:

data (BytesLike) – the data to encode using the multibase
base (str or Multibase) – the multibase to use

Return type:

str

exists

exists(name=None, *, code=None)[source]

Checks whether a multibase encoding with given name or code exists.

Example usage:

>>> multibase.exists("base8")
True
>>> multibase.exists(code="t")
True

Parameters:

name (str or None, optional) – the name of this multibase
code (Optional[str]) – the code of this multibase (keyword-only)

Raises:

ValueError – if the empty string is passed
ValueError – unless exactly one of name and code is specified

Return type:

bool

from_str

from_str(s)[source]

Returns the multibase encoding for the given string, according to the code specified by its prefix.

Example usage:

>>> multibase.from_str("mSGVsbG8gd29ybGQh")
Multibase(encoding='base64', code='m', status='default',
          description='rfc4648 no padding')

Parameters:

s (str) – the multibase encoded string

Raises:

ValueError – if the empty string is passed
KeyError – if no multibase exists with that code

Return type:

Multibase

get

get(name=None, *, code=None)[source]

Gets the multibase encoding with given name or multibase code.

Example usage:

>>> multibase.get("base8")
Multibase(encoding='base8', code='7',
          status='draft', description='octal')
>>> multibase.get(name="base8")
Multibase(encoding='base8', code='7',
          status='draft', description='octal')
>>> multibase.get(code="t")
Multibase(encoding='base32hexpad', code='t', status='candidate',
          description='rfc4648 case-insensitive - with padding')

Parameters:

name (str or None, optional) – the name of this multibase
code (Optional[str]) – the code of this multibase (keyword-only)

Raises:

ValueError – if the empty string is passed
KeyError – if no such multibase exists
ValueError – unless exactly one of name and code is specified

Return type:

Multibase

register

register(base, *, overwrite=False)[source]

Registers a given multibase encoding.

Example usage:

>>> base45 = Multibase(name="base45", code=":",
                       status="draft", description="base45 encoding")
>>> multibase.register(base45)
>>> multibase.get("base45")
Multibase(encoding='base45', code=':', status='draft',
          description='base45 encoding')

Parameters:

base (Multibase) – the multibase to register
overwrite (bool, optional) – whether to overwrite a multibase with existing code (optional, default False)

Raises:

ValueError – if overwrite is False and a multibase with the same name or code already exists
ValueError – if overwrite is True and a multibase with the same name but different code already exists

Return type:

None

table

table()[source]

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

Example usage:

>>> [e.code for e in multibase.table()]
['\x00', '0', '7', '9', 'B', 'C', 'F', 'K', 'M', 'T', 'U', 'V',
 'Z','b', 'c', 'f', 'h', 'k', 'm', 'p', 't', 'u', 'v', 'z']

Return type:: Iterator[Multibase]

unregister

unregister(name=None, *, code=None)[source]

Unregisters the multibase encoding with given name or code.

Example usage:

>>> base45 = Multibase(name="base45", code=":",
                       status="draft", description="base45 encoding")
>>> multibase.register(base45)
>>> multibase.get("base45")
Multibase(encoding='base45', code=':', status='draft',
          description='base45 encoding')
>>> multibase.unregister(code=":")
>>> multibase.exists("base45")
False

Parameters:

name (str or None, optional) – the multibase name
code (str or None, optional) – the multibase code

Raises:

KeyError – if no such multibase exists

Return type:

None

validate_multibase

validate_multibase(multibase)[source]

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

Parameters:

multibase (Multibase) – the instance to be validated

Raises:

KeyError – if no multibase with the given name is registered
ValueError – if a multibase with the given name is registered, but is different from the one given

Return type:

None