Data types¶
How Erlang terms and Python values map to each other. The examples run with either codec.
>>> from term import Atom, BitString, ImproperList, codec
>>> def roundtrip(value, options=None):
... return codec.binary_to_term(codec.term_to_binary(value), options)[0]
Decoding: Erlang to Python¶
Erlang |
Python |
Notes |
|---|---|---|
|
A |
|
|
|
Always, whatever the atom options say. |
|
|
Any size. |
|
|
NaN and infinities are rejected, as in Erlang. |
|
|
|
|
|
Or |
|
|
|
|
|
|
list of bytes sent as a string |
|
See Strings. Option |
improper list |
A |
|
|
|
See Maps. |
|
||
|
||
|
||
|
||
|
Cannot be called from Python; can be sent back. |
|
native record (OTP 29) |
Encoding: Python to Erlang¶
Python |
Erlang |
Notes |
|---|---|---|
|
|
At most 255 characters. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
improper list |
|
|
|
|
|
the same term |
|
any other object |
see Other objects |
Strings¶
An Erlang string is a list of integers, and nothing in the encoded bytes says
whether a list was meant as text. Erlang encodes a list of up to 65535
integers that are all in 0..255 in a compact form (STRING_EXT); such a
list is decoded to a str. Every other list, including a string with a
character above 255, is decoded to a list of integers.
>>> roundtrip("hello")
'hello'
>>> roundtrip("price: 5 €")
[112, 114, 105, 99, 101, 58, 32, 53, 32, 8364]
So a short list of small integers sent by Erlang, [1, 2, 3], arrives as
the string '\x01\x02\x03'. The option "byte_string" asks for bytes
or a list of integers instead:
>>> roundtrip("hello", {"byte_string": "int_list"})
[104, 101, 108, 108, 111]
>>> roundtrip("hello", {"byte_string": "bytes"})
b'hello'
term.list.list_to_unicode_str() turns a list of code points into a
str. When both sides are yours, send text as a UTF-8 binary: binaries
arrive as bytes whatever their content.
Atoms¶
An Atom is a str, so Atom("ok") == "ok". That is convenient, and it
means an atom and a string of the same text are one dict key. StrictAtom
hashes differently and can stand next to the string:
>>> roundtrip(Atom("ok"))
Atom('ok')
>>> roundtrip(Atom("ok"), {"atom": "StrictAtom"})
StrictAtom('ok')
>>> roundtrip(Atom("ok"), {"atom": "str"})
'ok'
>>> roundtrip(Atom("ok"), {"atom_call": lambda text: ("atom", text)})
('atom', 'ok')
Maps¶
A map becomes a dict. Keys that are different in Erlang and equal in
Python (1 and 1.0, true and 1, an atom and a string of the same
text) would silently merge into one entry, so such a map is refused:
>>> codec.binary_to_term(b"\x83t\x00\x00\x00\x02a\x01a\x01F?\xf0\x00\x00\x00\x00\x00\x00a\x02")
Traceback (most recent call last):
...
PyCodecError: Map key of type float equals an earlier key of the map in Python
A key that Python cannot hash (a list, a map) is refused as well.
Bitstrings and improper lists¶
>>> roundtrip(BitString(b"\xff\xe0", 3))
(b'\xff\xe0', 3)
>>> roundtrip(BitString(b"\xff\xe0", 3), {"bitstring": "BitString"})
BitString(b'\xff\xe0', 3)
>>> tail = roundtrip(ImproperList([1, 2], Atom("tail")))
>>> type(tail).__name__, tail
('ImproperList', [1, 2, Atom('tail')])
Other objects¶
A value of any other type is encoded as, in this order:
what the
"catch_all"entry of the encode hook returns for it;what its
__etf__()method returns;the tuple
{ClassName, #{Field => Value}}of its class name and public attributes, both as binaries.
>>> class Money:
... def __init__(self, amount):
... self.amount = amount
... def __etf__(self):
... return (Atom("money"), self.amount)
>>> roundtrip(Money(5))
(Atom('money'), 5)
An encode hook replaces values by the name of their type before they are encoded, and a decode hook does the same after decoding:
>>> import datetime
>>> hook = {"date": lambda d: (d.year, d.month, d.day)}
>>> codec.binary_to_term(codec.term_to_binary(datetime.date(2026, 1, 2), None, hook))[0]
(2026, 1, 2)
>>> codec.binary_to_term(codec.term_to_binary((1, (2,))), None, {"tuple": list})[0]
[1, [2]]
Limits¶
Input comes from the network, so both codecs bound what a term can cost:
"max_depth"(default 4096): how deeply compound terms may nest, for decoding and encoding."max_size"(default 256 MiB): the size a compressed term may declare.Counts in the input (list length, tuple arity, map size) are checked against the bytes that are left before anything is allocated.
>>> deep = []
>>> for _ in range(5000):
... deep = [deep]
>>> codec.term_to_binary(deep)
Traceback (most recent call last):
...
PyCodecError: Term is nested deeper than max_depth 4096
All options are listed with term.codec. Where the codec knowingly
differs from Erlang/OTP, Known differences says so.