Why does a `tuple` subclass with a custom `__new__` fail to unpickle, and what fixes it?

### Where the arguments come from When a class defines no `__reduce__` of its own, `object.__reduce_ex__(protocol)` composes a default reduction. Under protocol 2 and later the callable it produces reconstructs the object by calling `cls.__new__(cls, *args)` — the class's own allocator, with `__init__` deliberately skipped, because rerunning an initialiser would re-do work and could have side effects. The `args` in that call are not invented: they come from `__getnewargs__` if the class has one, from `__getnewargs_ex__` if keyword arguments are needed, and otherwise from nothing at all, giving `cls.__new__(cls)`. For an ordinary mutable class this is invisible. `__new__` accepts no extra parameters, a blank instance appears, and the attribute state recorded in the reduction is applied afterwards. The object is whole and nobody thinks about the hook. ### Why immutable types are different An immutable object cannot be filled in after the fact. Its value is fixed by `__new__`, so a reduction that constructs a blank instance and then assigns attributes cannot reproduce it. This is exactly what `__getnewargs__` exists for: it lets the class say "to build me again, call `__new__` with these arguments". The built-in immutable types implement it — `"abc".__getnewargs__()` returns `('abc',)`, and `(3, 4).__getnewargs__()` returns `((3, 4),)`, one argument holding the whole tuple, which is exactly what `tuple.__new__` wants. ### The trap in a subclass Now subclass `tuple` with your own two-parameter constructor: ```python class Bad(tuple): def __new__(cls, x, y): return super().__new__(cls, (x, y)) ``` Dumping works. Loading fails, with `TypeError: Bad.__new__() missing 1 required positional argument: 'y'`. The reason is that `Bad` inherited `tuple.__getnewargs__`, which reports one argument — the whole tuple — while `Bad.__new__` demands two. The inherited hook describes the base class's constructor signature, not yours, and nothing warns you at dump time; the mismatch only surfaces in whatever program later reads the data. The fix is one method: ```python class Point(tuple): def __new__(cls, x, y): return super().__new__(cls, (x, y)) def __getnewargs__(self): return (self[0], self[1]) ``` The rule is simply that `__getnewargs__` must return a tuple that can be splatted into your own `__new__`. If your constructor needs keyword-only parameters, define `__getnewargs_ex__` instead, returning a two-item tuple of a positional argument tuple and a keyword dictionary; a class should define one or the other, not both. ### How this relates to writing `__reduce__` These hooks belong to the *default* reduction. The moment a class defines `__reduce__`, `object.__reduce_ex__` delegates to it wholesale and `__getnewargs__` is never consulted — your tuple is the recipe, start to finish. That is worth stating explicitly in an interview, because candidates often add both and then debug a hook that is not running. Choose one: `__getnewargs__` when the default machinery is nearly right and only the construction arguments are missing, a full `__reduce__` when you want to control the callable as well. ### Related sharp edges The same reasoning applies to any class whose `__new__` has required parameters, immutable or not — a class hierarchy that pushes required arguments into `__new__` will fail to round-trip until the newargs hook matches. Frozen value objects assembled by libraries usually generate the hook for you; hand-written ones frequently do not. And because the failure appears at load time in a different process or a different day's run, it is the sort of defect that reaches production data before anyone sees it, so a round-trip test of every persisted type is cheap insurance. ### Versions The newargs hooks only participate in protocol 2 and later; protocols 0 and 1 use an older reconstruction path. That is a non-issue in practice, since `pickle.DEFAULT_PROTOCOL` is 5 on Python 3.14 and was 4 from 3.8 through 3.13. `__getnewargs_ex__`, the keyword-capable form, is likewise a protocol 2-and-later mechanism. ### Reading the failure The diagnostic habit worth showing is to ask the object what it will produce *before* trusting a round trip. Calling `__getnewargs__` on an instance and mentally splatting the result into your own `__new__` answers the question in one line, and a round trip through `pickle.dumps` and `pickle.loads` in a unit test answers it for real. The error text is unusually helpful here: it names the class and the missing parameter, which points straight at a constructor signature rather than at the serialisation machinery, and that is why the cause is so often mislabelled as a pickle bug when it is really an arity mismatch the class itself declared. ### A note on what travels Only the newargs values are consumed by the allocator; anything else the object carries is handled by the state part of the default reduction and applied afterwards. So a subclass of an immutable built-in that also keeps extra attributes needs both halves to be right: the arguments must rebuild the underlying value, and the extra attributes ride along separately. Keeping the newargs tuple minimal — exactly the parameters `__new__` declares, nothing more — is what keeps the two halves from overlapping and writing the same data twice.