Why must you override `__new__`, not `__init__`, to subclass `int`, `str` or `tuple`?

Immutability in CPython is not a promise the class makes at the Python level; it is a property of how the object is laid out. An `int` stores its digits, a `str` its characters, a `tuple` its slot array — all inside the object, all written while it is being created and never afterwards. There is no assignable attribute holding the value, so there is nothing an initializer could set. That single fact decides which construction hook a subclass has to use. Recall the protocol. Calling a class runs `type.__call__`, which calls `__new__` to obtain the object and then `__init__` on the result. For an immutable built-in, all of the value-determining work happens in the first step: `int.__new__(cls, value)`, `str.__new__(cls, value)` and `tuple.__new__(cls, iterable)` each build an instance of `cls` already holding what it will hold forever. By the time `__init__` receives `self`, the object is finished. Writing `self.value = value` there does not change the integer; it merely bolts an unrelated attribute onto it, and the object still compares and behaves as whatever `__new__` produced. This is why `class Money(int): def __init__(self, cents): ...` appears to do nothing at all — because it does nothing at all. **The shape that works.** Override `__new__`, do the validation or transformation on the incoming argument, and delegate: ```python class PositiveInt(int): def __new__(cls, value): if value <= 0: raise ValueError("must be positive") return super().__new__(cls, value) ``` Two details are load-bearing. Pass `cls`, not the hard-coded base class, so a further subclass still produces its own type. And pass the value *to the base* `__new__`, not to `object.__new__` — the delegation goes through the immutable type's own creator, which is what accepts a payload argument at all. **Attaching extra data.** A Python-level subclass of an immutable built-in gets an instance `__dict__`, so `__new__` may set attributes on the object before returning it: ```python class Sql(str): def __new__(cls, text, *, source): obj = super().__new__(cls, text.strip()) obj.source = source return obj ``` The instance is still an immutable string as far as string operations are concerned; the added attribute lives beside the value rather than in it. Defining `__slots__ = ()` removes that `__dict__` again when you want the memory back and have no extra data to carry. **Argument compatibility.** Both steps receive the call's arguments. In the two classes above, `__init__` is inherited and is really `object.__init__`; because `__new__` *is* overridden, the extra arguments reaching it are tolerated and ignored. The moment you also define `__init__`, its signature must accept the same call — a mismatch shows up as a `TypeError` on an argument the initializer never expected. If you override `__init__` on such a subclass at all, it is for side effects only. **Behaviour you inherit and probably do not want.** Operators on the base type build base-type results: `PositiveInt(7) + 1` evaluates to a plain `int`, `Sql("a") + "b"` to a plain `str`, slicing a `tuple` subclass to a plain `tuple`. Keeping the subclass through arithmetic means overriding the operator methods to re-wrap results, which is a substantial amount of surface to maintain and a good moment to ask whether composition — a small class holding the value as an attribute — is the better design. Subclassing an immutable earns its keep mainly when the value must remain usable everywhere the base type is: as a dict key, in a format string, in a comparison. **Serialization and copying.** Because these objects are rebuilt by creation rather than by mutation, machinery that reconstructs them calls `cls.__new__(cls)` without your arguments. A `tuple` subclass whose `__new__` requires parameters therefore fails to unpickle with a missing-argument `TypeError` until it defines `__getnewargs__`, which tells the protocol which arguments to pass back into `__new__`. This is exactly why `collections.namedtuple` generates both a `__new__` and a `__getnewargs__` for the classes it builds. The same reconstruction path is used by shallow and deep copying, so the fix covers both. **A quick way to check yourself.** If you can name where the object's value physically lives, you can predict which hook is needed without memorizing a rule. A mutable object keeps its state in attributes that exist independently of the object's creation, so an initializer can still reach them. An immutable built-in keeps its state inside the object's own storage, written once at creation and never re-opened, so nothing that runs later has a way in. The same reasoning explains why `frozenset` and `bytes` subclasses follow the identical pattern, and why a subclass of a mutable type does not need it. **The one-sentence answer.** Mutable state can be set after the fact, so `__init__` suffices; an immutable's value is decided at creation, and `__new__` is the only step that participates in creation — so for `int`, `str` and `tuple` subclasses, the value goes to `super().__new__`.