When do you implement `__deepcopy__` on a class, and what must it do with memo?

### What the copy module does without a hook `copy.copy(obj)` and `copy.deepcopy(obj)` both start by dispatching on the object's type. For built-in containers they use dedicated routines; for an ordinary instance with no hooks they build a new instance of the same class **without calling `__init__`** and populate its `__dict__` — shallowly for `copy.copy`, recursively for `copy.deepcopy`. If the type resists that treatment, they fall back to the pickle-style reduction protocol through `__reduce_ex__`, which is why some objects raise `TypeError` when deep-copied at all. For the large majority of classes that default is exactly right and writing a hook would be noise. You define one when the default is *wrong*. ### The three cases that justify a hook 1. **The object owns something that must not be duplicated.** A `threading.Lock`, a socket, a database connection, an open file handle. Deep-copying a lock does not even work — the reduction protocol refuses it — and even if it did, a clone holding a copy of a lock is a bug: two objects that believe they are mutually excluded are not. The hook gives the copy a *fresh* lock and reconnects or drops the connection. 2. **The object holds derived state that should be dropped or shared.** A memoisation cache, an index, a compiled pattern, a large read-only lookup table. Copying it is pure cost; the honest copy starts with an empty cache or keeps pointing at the shared table. 3. **Some field must differ in the copy.** An identity, a version number, a creation timestamp. If every copy must get a new one, the hook is the only place that happens automatically. ### The memo contract, precisely `__deepcopy__(self, memo)` receives the same memo dict the whole traversal is threading through, and it must cooperate with it in two ways: ```python import copy import threading class ScoreCache: def __init__(self, entries=None): self.entries = entries if entries is not None else {} self.lock = threading.Lock() def __deepcopy__(self, memo): clone = ScoreCache.__new__(ScoreCache) memo[id(self)] = clone # 1. register first clone.entries = copy.deepcopy(self.entries, memo) # 2. thread memo down clone.lock = threading.Lock() # fresh, never copied return clone original = ScoreCache({"acct-1": 0.83}) clone = copy.deepcopy(original) print(clone.entries, clone.lock is original.lock) ``` **Register before recursing.** `memo[id(self)] = clone` must happen before any child is copied. If a child (directly or transitively) refers back to `self`, the walk finds the entry and links to the in-progress clone; without it, the recursion never bottoms out. **Pass `memo` down.** Every nested `copy.deepcopy(child, memo)` must forward it. Omitting the argument starts a fresh traversal, which duplicates objects the outer walk already copied and destroys the aliasing the outer copy was carefully preserving — two fields that shared an object in the original end up holding two different copies. **Prefer `__new__` over `__init__`.** Calling the constructor inside the hook re-runs whatever side effects it has — opening files, registering in a registry, validating — and forces you to reconstruct arguments you may not have kept. Allocating with `__new__` and assigning attributes mirrors what the default machinery does. ### `__copy__`, and the option of not copying at all `__copy__(self)` is the shallow counterpart: no memo, no recursion, just "make me a one-level copy of this object". A class that needs a fresh lock will usually want both hooks, since `copy.copy` will otherwise hand out an instance sharing the original's lock object. There is a third, legitimate answer for genuinely immutable value objects: return `self` from both hooks. Copying something that cannot change is pure waste, and the built-in atomics already behave this way. Use it only when the object really is immutable — returning `self` from a mutable object's copy hook turns every "copy" into an alias and produces exactly the bug the caller was trying to avoid. ### Testing a hook Three assertions cover almost all of it: the copy is not the original (`clone is not original`); the resource is fresh rather than shared (`clone.lock is not original.lock`); and a mutation through one is not visible through the other. Add a cycle to the fixture if the type can participate in one, and assert that deep-copying a structure holding the object twice yields one clone referenced twice — that is the check that catches a forgotten `memo` argument, which is otherwise invisible until a subtle aliasing bug shows up in production.