Term¶
Term represents Erlang terms as Python values and converts them to and from
the Erlang External Term Format (ETF), the format of term_to_binary/1,
binary_to_term/1 and the Erlang distribution protocol.
Every term type that an Erlang/OTP 25 to 29 node sends is decoded and encoded, including pids, ports and references of the current sizes, bitstrings, funs and native records.
Two codecs with the same results: one in Python, and a native one in Rust that is several times faster. The native one is used when it is installed.
Input is treated as untrusted: malformed, truncated, too deep or too large input raises
PyCodecErrorand nothing else.Python 3.11 or newer; no dependencies.
Term is one of three projects that work together and can be used apart:
Pyrlang: an Erlang node in Python. It uses Term for every message.
Term: this project.
Epmd: an Erlang Port Mapper Daemon in Python.
Installing¶
pip install pyrlang-term
Wheels are published for Linux, Windows and macOS. One wheel serves every CPython from 3.11 on and contains the native codec. Where no wheel fits, pip builds from source: with a Rust toolchain you get the native codec, without one the Python codec only.
From a clone of https://github.com/Pyrlang/Term:
pip install -e . --config-settings editable_mode=compat
A first example¶
Everything goes through term.codec:
>>> from term import Atom, codec
>>> data = codec.term_to_binary((Atom("ok"), 1, [2.5, b"binary"]))
>>> data
b'\x83h\x03w\x02oka\x01l\x00\x00\x00\x02F@\x04\x00\x00\x00\x00\x00\x00m\x00\x00\x00\x06binaryj'
>>> codec.binary_to_term(data)
((Atom('ok'), 1, [2.5, b'binary']), b'')
binary_to_term returns the value and the bytes that follow the term, so
several terms in one buffer can be decoded one after another.
term_to_binary_2 and binary_to_term_2 do the same without the leading
version byte 131.
Which codec is in use:
>>> codec.co_impl.__name__ in ("term.native_codec_impl", "term.py_codec_impl")
True
When the native codec cannot be imported, term.codec logs one warning on
the logger term and uses the Python codec.
Errors¶
Both directions raise term.codec.PyCodecError:
>>> codec.binary_to_term(b"\x83h\x02a\x01")
Traceback (most recent call last):
...
PyCodecError: Incomplete data: 1 bytes needed at offset 5, 0 left
The message is the Python codec’s; the native codec words it differently.
The class is that of the codec in use, so always catch
codec.PyCodecError.