.PY File Format – Data model

Mutable and immutable objects

Objects whose value can change are mutable, such as lists and dictionaries. Others are immutable, such as numbers, strings and tuples. A tuple cannot change which objects it refers to, but an object it refers to may itself be mutable.

Equal immutable objects may or may not be the same object: after a = 1; b = 1, a is b depends on the implementation. For mutable objects it is guaranteed: after c = []; d = [] the two are different lists.

Lifetime

An object is never destroyed explicitly. It may be reclaimed once it becomes unreachable. How and when is up to the implementation: CPython uses reference counting with a collector for cycles, but programs should not depend on it. Close files and other resources with a with statement.

How special methods are found

When Python calls a special method implicitly, it looks it up on the object's type, not on the instance (3.3.13):

class C:
    pass

c = C()
c.__len__ = lambda: 5
len(c)                # TypeError: object of type 'C' has no len()

Basic customisation

• Comparison. The default __eq__ compares identity, and __ne__ inverts __eq__ by default. There are no reflected comparison methods: x < y tries x.__lt__(y), then y.__gt__(x). If the right operand's type is a subclass of the left's, its method runs first.
• Hashing. A class that defines __eq__ without __hash__ has its __hash__ set to None, so its instances cannot be dictionary keys.

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __repr__(self):
        return f"Point({self.x}, {self.y})"

    def __eq__(self, other):
        if not isinstance(other, Point):
            return NotImplemented
        return (self.x, self.y) == (other.x, other.y)

    def __hash__(self):
        return hash((self.x, self.y))

    def __add__(self, other):
        if not isinstance(other, Point):
            return NotImplemented
        return Point(self.x + other.x, self.y + other.y)

Attribute access

A module can define __getattr__ and __dir__ as ordinary functions to customise access to its own attributes (PEP 562, Python 3.7). Descriptors and __slots__ are on the Classes page.

Containers

A slice such as x[1:3] reaches __getitem__ as a slice object. If a class has no __iter__, iter() falls back to calling __getitem__ with 0, 1, 2 and so on until IndexError. If it has no __contains__, in iterates.

Numeric methods

Each binary operator has a method, a reflected form tried with the operands swapped, and an in-place form for augmented assignment (3.3.8):

For x + y:

1. If the type of y is a subclass of the type of x and overrides __radd__, y.__radd__(x) is tried first.
2. Otherwise x.__add__(y) is tried. If it is missing or returns NotImplemented, y.__radd__(x) is tried.
3. If nothing works, TypeError is raised.

If both operands have the same type, the reflected method is not tried. x += y tries x.__iadd__(y) first and falls back to the rule above. __index__ gives an object an exact integer, which lets it serve as a list index or in hex(). Since Python 3.14, int() no longer delegates to __trunc__.

Other protocols