Language

Classes

Classes are state containers and namespaces, not the primary abstraction. This is a design choice. Two patterns cover most uses.

State machines. A few methods mutate the receiver.
Namespaces. A class bundles related functions and constants.

The class model supports these features.

Single and multiple inheritance (C3 MRO) with super().
@property and @x.setter.
@staticmethod and @classmethod.
A curated dunder protocol for operators, indexing, iteration, hashing, context managers and attribute fallback. See Operator overloading and protocols.

Any other dunder a class body binds, and a class keyword such as metaclass=, fails at compile time. Limits and errors lists each one.

State-machine pattern

class Counter:
  def __init__(self, n=0):
    self.n = n
  def tick(self):
    self.n += 1
  def value(self):
    return self.n

c = Counter()
c.tick()
c.tick()
c.tick()
print(c.value())

{}

Output

Namespace pattern

A class with no __init__ and no per-instance state is a namespace. Its functions are called on the class itself.

class Status:
  IDLE = 0
  RUNNING = 1
  DONE = 2

class Math:
  PI = 3.14159
  def square(x):
    return x * x
  def cube(x):
    return x * x * x

print(Status.IDLE)
print(Math.PI)
print(Math.square(5))
print(Math.cube(3))

{}

Output

Inheritance and super()

A class takes one base or several, as in class Sub(Base): and class C(A, B):.

Methods missing on the subclass resolve along the C3 linearization, the MRO.
An inconsistent hierarchy raises TypeError at class creation.
isinstance(x, Base) walks the ancestor chain. A Sub instance is an instance of every ancestor.

super() with no arguments delegates to the next class up the chain, bound to the current self. It is most common in __init__ to extend a base constructor.

class Animal:
  def __init__(self, name):
    self.name = name
  def describe(self):
    return self.name

class Dog(Animal):
  def __init__(self, name, breed):
    super().__init__(name)
    self.breed = breed
  def describe(self):
    return super().describe() + " (" + self.breed + ")"

d = Dog("Rex", "lab")
print(d.describe())
print(isinstance(d, Animal))

{}

Rex (lab)
True

Output

class A:
  def who(self):
    return "A"
class B(A):
  def who(self):
    return "B"
class C(A):
  def who(self):
    return "C"
class D(B, C):
  pass

print(D().who())  # B comes first in the C3 order

try:
  class Bad(A, B):
    pass
except TypeError:
  print("inconsistent hierarchy")

{}

B
inconsistent hierarchy

Output

Attribute access on classes vs instances

Access form	Resolves to
`MyClass.attr`	class member, returned as-is (no binding)
`MyClass.method()`	method called directly, no `self`
`instance.attr`	instance `__dict__` first, then class
`instance.method()`	bound method, `self` prepended

setattr and delattr work on instances and on class objects. On a class object they change the members of the class.

Class decorators

A class decorator is called with the class object, and its return value binds to the name. It can add or replace class attributes (cls.kind = ...) or return a replacement.

def tag(cls):
  cls.kind = "tagged"
  return cls

@tag
class Box:
  def __init__(self, v):
    self.v = v

print(Box.kind)
print(Box(7).v)

{}

tagged
7

Output

Properties

@property turns a method into a read-only attribute. @x.setter makes it writable. Properties live on the class, and subclasses inherit and can override either side.

class Temp:
  def __init__(self, c):
    self._c = c
  @property
  def celsius(self):
    return self._c
  @celsius.setter
  def celsius(self, value):
    self._c = value
  @property
  def fahrenheit(self):
    return self._c * 9 / 5 + 32

t = Temp(20)
print(t.celsius)
print(t.fahrenheit)
t.celsius = 100
print(t.fahrenheit)

{}

20
68.0
212.0

Output

Static methods

@staticmethod makes a method that receives no implicit self. It is a plain function in the class namespace.

It is callable as Class.method(...) or instance.method(...) with the same arguments.
Subclasses inherit it and can override it.
It suits helpers that belong to a class but need no receiver.

class Geometry:
  @staticmethod
  def add(a, b):
    return a + b
  @staticmethod
  def triangle_area(base, height):
    return base * height / 2

print(Geometry.add(2, 3))
print(Geometry().triangle_area(10, 4))

{}

5
20.0

Output

Class methods

