.PY File Format – Classes

The class statement

classdef:    [decorators] "class" classname [type_params] [inheritance] ":" suite
inheritance: "(" [argument_list] ")"

class Account:
    """A bank account."""

    interest = 0.02                   # class attribute

    def __init__(self, owner):
        self.owner = owner            # instance attribute
        self.balance = 0

    def deposit(self, amount):
        self.balance += amount

account = Account("Ada")
account.deposit(10)

• The body runs when the statement is reached, in a new namespace. The names it binds become the class's attributes, and the class is then bound to its name.
• A class with no base inherits from object.
• Calling the class runs __new__, then __init__.
• Keyword arguments in the base list, other than metaclass, are passed to __init_subclass__.
• Square brackets after the name make a generic class (Python 3.12).
• A class can be decorated like a function: @decorator before class.

Names bound in a class body are not visible inside its methods.

Attributes and methods

Reading x.a looks in the instance's __dict__, then in the class and its bases. A class attribute is shared by all instances until one instance assigns its own, which hides it for that instance only. A mutable class attribute is shared in full, so set up per-instance data in __init__.

A function stored in a class is turned into a bound method by the descriptor protocol. x.m makes a method object whose __self__ is x and whose __func__ is the function, so x.m() calls type(x).m(x). self is only a convention.

class C:
    __secret = 1
    def read(self):
        return self.__secret     # means self._C__secret

C().read()                       # 1
C._C__secret                     # 1
hasattr(C, "__secret")           # False

Inheritance

A class names its bases in the list after its name, and it inherits their attributes. A method with the same name overrides the base's. isinstance and issubclass test the relation. Base classes that disallow subclassing, such as bool, raise TypeError.

class A:
    def f(self): return "A"

class B(A):
    def f(self): return "B" + super().f()

class C(A):
    def f(self): return "C" + super().f()

class D(B, C):
    def f(self): return "D" + super().f()

D().f()                 # 'DBCA'
[k.__name__ for k in D.__mro__]   # ['D', 'B', 'C', 'A', 'object']

Descriptors

A descriptor is an object stored in a class whose type defines one or more of these methods (3.3.2.2). Attribute access on instances then goes through them.

A data descriptor defines __set__ or __delete__. A non-data descriptor defines only __get__. Attribute lookup on an instance uses this order:

1. A data descriptor on the class.
2. The instance's __dict__.
3. A non-data descriptor or a plain attribute on the class.
4. __getattr__, if the class defines it. Otherwise AttributeError.

Functions are non-data descriptors, which is why an instance attribute can hide a method. property, classmethod and staticmethod are descriptors too.

class Doubled:
    def __set_name__(self, owner, name):
        self.name = name

    def __get__(self, instance, owner=None):
        if instance is None:
            return self
        return instance.__dict__[self.name] * 2

    def __set__(self, instance, value):
        instance.__dict__[self.name] = value

class Thing:
    size = Doubled()

t = Thing()
t.size = 4
t.size                   # 8

class Temperature:
    def __init__(self):
        self._celsius = 0.0

    @property
    def celsius(self):
        return self._celsius

    @celsius.setter
    def celsius(self, value):
        if value < -273.15:
            raise ValueError("too cold")
        self._celsius = value

Class creation and metaclasses

A class's type is its metaclass, normally type. Calling type(name, bases, namespace) makes a class directly. A class chooses another metaclass with class C(metaclass=M): (PEP 3115). The steps to create a class are (3.3.3):

1. Any base objects that are not types are resolved through __mro_entries__.
2. The most derived metaclass among the bases and the metaclass argument is chosen. Conflicting metaclasses raise TypeError.
3. The namespace comes from the metaclass's __prepare__, or is an empty dictionary.
4. The class body runs in that namespace.
5. The class is created by calling metaclass(name, bases, namespace), which runs __new__ and __init__.
6. Each attribute's __set_name__ runs, and then the parent's __init_subclass__.
7. Class decorators are applied, and the class is bound to its name.

class Meta(type):
    def __new__(mcs, name, bases, namespace, **kwargs):
        cls = super().__new__(mcs, name, bases, namespace)
        cls.created_by = "Meta"
        return cls

class Model(metaclass=Meta):
    pass

Model.created_by         # 'Meta'
type(Model)              # <class '__main__.Meta'>

class Plugin:
    registry = []

    def __init_subclass__(cls, tag=None, **kwargs):
        super().__init_subclass__(**kwargs)
        cls.tag = tag
        Plugin.registry.append(cls)

class Upload(Plugin, tag="up"):
    pass

Upload.tag               # 'up'

Dataclasses

The dataclasses module (PEP 557, Python 3.7) generates methods from annotated class attributes, so that a class of plain fields needs no boilerplate.

from dataclasses import dataclass, field, KW_ONLY, InitVar

@dataclass(order=True, frozen=True)
class Point:
    x: int
    y: int = 0

@dataclass
class Order:
    items: list[str] = field(default_factory=list)
    tax: InitVar[int] = 0
    _: KW_ONLY
    tag: str = ""

    def __post_init__(self, tax):
        self.total_tax = tax

Point(1)                  # Point(x=1, y=0)
Point(1) < Point(2)       # True

• A field is any annotated class attribute. ClassVar fields are left out, and InitVar fields are passed only to __post_init__.
• A mutable default such as [] is a ValueError. Use field(default_factory=list).
• With eq=True and frozen=False, __hash__ is set to None, so instances are unhashable. With eq=True and frozen=True, a hash is generated.
• __post_init__ runs at the end of the generated __init__. The generated __init__ does not call a base's __init__.
• After _: KW_ONLY, the following fields are keyword-only.
• dataclasses.replace, asdict, astuple and fields work on instances.