Serpent Serialization Library

Warnings

• gotcha Although based on `ast.literal_eval` (which is safer than `eval()`), processing untrusted input with Serpent can still lead to Denial of Service (DoS) attacks, such as memory exhaustion or C stack exhaustion, by crafting malicious inputs.
  Fix: Do not deserialize data from untrusted sources. If you must process untrusted data, implement strict input validation and consider applying resource limits to prevent DoS attacks.
• gotcha When serializing `bytes`, `bytearray`, or `memoryview` objects, Serpent defaults to base-64 encoding. To retrieve the original `bytes` object during deserialization, you must manually decode the string using `serpent.tobytes()`. Alternatively, using the `bytes_repr=True` option during serialization (available since 1.40) will output Python's `bytes` literal representation, but this generally results in larger and slower serialization.
  Fix: After `loads()`, inspect string fields for base-64 encoded byte data and use `serpent.tobytes()` to convert them. Or, serialize with `dumps(obj, bytes_repr=True)` and handle the larger output.
• gotcha Serpent cannot serialize object graphs with circular references (where an object refers to itself, directly or indirectly). Attempting to do so will result in a `ValueError`.
  Fix: Ensure that the object tree you are serializing does not contain any circular references. You may need to preprocess your data structure to break such cycles.
• breaking Support for Python 3.11 introduced changes to `__getstate__` behavior. Serpent versions prior to 1.41 may fail to correctly serialize custom objects implementing `__getstate__` when running on Python 3.11 or newer.
  Fix: Upgrade to Serpent version 1.41 or newer if you are using Python 3.11+ and rely on custom `__getstate__` implementations for your serializable objects.
• gotcha The serializer instance itself is not thread-safe. Avoid modifying the object tree being serialized while `dumps()` is running, and do not use the same `dumps()` (or a shared underlying serializer instance) across multiple threads concurrently.
  Fix: For concurrent serialization, create a new `dumps` call (or ensure a new serializer instance is implicitly used) for each thread, or synchronize access to the object being serialized and the serializer instance.

Install

• pip install serpent Install stable version

Imports

• dumps

  from serpent import dumps

• loads

  from serpent import loads

  While Serpent's output is compatible with `ast.literal_eval`, `serpent.loads` handles specific corner cases and custom type deserialization that `ast.literal_eval` alone would not.
• tobytes

  from serpent import tobytes

  Used to decode base-64 encoded byte strings back to `bytes` objects if not using the `bytes_repr` serialization option.

Quickstart

This quickstart demonstrates basic serialization and deserialization of a Python dictionary containing various literal types. The `indent=True` option is used for human-readable output, and the data is converted to a UTF-8 string for printing.

from serpent import dumps, loads

data = {
    'name': 'Serpent Example',
    'version': 1.0,
    'is_active': True,
    'items': [1, 2, {'id': 'a'}]
}

# Serialize the data
serialized_bytes = dumps(data, indent=True) # indent=True for pretty-printing
print(f"Serialized data:\n{serialized_bytes.decode('utf-8')}")

# Deserialize the data
deserialized_data = loads(serialized_bytes)
print(f"Deserialized data: {deserialized_data}")
print(f"Is deserialized data equal to original? {data == deserialized_data}")