@classmethod binds the class, not the instance, as the first argument. Through a subclass, cls is the subclass. Alternate constructors then return the right type down the hierarchy.

class Color:
  def __init__(self, r, g):
    self.r, self.g = r, g
  @classmethod
  def rgb(cls, r, g=0):
    return cls(r, g)
  @classmethod
  def which(cls):
    return cls.__name__

class Bright(Color):
  pass

c = Color.rgb(1, g=2)
print(c.r, c.g)
print(Color.which(), Bright.which())

{}

1 2
Color Bright

Output

The three decorators also work as plain calls without decorator syntax. The forms are property(fget, fset), staticmethod(func) and classmethod(func).

Operator overloading and protocols

Dunders such as __add__, __eq__ and __getitem__ plug a class into language protocols. Define them in the class body. The engine calls them when the matching operator, builtin or syntax form runs.

class V:
  def __init__(self, n):
    self.n = n
  def __add__(self, o):
    return V(self.n + o.n)
  def __eq__(self, o):
    return self.n == o.n

print((V(3) + V(4)).n)
print(V(3) == V(3))

{}

7
True

Output

Dunders are looked up on the class chain, and subclasses inherit them and may override them. The instance dict is skipped. Assigning obj.__add__ = ... has no effect.

Arithmetic

Operator	Forward	Reflected
`a + b`	`__add__`	`__radd__`
`a - b`	`__sub__`	`__rsub__`
`a * b`	`__mul__`	`__rmul__`
`a / b`	`__truediv__`	`__rtruediv__`
`a // b`	`__floordiv__`	`__rfloordiv__`
`a % b`	`__mod__`	`__rmod__`
`a ** b`	`__pow__`	`__rpow__`
`a @ b`	`__matmul__`	`__rmatmul__`
`-a`	`__neg__`	-
`+a`	`__pos__`	-

The engine picks between the forward and the reflected dunder by these rules.

A forward dunder that returns NotImplemented makes the engine try the reflected one on the other operand.
If both return NotImplemented, or neither is defined, the operation raises TypeError.
When type(b) is a strict subclass of type(a), b.__radd__ runs before a.__add__. A subclass can then override an inherited reflected op without touching the base.
An augmented assignment such as a += b first calls the in-place dunder (__iadd__, __imatmul__ and the rest). It falls back to the pair above when that dunder is missing or returns NotImplemented.

class Money:
  def __init__(self, n): self.n = n
  def __add__(self, o):
    return Money(self.n + (o.n if isinstance(o, Money) else o))
  def __radd__(self, o):
    return Money(o + self.n)

print((Money(10) + Money(5)).n)
print((3 + Money(7)).n)

{}

15
10

Output

Bitwise and shifts

The bitwise and shift operators follow the same forward and reflected protocol.

Operator	Forward	Reflected
`a \| b`	`__or__`	`__ror__`
`a & b`	`__and__`	`__rand__`
`a ^ b`	`__xor__`	`__rxor__`
`a << b`	`__lshift__`	`__rlshift__`
`a >> b`	`__rshift__`	`__rrshift__`
`~a`	`__invert__`	-

Comparison

Operator	Forward	Reflected
`a == b`	`__eq__`	`__eq__`
`a != b`	`__ne__`	`__ne__`
`a < b`	`__lt__`	`__gt__`
`a <= b`	`__le__`	`__ge__`
`a > b`	`__gt__`	`__lt__`
`a >= b`	`__ge__`	`__le__`

When __ne__ is absent, != falls back to not __eq__, coerced to bool. Every other comparison returns the raw result of its dunder. A __lt__ that returns 'A.lt' yields the string, not True.

class N:
  def __init__(self, v):
    self.v = v
  def __eq__(self, o):
    return self.v == o.v

print(N(1) != N(2))
print(N(1) != N(1))

{}

True
False

Output

Truth and length

bool(x) and any boolean context consult these in order.

__bool__ if defined. It must return bool, else TypeError.
__len__ if defined. False when the length is 0, else True.
Default True.

len(x) calls __len__ directly. It must return a non-negative int.

class Empty:
  def __bool__(self):
    return False

class Container:
  def __init__(self, n): self.n = n
  def __len__(self):
    return self.n

print(bool(Empty()))
print(bool(Container(0)), bool(Container(3)))
print(len(Container(5)))

{}

False
False True
5

Output

Indexing and containment

