pocketpy/docs/modules/pickle.md

---

icon: package

label: pickle

pickle

Save Python object graphs as bytes and restore them within pocketpy.

Function	Result
dumps(obj)	Serialized bytes.
loads(data: bytes)	Restored object.

!!!warning Only load data you trust. Deserialization can resolve classes and call reconstruction functions. This is pocketpy's own format, not CPython's pickle protocol; use a matching runtime when exchanging saved data. !!!

Shared references and cycles

import pickle

shared = ['coin']
inventory = [shared, shared]
restored = pickle.loads(pickle.dumps(inventory))
assert restored == [['coin'], ['coin']]
assert restored[0] is restored[1]

cycle = []
cycle.append(cycle)
restored_cycle = pickle.loads(pickle.dumps(cycle))
assert restored_cycle[0] is restored_cycle

Supported objects

• None, booleans, integers, floats, strings, and bytes.
• Tuples, lists, sets, and dictionaries containing supported values.
• User-defined functions and classes accessible by name at module scope.
• Instances of such classes, and native types with supported reconstruction behavior, such as random.Random.

Functions and classes are resolved by their module/name; their source code is not packed into the data. Make those definitions available when loading, especially in a worker VM. Lambdas and local functions are not suitable replacements for module-level definitions.

Lists, dictionaries, and Python class instances are memoized before their contents, preserving shared identity and supported reference cycles. Cycles involving a tuple or a __reduce__ reconstruction can be restricted; a tuple-only cycle or a self-reference through a reduce result is unsupported.

array2d instances cannot be pickled and raise TypeError. Previously pickled array2d data is not supported. Convert appropriate contents to lists if needed.

Custom reconstruction

__reduce__() must return a two-item tuple (reconstruction_callable, argument_tuple). The callable must be resolvable when loading. The hooks __getnewargs__, __getstate__, and __setstate__ are not implemented.

Implementation: pickle.c.