Subclassing Built-in Types

### Two different copying machineries A `dict` subclass has two entirely separate ways of being copied, and they disagree about what the result *is*. The first is the built-in machinery: the bound method `dict.copy()`, the `dict(...)` constructor and the `{**d}` unpacking form. All three are implemented in C on the concrete `dict` type. They allocate a brand-new *exact* `dict` object and fill it with the key/value pairs they read out of the source mapping. Nothing in that path asks what class the source was. So for ```python class Headers(dict): def __init__(self, source, /, **kw): self.source = source super().__init__({k.lower(): v for k, v in kw.items()}) def __setitem__(self, key, value): super().__setitem__(key.lower(), value) ``` `type(h.copy())`, `type(dict(h))` and `type({**h})` are all plain `dict`. The `source` attribute is gone too, because it never lived in the dict storage at all: it lives in the instance `__dict__` that your subclass gets on top of the dict, and a fresh exact `dict` has no instance `__dict__` to put it in. The `|` merge operator behaves the same way — `h | {"x": 1}` is a plain `dict`. The one built-in that does keep your class is `fromkeys()`, because it is inherited as a classmethod and is therefore called with `cls` bound to your subclass. The second machinery is the `copy` module. `copy.copy(d)` looks for a copy hook on the class, then falls back to the pickle reduction protocol: it calls `d.__reduce_ex__(4)`, which for a `dict` subclass returns a constructor callable plus your class, the instance `__dict__` as state, and an item iterator. `copy` then builds a new object with `cls.__new__(cls)`, restores the state onto the new instance's `__dict__`, and re-inserts the items one at a time. The result is an instance of your subclass, carrying `source`, and — because the re-insertion is ordinary subscript assignment — the class's own `__setitem__` runs for every item. `copy.deepcopy()` follows the same route, and `pickle` round-trips preserve the class for exactly the same reason. ### The consequences worth naming **`__init__` is not called.** Reconstruction goes through `__new__`, not `__init__`. A subclass whose `__init__` opens a connection, registers the instance in a table, or computes a derived field will not do any of that on a copy; only whatever ended up in the instance `__dict__` is carried over. That is usually what you want, and occasionally a nasty surprise. **The invariant is not the type.** In the example above the class exists to keep every key case-folded. `plain = h.copy()` still *contains* folded keys — the folding already happened — but the returned object no longer enforces anything, so `plain["X-Trace"] = "1"` stores an unfolded key and a later `plain["x-trace"]` lookup misses. The bug does not appear at the copy; it appears at the next write, possibly in a different module, which is what makes it expensive to find. **Every boundary is a downgrade point.** Any function that takes your mapping and returns `dict(arg)`, `{**arg}` or `arg.copy()` — normalizers, cache layers, serializers, "defensive copy" helpers, functions building keyword arguments — hands back a plain `dict`. You cannot audit all of them, and a type checker will not flag it, because `dict.copy()` is annotated as returning `dict[K, V]`, which is a perfectly valid supertype. Code downstream that does `result.source` or `isinstance(result, Headers)` then fails at runtime. **Serialization is a partial exception.** `pickle` uses the same reduction protocol as `copy`, so a pickled and unpickled instance is still your subclass, attributes and all. Text formats are not so kind: a JSON encoder walks the mapping and writes the pairs, so `source` and the class simply are not in the output, and what comes back is a plain `dict`. If your subclass carries meaning, that meaning has to be encoded as data somewhere, not left implicit in the type. ### How this shows up in practice The tell is a `TypeError` or `AttributeError` on a line nowhere near the copy — code doing `result.source` on something that is now a bare `dict`, or a lookup that misses because the folding quietly stopped happening. A short REPL check settles it: build an instance, run each of `d.copy()`, `dict(d)`, `{**d}` and `copy.copy(d)`, and print `type(...)` of each. Do that once for any subclass you are considering shipping, before you rely on the type surviving. ### What to do about it If the subclass exists only to hold extra attributes, it should probably not be a `dict` subclass: compose — hold a `dict` in an attribute and expose exactly the operations you need. If it exists to change mapping behaviour, `collections.UserDict` is the honest base: it stores everything in a plain `dict` under `self.data`, all mutations go through Python-level `__setitem__`, and its `copy()` is implemented in Python so it returns your class. Even then `dict(u)` still yields a plain `dict`, because that is the built-in constructor consuming a mapping — `UserDict` fixes the methods your class inherits, not what other people's constructors do with it. If you must keep a `dict` subclass, make the copying explicit: override `copy()` to return `type(self)(...)`, and test it. A one-line test asserting `type(d.copy()) is MyDict` is worth more than the docstring explaining why it might not be.