Form	Dunder	Arguments
`obj[i]`	`__getitem__`	`(self, i)`
`obj[i] = v`	`__setitem__`	`(self, i, value)`
`del obj[i]`	`__delitem__`	`(self, i)`
`v in obj`	`__contains__`	`(self, value)`

Slices pass as a slice object. obj[1:3] calls __getitem__(self, slice(1, 3, None)).
Indexes on builtin sequences coerce through __index__, slice bounds included. Dict keys never coerce.
Without __contains__, v in obj iterates obj and compares with __eq__.

class Store:
  def __init__(self):
    self.data = {}
  def __setitem__(self, key, value):
    self.data[key] = value
  def __getitem__(self, key):
    return self.data.get(key, "missing")
  def __contains__(self, key):
    return key in self.data

s = Store()
s["a"] = 1
print(s["a"], s["b"])
print("a" in s, "z" in s)

{}

1 missing
True False

Output

Iteration

Method	Role
`__iter__`	Returns an iterator (often `self`).
`__next__`	Returns the next item, or raises `StopIteration` to end the loop.

class Up:
  def __init__(self, stop):
    self.i = 0
    self.stop = stop
  def __iter__(self):
    return self
  def __next__(self):
    if self.i >= self.stop:
      raise StopIteration
    self.i += 1
    return self.i

print(list(Up(3)))
print(2 in Up(3))

{}

[1, 2, 3]
True

Output

for loops, list(x) and tuple(x) all honor the protocol.

Callable

__call__ makes instances callable. Positional and keyword arguments pass through like any method call.

class Double:
  def __call__(self, x, times=2):
    return x * times

d = Double()
print(d(7))
print(d(7, times=3))
print(callable(d))

{}

14
21
True

Output

Hashing

An instance hashes by identity, so it can be a dict key or a set item. A class that defines __eq__ is unhashable, and {x: 1} raises TypeError, since two equal instances could hash apart.

class K:
  def __init__(self, n): self.n = n

k = K(5)
print({k: 'found'}[k])
print(K(5) in {k}) # another instance is another key

{}

found
False

Output

Representation

Function / form	Dunder	Fallback
`repr(x)`	`__repr__`	`<ClassName instance>`
`str(x)`, `print(x)`	`__str__`	`__repr__`, then default
`f"{x}"` (no spec)	`__str__`	same as `str(x)`
`f"{x:spec}"`	`__format__`	`TypeError` for a non-empty spec
`f"{x!r}"`	`__repr__`	-

__format__(spec) receives the spec string and must return str.

class P:
  def __init__(self, n):
    self.n = n
  def __repr__(self):
    return f"P({self.n})"

p = P(3)
print(repr(p))
print(str(p))  # falls back to __repr__
print(f"{p!r}")
print([p])  # containers use __repr__

{}

P(3)
P(3)
P(3)
[P(3)]

Output

Numeric conversion

Function / form	Dunder	Fallback
`int(x)`	`__int__`	-
`float(x)`	`__float__`	`__index__`
`abs(x)`	`__abs__`	-
`%d`, `%x`, `%X`, `%o`	`__int__`	-

class Money:
  def __init__(self, cents):
    self.cents = cents
  def __int__(self):
    return self.cents // 100
  def __float__(self):
    return self.cents / 100
  def __abs__(self):
    return Money(abs(self.cents))

m = Money(1250)
print(int(m), float(m), abs(Money(-5)).cents)
print("%d dollars" % m)

{}

12 12.5 5
12 dollars

Output

Attribute access fallback

__getattr__(self, name) runs only when normal lookup misses. Normal lookup checks the instance dict, then the class chain. The dunder receives the name as a string and returns the value, or raises AttributeError to report a real miss.

class Proxy:
  def __init__(self):
    self.real = 1
  def __getattr__(self, name):
    return f"computed:{name}"

p = Proxy()
print(p.real)  # existing attribute, no fallback
print(p.anything)
print(p.foo)

{}

1
computed:anything
computed:foo

Output

Context managers

__enter__ and __exit__ make an instance usable in with. Control flow covers the order of calls, the arguments of __exit__ and suppression.

Reuse behavior through free functions and composition by default. Reach for inheritance and operator overloading when the abstraction calls for them.

AsyncCooperative coroutines with run, sleep, gather and cancel.BuiltinsThe builtins that build and inspect classes.