Data Model

Lookup sheet for stage 4. The question it exists to answer: which method does this construct call, and where does the lookup go?

Attribute lookup, for obj.name

1. A data descriptor on the class or its bases: defines __get__ and __set__. Wins outright.
2. obj.__dict__["name"].
3. A non-data descriptor (__get__ only) or a plain class attribute, along the MRO.
4. __getattr__, if defined, as a last resort.

The two descriptor checks sit on opposite sides of the instance dict, and that placement is the whole of the table below. A data descriptor is asked before the instance dict, so nothing an instance stores can shadow a @property. A non-data descriptor is asked after it, so obj.method = f shadows a method and @cached_property can retire itself by writing the answer into the instance dict.

Assignment obj.name = v goes to a data descriptor's __set__ if one exists, otherwise straight into obj.__dict__, shadowing any class attribute.

__getattr__ runs only after failure. __getattribute__ intercepts every access, including self.x inside itself, so it recurses unless it calls object.__getattribute__.

Class against instance attributes

class Cart:
    items = []              # one list, shared by every instance

• Reading falls through to the class; writing creates an instance attribute and stops sharing.
• a.items.append(x) mutates the shared one, because nothing was assigned.
• Mutable state belongs in __init__ or field(default_factory=...).
• Deliberately shared state should be annotated ClassVar[...].

The descriptor protocol

Write one when the same non-trivial attribute behaviour is needed on several attributes or classes. For one attribute, use a property. For validate-once, use a frozen dataclass with __post_init__.

Dunder map, by what you want

Equality contract

1. Equal objects must hash equal.
2. A hash must not change while the object is in a dict or set.
3. Defining __eq__ sets __hash__ = None: instances become unhashable until you define it.
4. Return NotImplemented, not False, for an unrecognised type, or comparison becomes asymmetric.

@dataclass(frozen=True) generates all of this correctly and is the right default.

Construction

obj = Cls.__new__(Cls, *args)      # creates
if isinstance(obj, Cls):
    obj.__init__(*args)            # configures, returns None

__new__ is required only for:

• subclassing an immutable type (str, int, float, tuple, bytes, frozenset);
• returning an existing instance, remembering that __init__ still runs on it;
• controlling allocation, copy or pickle machinery.

Otherwise use __init__, and give every alternative way of building the object a name:

@classmethod
def from_row(cls, row): return cls(...)

__del__ has unspecified timing, may run at shutdown with globals gone, may never run for cycles, and swallows exceptions. Use a context manager.

Inheritance

[k.__name__ for k in D.__mro__]    # the exact lookup order

C3 linearisation guarantees: a class precedes its bases, declared base order is kept, each class appears once. When no such order exists:

TypeError: Cannot create a consistent method resolution order (MRO) for bases A, C

super() means the next class after this one in the instance's MRO, not the base class. In a cooperative hierarchy every override must call super() exactly once and forward **kwargs; one that does not silently truncates the chain.

Subclassing dict, list or str does not route their internal operations through your overrides. Verified: with __setitem__ overridden on a dict subclass, d["a"] = 1 calls it while update, setdefault and the constructor do not.

Class creation hooks, in order of preference

A metaclass is required only for: __prepare__ (a non-dict class-body namespace), __instancecheck__ or __subclasshook__, customising the class object itself including __call__, and reaching a hierarchy whose base was not written with a hook.

Its cost is concrete:

TypeError: metaclass conflict: the metaclass of a derived class must be a
(non-strict) subclass of the metaclasses of all its bases

Two bases with different metaclasses cannot be combined, and a user of two libraries cannot fix that.

Diagnosing unfamiliar magic

type(SomeClass)          # the metaclass, if any
SomeClass.__mro__        # where an inherited name came from
SomeClass.__dict__       # what this class defines, versus inherits
vars(obj)                # the instance dict

Sources

• Data model
• Descriptor HowTo Guide
• The Python 2.3 Method Resolution Order
• abc, collections.abc
• PEP 487, Simpler customisation of class creation