What does pickle actually store for a class instance, and what can it not store?

### The reduce protocol, applied to an ordinary object `pickle` has built-in encodings for a fixed set of types: `None`, bools, ints, floats, `str`, `bytes`, tuples, lists, dicts, sets, and a few more. For everything else it asks the object how to rebuild itself, by calling `__reduce_ex__(protocol)`. Instances of ordinary classes do not define that method, so they inherit the default, which produces roughly: *call this reconstructor with the class object, then install this state*. That has two halves worth separating, because most pickle bugs live in one or the other. **The class is stored by reference.** What goes into the stream is the module name and the qualified name — the module where the class was defined, plus `Record` — and on load the unpickler imports that module and looks the attribute up. No class body, no methods, no source is serialized. The practical consequences are immediate: the reading process must be able to import the same name; renaming or moving a class silently invalidates every pickle you have already written; and a class defined inside a function has a qualified name containing `<locals>`, which cannot be looked up, so it cannot be pickled at all. **The state is a dict.** By default it is `object.__getstate__()`, which returns the instance `__dict__` (and, for a class using `__slots__`, a two-tuple of the dict and a slots-values dict). Since Python 3.11 `object.__getstate__` exists as a real default implementation you can call and extend; before that the default lived only inside the pickle machinery. On load, the instance is created **without calling `__init__`** and the state is applied — merged into `__dict__`, or passed to `__setstate__` when the class defines one. Forgetting that `__init__` is skipped is the classic source of "my object came back with an attribute missing that the constructor always sets": the attribute was absent from the state, and nothing re-ran to create it. ### What cannot be pickled, and why the error differs Two distinct failures, with two distinct exception types: ```python import pickle, threading pickle.dumps(threading.Lock()) # TypeError: cannot pickle '_thread.lock' object pickle.dumps(lambda x: x) # PicklingError: ... not found as __main__.<lambda> ``` `TypeError` means the object holds state that has no meaning in another process or another run: a lock owned by this interpreter, an open file with an OS file descriptor and a position, a socket, a running generator or a frame. There is nothing to serialize; a copy would be a lie. `PicklingError` means the object *is* fine conceptually but is not reachable by a qualified name. Functions and classes are always pickled by reference, so a lambda, a closure, a class produced by a factory, or anything defined inside a function has no name for the stream to carry. ### Controlling it: `__getstate__`, `__setstate__`, `__reduce__` The idiomatic fix for the first family is to define `__getstate__` to return a state dict with the unpicklable attributes removed, and `__setstate__` to rebuild them: ```python def __getstate__(self): state = self.__dict__.copy() del state["lock"] return state def __setstate__(self, state): self.__dict__.update(state) self.lock = threading.Lock() ``` Below that sit two heavier tools. `__reduce__` lets you specify the callable and arguments used to rebuild the object outright — the same hook that makes unpickling untrusted data dangerous, and the one to reach for when reconstruction needs a factory rather than a state dict. `copyreg.pickle` registers a reduction function for a type you do not own, without touching its class. `__getnewargs_ex__` supplies arguments to `__new__` for immutable types that need them. One more thing that surprises people: these hooks are shared with `copy.copy` and `copy.deepcopy`, which use the same reduce protocol. Adding `__getstate__` to strip a lock also changes how the object copies — usually for the better, but it is a wider blast radius than "how it pickles". ### The design rule Pickle round-trips *state*, and it does so by trusting that the same code is importable on both sides. That makes it excellent within one codebase and one interpreter version, and fragile as an archive format: your class layout becomes part of the file format, and refactoring breaks it. If the bytes must outlive the code that wrote them, define an explicit schema and serialize fields, not objects.