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,falseandundefinedalways becomeTrue,FalseandNone."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 asSTRING_EXTbecomes."bitstring""tuple"(default): a bitstring becomes(bytes, last_byte_bits)."BitString": it becomes aBitString, 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_REFrefers 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", notint) 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.
Noneis encoded as the atomundefined,TrueandFalseastrueandfalse.- Parameters:
- 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:
- 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:
- 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:
- Returns:
the encoded term
- Return type:
- 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_REFrefers to its entries.
- exception term.codec.PyCodecError¶
Bases:
ExceptionA 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.
Noneis encoded as the atomundefined,TrueandFalseastrueandfalse.- Parameters:
- 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:
- 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:
- 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.
Noneis encoded as the atomundefined,TrueandFalseastrueandfalse.- Parameters:
- 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:
- 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:
- 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.
Noneis encoded as the atomundefined,TrueandFalseastrueandfalse.- Parameters:
- 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:
- 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:
- 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]