term.codec

The codec: Erlang External Term Format to Python values and back.

This module is the public interface. It uses the native (Rust) codec when the extension module was built, and the Python codec (term.py_codec_impl) otherwise; both give the same results.

Decode options

binary_to_term and binary_to_term_2 take a dict of options. They apply at every nesting level of the term.

"atom"

"Atom" (default), "StrictAtom", "str" or "bytes": what an Erlang atom becomes. true, false and undefined always become True, False and None.

"atom_call"

A callable that gets the atom’s text and returns the value to use for it. Takes precedence over "atom".

"byte_string"

"str" (default), "bytes" or "int_list": what a list of bytes that Erlang sent as STRING_EXT becomes.

"bitstring"

"tuple" (default): a bitstring becomes (bytes, last_byte_bits). "BitString": it becomes a BitString, which encodes back to the same bitstring.

"decode_hook"

A dict of type name to callable. Every decoded value whose type has that name is replaced by what the callable returns for it.

"atom_cache"

A list or tuple of atom texts that ATOM_CACHE_REF refers to, for terms that follow a distribution header. Without it such a reference is an error.

"max_depth"

How deeply compound terms may nest (default 4096).

"max_size"

The largest size in bytes a compressed term may declare (default 256 MiB).

Encode options

"encode_hook"

A dict of type name ("int", not int) to callable; a value of that type is replaced by what the callable returns before it is encoded. The key "catch_all" is used for values that have no encoding of their own. A single callable instead of a dict means {"catch_all": callable}.

"max_depth"

How deeply compound values may nest (default 4096).

A value with no encoding of its own and no "catch_all" hook is encoded as what its __etf__() method returns, or else as the tuple (ClassName, Fields) of its public attributes.

term.codec.term_to_binary(term, options=None, encode_hook=None)

Encode a value, starting with the version byte 131.

None is encoded as the atom undefined, True and False as true and false.

Parameters:
  • term (object) – the value to encode

  • options (dict[str, Any] | None) – the encode options listed in the module description

  • encode_hook (dict[str, Callable[[Any], Any]] | None) – the "encode_hook" option, given separately

Raises:

PyCodecError – for a value nested deeper than "max_depth", a value that contains itself, and a value that cannot be encoded

Returns:

the encoded term

Return type:

bytes

term.codec.binary_to_term(data, options=None, decode_hook=None)

Decode one term that starts with the version byte 131; a compressed term is inflated.

Parameters:
  • data (bytes) – the encoded term; more bytes may follow it

  • options (dict[str, Any] | None) – the decode options listed in the module description

  • decode_hook (dict[str, Callable[[Any], Any]] | None) – the "decode_hook" option, given separately

Raises:

PyCodecError – when the first byte is not 131, on any malformed or truncated input, when a limit is exceeded, and when a hook or "atom_call" raises (the original exception is the __cause__)

Returns:

the value, and the bytes that follow the term

Return type:

tuple[str | List[Any] | tuple | dict | int | float | bytes | BaseTerm | None, bytes]

term.codec.term_to_binary_2(term, options=None, encode_hook=None)

Encode a value without the version byte 131; otherwise as term_to_binary().

Parameters:
Raises:

PyCodecError – as term_to_binary()

Returns:

the encoded term

Return type:

bytes

term.codec.binary_to_term_2(data, options=None, decode_hook=None)

Decode a term that has no version byte 131, as the terms that follow a distribution header; with the option "atom_cache" (a list of atom texts) ATOM_CACHE_REF refers to its entries.

Parameters:
Raises:

PyCodecError – as binary_to_term()

Returns:

the value, and the bytes that follow the term

Return type:

tuple[str | List[Any] | tuple | dict | int | float | bytes | BaseTerm | None, bytes]

exception term.codec.PyCodecError

Bases: Exception

A term could not be decoded or a value could not be encoded.

term.codec.encode(term, options=None, encode_hook=None)

Encode a value, starting with the version byte 131.

None is encoded as the atom undefined, True and False as true and false.

Parameters:
  • term (object) – the value to encode

  • options (dict[str, Any] | None) – the encode options listed in the module description

  • encode_hook (dict[str, Callable[[Any], Any]] | None) – the "encode_hook" option, given separately

Raises:

PyCodecError – for a value nested deeper than "max_depth", a value that contains itself, and a value that cannot be encoded

Returns:

the encoded term

Return type:

bytes

term.codec.decode(data, options=None, decode_hook=None)

Decode one term that starts with the version byte 131; a compressed term is inflated.

Parameters:
  • data (bytes) – the encoded term; more bytes may follow it

  • options (dict[str, Any] | None) – the decode options listed in the module description

  • decode_hook (dict[str, Callable[[Any], Any]] | None) – the "decode_hook" option, given separately

Raises:

PyCodecError – when the first byte is not 131, on any malformed or truncated input, when a limit is exceeded, and when a hook or "atom_call" raises (the original exception is the __cause__)

Returns:

the value, and the bytes that follow the term

Return type:

tuple[str | List[Any] | tuple | dict | int | float | bytes | BaseTerm | None, bytes]

term.codec.pack(term, options=None, encode_hook=None)

Encode a value, starting with the version byte 131.

None is encoded as the atom undefined, True and False as true and false.

Parameters:
  • term (object) – the value to encode

  • options (dict[str, Any] | None) – the encode options listed in the module description

  • encode_hook (dict[str, Callable[[Any], Any]] | None) – the "encode_hook" option, given separately

Raises:

PyCodecError – for a value nested deeper than "max_depth", a value that contains itself, and a value that cannot be encoded

Returns:

the encoded term

Return type:

bytes

term.codec.unpack(data, options=None, decode_hook=None)

Decode one term that starts with the version byte 131; a compressed term is inflated.

Parameters:
  • data (bytes) – the encoded term; more bytes may follow it

  • options (dict[str, Any] | None) – the decode options listed in the module description

  • decode_hook (dict[str, Callable[[Any], Any]] | None) – the "decode_hook" option, given separately

Raises:

PyCodecError – when the first byte is not 131, on any malformed or truncated input, when a limit is exceeded, and when a hook or "atom_call" raises (the original exception is the __cause__)

Returns:

the value, and the bytes that follow the term

Return type:

tuple[str | List[Any] | tuple | dict | int | float | bytes | BaseTerm | None, bytes]

term.codec.dumps(term, options=None, encode_hook=None)

Encode a value, starting with the version byte 131.

None is encoded as the atom undefined, True and False as true and false.

Parameters:
  • term (object) – the value to encode

  • options (dict[str, Any] | None) – the encode options listed in the module description

  • encode_hook (dict[str, Callable[[Any], Any]] | None) – the "encode_hook" option, given separately

Raises:

PyCodecError – for a value nested deeper than "max_depth", a value that contains itself, and a value that cannot be encoded

Returns:

the encoded term

Return type:

bytes

term.codec.loads(data, options=None, decode_hook=None)

Decode one term that starts with the version byte 131; a compressed term is inflated.

Parameters:
  • data (bytes) – the encoded term; more bytes may follow it

  • options (dict[str, Any] | None) – the decode options listed in the module description

  • decode_hook (dict[str, Callable[[Any], Any]] | None) – the "decode_hook" option, given separately

Raises:

PyCodecError – when the first byte is not 131, on any malformed or truncated input, when a limit is exceeded, and when a hook or "atom_call" raises (the original exception is the __cause__)

Returns:

the value, and the bytes that follow the term

Return type:

tuple[str | List[Any] | tuple | dict | int | float | bytes | BaseTerm | None, bytes]