Search code examples
pythonpython-typing

What is the meaning of __total__ dunder attribute?

In newly released Python 3.8 there is a new type annotation typing.TypedDict. Its documentation mentions that

The type info for introspection can be accessed via Point2D.__annotations__ and Point2D.__total__. [....]

While __annotations__ is well-known, having been introduced in PEP 3107, I cannot find any information on __total__. Could anyone explain its meaning and if possible linking to authoritative sources?

Solution

  • I am guessing that the __total__ field signifies whether instances must be complete (the default) or not (all fields optional). I started my search at PEP 589, which introduced TypedDict and describes totality as such. It used a total argument, which it would make sense to rename dunder-style for the class syntax. However, I did not find when such a renaming took place.

    Looking into MyPy, which is the actual type checker that cares about these annotations, there is similar documentation on TypedDict and totality, but again no reference to the dunder syntax. Digging into its implementation led to more confusion, as TypedDictType in types.py doesn't have a total field, but separate items and required_keys. Totality would imply that items.keys()==required_keys but the implementation makes different assumptions, such as can_be_false relying on items alone. total=False should in principle mean required_keys is empty.

    The CPython source for _TypedDictMeta at least reveals that the total argument and __total__ dunder are one and the same, although the source describes TypedDict itself as "may be added soon".