ADR-0022: Hold a union of objects as a pointer and others as a tag and value¶
Status¶
Superseded by ADR-0027
Date¶
2026-11-13
Context¶
TYP-14 asks for annotations that join two or more types other than
None with |, such as int | str, and TYP-07 for narrowing them with
isinstance. Until 0.4 the only union is T | None, held in a value
T never takes (ADR-0011): the word 0 or the null address, or a
signalling NaN for a float.
A value of each type has one of two shapes:
- By value. An
intis a 64-bit word, afloata double, aboolone bit, and a tuple its items laid out in place. - An object. A
str,bytes, list, set, dict, iterator or instance is a pointer to an object whose header holds its type ID; an instance also points to its class (ADR-0012).
A union needs to know at run time which member it holds: isinstance
reads it, and writing, comparing and hashing a union inside a container
depend on it.
Options considered¶
- Box every member. A union is always a pointer to an object, as in
CPython; an
intmember is boxed into a heap object. Anint | strcosts an allocation for eachintstored in it. - A tag and a value, always. A union is a tag word naming the member, then the value. A union of objects carries a tag the object's header already holds.
- The object for a union of objects, a tag and a value otherwise. A union whose members are all objects is the pointer, and its member is read from the header and the class. Any other union is a tag word and the value.
Decision¶
TyPy uses option 3, which is option 2 without the tag an object already carries.
- Normal form. A union is a set of members, so
int | strandstr | intare one type. A member that another member accepts is dropped:bool | intisint, andShape | CircleisShapewhenCirclederives fromShape. A union of one member is that member. - A union of objects is the object's address;
Nonein it is the null address, as in ADR-0011. Widening a member to the union is free. - Any other union is a tag word, then the value in as many bytes as
its largest member takes: 16 bytes for a union of scalars and objects.
The tag is the member's position in the normal form, and
Nonein it is a tag of its own. - Narrowing.
isinstance,is Noneandis not Nonenarrow a union in the branch where the test holds and in the code after a branch that cannot fall through, as type checkers do (TYP-07). - Operations. An operation, attribute or method applies to a union only when it applies to every member, as type checkers require; a method every member has runs by a switch on the member.
- Containers. The runtime gains an item kind for a tagged union,
which writes, compares and hashes the item as its member does, so a
list[int | str]prints and sorts as in CPython.
Consequences¶
- An
int | strtakes 16 bytes in a variable and in a container, and storing anintin it allocates nothing. - A union of classes, the common case with inheritance, is one pointer, and its methods dispatch through ADR-0021's table when the members share a base, or by a switch when they do not.
- Each union with a value member adds a tuple descriptor of its tag and largest member, shared as tuple descriptors are (ADR-0009).
- Ordering, equality and hashing across members follow CPython: an
intand afloatcompare by value, anintand astrraiseTypeErrorwhen ordered.
Related requirements¶
TYP-07, TYP-14, ADR-0009, ADR-0011, ADR-0012, ADR-0021.