API Reference


rlp.encode(obj, sedes=None, infer_serializer=True)

Encode a Python object in RLP format.

By default, the object is serialized in a suitable way first (using rlp.infer_sedes()) and then encoded. Serialization can be explicitly suppressed by setting infer_serializer to False and not passing an alternative as sedes.

  • sedes – an object implementing a function serialize(obj) which will be used to serialize obj before encoding, or None to use the infered one (if any)
  • infer_serializer – if True an appropriate serializer will be selected using rlp.infer_sedes() to serialize obj before encoding

the RLP encoded item


rlp.EncodingError in the rather unlikely case that the item is too big to encode (will not happen)


rlp.SerializationError if the serialization fails

rlp.decode(rlp, sedes=None, **kwargs)

Decode an RLP encoded object.

  • sedes – an object implementing a function deserialize(code) which will be applied after decoding, or None if no deserialization should be performed
  • **kwargs – additional keyword arguments that will be passed to the deserializer

the decoded and maybe deserialized Python object


rlp.DecodingError if the input string does not end after the root item


rlp.DeserializationError if the deserialization fails

rlp.decode_lazy(rlp, sedes=None, **sedes_kwargs)

Decode an RLP encoded object in a lazy fashion.

If the encoded object is a bytestring, this function acts similar to rlp.decode(). If it is a list however, a LazyList is returned instead. This object will decode the string lazily, avoiding both horizontal and vertical traversing as much as possible.

The way sedes is applied depends on the decoded object: If it is a string sedes deserializes it as a whole; if it is a list, each element is deserialized individually. In both cases, sedes_kwargs are passed on. Note that, if a deserializer is used, only “horizontal” but not “vertical lazyness” can be preserved.

  • rlp – the RLP string to decode
  • sedes – an object implementing a method deserialize(code) which is used as described above, or None if no deserialization should be performed
  • **sedes_kwargs – additional keyword arguments that will be passed to the deserializers

either the already decoded and deserialized object (if encoded as a string) or an instance of rlp.LazyList

class rlp.LazyList(rlp, start, end, sedes=None, **sedes_kwargs)

A RLP encoded list which decodes itself when necessary.

Both indexing with positive indices and iterating are supported. Getting the length with len() is possible as well but requires full horizontal encoding.

  • rlp – the rlp string in which the list is encoded
  • start – the position of the first payload byte of the encoded list
  • end – the position of the last payload byte of the encoded list
  • sedes – a sedes object which deserializes each element of the list, or None for no deserialization
  • **sedes_kwargs – keyword arguments which will be passed on to the deserializer

Try to find a sedes objects suitable for a given Python object.

The sedes objects considered are obj‘s class, big_endian_int and binary. If obj is a sequence, a ListSedes will be constructed recursively.

Parameters:obj – the python object for which to find a sedes object
Raises:TypeError if no appropriate sedes could be found

Sedes Objects


A sedes object that does nothing. Thus, it can serialize everything that can be directly encoded in RLP (nested lists of strings). This sedes can be used as a placeholder when deserializing larger structures.

class rlp.sedes.Binary(min_length=None, max_length=None, allow_empty=False)

A sedes object for binary data of certain length.

  • min_length – the minimal length in bytes or None for no lower limit
  • max_length – the maximal length in bytes or None for no upper limit
  • allow_empty – if true, empty strings are considered valid even if a minimum length is required otherwise
classmethod fixed_length(l, allow_empty=False)

Create a sedes for binary data with exactly l bytes.


A sedes object for binary data of arbitrary length (an instance of rlp.sedes.Binary with default arguments).

class rlp.sedes.BigEndianInt(l=None)

A sedes for big endian integers.

Parameters:l – the size of the serialized representation in bytes or None to use the shortest possible one

A sedes object for integers encoded in big endian without any leading zeros (an instance of rlp.sedes.BigEndianInt with default arguments).

class rlp.sedes.List(elements=[])

A sedes for lists, implemented as a list of other sedes objects.

class rlp.sedes.CountableList(element_sedes)

A sedes for lists of arbitrary length.

Parameters:element_sedes – when (de-)serializing a list, this sedes will be applied to all of its elements
class rlp.Serializable(*args, **kwargs)

Base class for objects which can be serialized into RLP lists.

fields defines which attributes are serialized and how this is done. It is expected to be an ordered sequence of 2-tuples (name, sedes). Here, name is the name of an attribute and sedes is the sedes object that will be used to serialize the corresponding attribute. The object as a whole is then serialized as a list of those fields.


fields – a list of 2-tuples (name, sedes) where name is a string corresponding to an attribute and sedes is the sedes object used for (de)serializing the attribute.

  • *args – initial values for the first attributes defined via fields
  • **kwargs – initial values for all attributes not initialized via positional arguments
classmethod exclude(excluded_fields)

Create a new sedes considering only a reduced set of fields.


exception rlp.RLPException

Base class for exceptions raised by this package.

exception rlp.EncodingError(message, obj)

Exception raised if encoding fails.

Variables:obj – the object that could not be encoded
exception rlp.DecodingError(message, rlp)

Exception raised if decoding fails.

Variables:rlp – the RLP string that could not be decoded
exception rlp.SerializationError(message, obj)

Exception raised if serialization fails.

Variables:obj – the object that could not be serialized
exception rlp.DeserializationError(message, serial)

Exception raised if deserialization fails.

Variables:serial – the decoded RLP string that could not be deserialized