# API Reference

## Functions

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

  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.

  If obj has an attribute `_cached_rlp` (as, notably, `rlp.Serializable`) and its value is not None, this value is returned bypassing serialization and encoding, unless sedes is given (as the cache is assumed to refer to the standard serialization which can be replaced by specifying sedes).

  If obj is a `rlp.Serializable` and cache is true, the result of the encoding will be stored in `_cached_rlp` if it is empty and `rlp.Serializable.make_immutable()` will be invoked on obj.

  Parameters:

  - 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
  - cache – cache the return value in obj._cached_rlp if possible and make obj immutable (default False)

  Returns: | the RLP encoded item
  Raises: | `rlp.EncodingError` in the rather unlikely case that the item is too big to encode (will not happen)
  Raises: | `rlp.SerializationError` if the serialization fails

`rlp.``decode`(rlp, sedes=None, strict=True, **kwargs)

  Decode an RLP encoded object.

  If the deserialized result obj has an attribute `_cached_rlp` (e.g. if sedes is a subclass of `rlp.Serializable`) it will be set to rlp, which will improve performance on subsequent `rlp.encode()` calls. Bear in mind however that obj needs to make sure that this value is updated whenever one of its fields changes or prevent such changes entirely (`rlp.sedes.Serializable` does the latter).

  Parameters:

  - 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
  - strict – if false inputs that are longer than necessary don’t cause an exception

  Returns: | the decoded and maybe deserialized Python object
  Raises: | `rlp.DecodingError` if the input string does not end after the root item and strict is true
  Raises: | `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.

  Parameters:

  - 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

  Returns: | 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.

    Parameters:

    - 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

`rlp.``infer_sedes`(obj)

  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 `rlp.sedes.List` 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

`rlp.sedes.``raw`

  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.

  Parameters:

  - 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.

`rlp.sedes.``binary`

  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

`rlp.sedes.``big_endian_int`

  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=[], strict=True)

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

  Parameters: | strict – If true (de)serializing lists that have a length not matching the sedes length will result in an error. If false (de)serialization will stop as soon as either one of the lists runs out of elements.

class `rlp.sedes.``CountableList`(element_sedes, max_length=None)

  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
  - max_length – maximum number of allowed elements, or None for no limit

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.

  Variables:

  - 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.
  - _cached_rlp – can be used to store the object’s RLP code (by default None)
  - _mutable – if False, all attempts to set field values will fail (by default True, unless created with `deserialize()`)

  Parameters:

  - *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.

  `is_mutable`()

    Checks if the object is mutable

  `make_immutable`()

    Make it immutable to prevent accidental changes.

    obj.make_immutable is equivalent to make_immutable(obj), but doesn’t return anything.

  `make_mutable`()

    Make it mutable.

    obj.make_mutable is equivalent to make_mutable(obj), but doesn’t return anything.

## Exceptions

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