The big ideas of Python, from the interpreter up

Contract

The language promises only that unreachable objects may be reclaimed. It promises nothing about when, and other implementations such as PyPy use tracing GCs. CPython adds a de facto guarantee that a lot of code relies on: an object with no cycles is destroyed as soon as its last reference goes away, so __del__ and weakref callbacks run at a predictable point.

How it works

Every object header holds ob_refcnt. Py_INCREF and Py_DECREF adjust it, and reaching zero calls the type's tp_dealloc immediately. Cycles never reach zero, so container objects (those with Py_TPFLAGS_HAVE_GC) are also tracked by a generational collector. To find unreachable cycles it copies each tracked object's refcount into gc_refs, then subtracts one for every reference coming from another tracked object. Objects left with $\mathtt{gc\_refs}>0$ are referenced from outside, so they are reachable roots. Everything reachable from those roots is kept, and the rest is garbage.

import gc, sys
x = []
sys.getrefcount(x)      # 2: x, plus the call's own argument
gc.get_threshold()      # (700, 10, 10) in 3.12

Contract

object.__getattribute__(obj, name) looks up name along type(obj).__mro__. If the attribute found there is a data descriptor (it defines __set__ or __delete__), its __get__ wins. Otherwise obj.__dict__[name] wins if present. Otherwise a non-data descriptor's __get__ is called (this is how functions become bound methods), or the plain class attribute is returned. Only if all of that fails is __getattr__ called. property, classmethod, staticmethod, __slots__ members and methods are all descriptors.

The MRO is the C3 linearization:

where merge repeatedly takes the first head that doesn't appear in the tail of any list. If no head qualifies, there is no consistent order and class creation raises TypeError.

How it works

C3 guarantees three properties. Local precedence: the order of bases in each class statement is kept. Monotonicity: a class's MRO is a subsequence-preserving extension of each parent's MRO. Extended precedence graph consistency. Together they make cooperative super() work: super().m() means "the next class in type(self).__mro__ after this one," which may be a sibling, not a parent. Lookups are cached per type in a method cache keyed by type version tags, so the walk is usually skipped.

class Base:
    def save(self): print("Base")
class Logged(Base):
    def save(self): print("Logged"); super().save()
class Cached(Base):
    def save(self): print("Cached"); super().save()
class Model(Logged, Cached): pass
Model().save()   # Logged, Cached, Base: super() reached a sibling

Contract

Average $O(1)$ lookup, insertion and deletion for keys with a well-distributed __hash__ consistent with __eq__. Iteration follows insertion order (guaranteed since 3.7). Mutating a dict's size while iterating over it raises RuntimeError.

How it works

Since 3.6 the table is split in two. The indices array has $2^k$ slots, each holding a small integer index or EMPTY/DUMMY. The entries array stores (hash, key, value) in insertion order. This saves memory, because the sparse part holds 1-byte indices for small tables, and it gives ordered iteration for free. A lookup starts at slot i = hash & mask and probes

The recurrence $i\mapsto 5i+1 \pmod{2^k}$ alone visits every slot. Mixing in perturb brings in the high hash bits, so keys that agree in their low bits don't trace the same path. The table is resized when the usable entries, $\lfloor 2\cdot2^k/3\rfloor$, run out. Deleted entries still use up that budget until the next resize.

hash(8), hash(16), hash(-1)   # (8, 16, -2): small ints hash to themselves
{0: 0, 8: 0, 16: 0}            # all start at slot 0 of an 8-slot table

Contract

Bytecode is an implementation detail. Its format can change in any minor release, and .pyc files carry a magic number for exactly that reason. What's stable is the dis module as an inspection tool, and the semantics the bytecode implements.

How it works

The compiler turns the AST into a code object holding co_code (2-byte instructions plus inline cache entries), constants, names and a table of local variable slots. _PyEval_EvalFrameDefault runs a frame: fetch an instruction, jump to its handler (via computed gotos, generated from Python/bytecodes.c since 3.12), and manipulate a value stack. Locals live in an array indexed by LOAD_FAST's argument, which is why local variables are faster than globals, which go through a dict lookup (cached since 3.11). Each loop iteration in the lab costs nine instructions, each with its own dispatch, reference-count traffic and type checks.

import dis
def f(n):
    total = 0
    for i in range(n):
        total += i * i
    return total
dis.dis(f)

Contract

Semantics are unchanged. Specialization is invisible except through speed and dis.dis(f, adaptive=True). Code whose types are stable at each site gets faster, and code that's polymorphic at a site gets the generic path.

How it works

PEP 659 gives each specializable instruction inline cache entries holding a counter. After a short warm-up, the instruction specializes for the operand types it is currently seeing. BINARY_OP becomes BINARY_OP_ADD_INT, BINARY_OP_ADD_FLOAT or BINARY_OP_ADD_UNICODE. LOAD_ATTR becomes LOAD_ATTR_INSTANCE_VALUE, and so on. A specialized instruction starts with a cheap guard (is this still an int?). If the guard fails, it runs the generic code. Repeated failures make it de-specialize and try again after an exponential back-off. This is quickening without a JIT. The tier-2 optimizer and experimental copy-and-patch JIT in 3.13 (PEP 744) build on the same type information.

Contract

import m checks sys.modules["m"]. On a miss it asks each finder on sys.meta_path for a spec, creates the module object, inserts it into sys.modules, and then executes the module's code in the module's namespace. Later imports return the cached object without running the code again.

How it works

Registering before executing is what makes cycles terminate. If a imports b and b imports a, the inner import a finds the partially initialized a already in sys.modules and binds it immediately. Anything a defines after its import b line doesn't exist yet. Accessing it at b's top level fails, while accessing it later, inside a function called after both modules have finished, works. from a import X fails earlier still, because it reads the attribute at import time.

AttributeError: partially initialized module 'a' has no attribute 'X'
(most likely due to a circular import)

Contract

Python's float is IEEE 754 binary64 on every platform CPython supports. Basic operations are correctly rounded:

math.fsum returns the correctly rounded sum of its inputs. math.ulp, math.nextafter and float.hex expose the representation directly.

How it works

Rounding is relative, so it's harmless until cancellation. If $a\approx b$, then $\mathrm{fl}(a)-\mathrm{fl}(b)$ has an absolute error of about $u\max(|a|,|b|)$, but the result is small, so its relative error is about $u\,|a|/|a-b|$. The textbook one-pass variance $\frac1n\sum x_i^2-\bar x^2$ subtracts two numbers of size $\mu^2$ to get $\sigma^2$. Its relative error grows like $u\,\mu^2/\sigma^2$, and once $\mu/\sigma\gtrsim10^8$ the result is noise, and can even be negative. Welford's update and the two-pass algorithm work with deviations from the mean and are stable. statistics.variance goes further and computes with exact fractions.

Contract

The documented costs (the "TimeComplexity" wiki page): append, pop() and indexing are amortized $O(1)$. insert(0, x) and pop(0) are $O(n)$. Use collections.deque for queues.

How it works

A list is an array of PyObject* with ob_size (length) and allocated (capacity). When append finds them equal, list_resize (3.12) asks for

which gives 0, 4, 8, 16, 24, 32, 40, 52, 64, 76, … Growth by a factor $r=1.125$ means the total elements moved across all resizes up to size $n$ is at most $\sum_k n r^{-k}\approx n\cdot\frac{r}{r-1}=9n$, so each append moves $O(1)$ elements on average. A small factor wastes little memory, and realloc can often grow the block in place, so the real copying cost is usually lower than that bound.

import sys
xs = []; sizes = []
for k in range(10):
    sizes.append(sys.getsizeof(xs)); xs.append(k)
sizes   # [56, 88, 88, 88, 88, 120, 120, 120, 120, 184]

Contract

Basic slicing (a[1:, ::2]), .T, reshape when the layout allows it, and broadcast_to return views that share memory with the original. Fancy indexing (a[[0, 2]]) and boolean masks return copies. np.shares_memory tells you which you got.

How it works

Element $(i_0,\ldots,i_{d-1})$ lives at byte address

A C-contiguous $3\times4$ int64 array has strides $(32,8)$. Its transpose has $(8,32)$, with the same buffer. a[:, ::2] doubles the second stride. a[::-1] uses a negative stride and moves the data pointer. Broadcasting sets a stride to 0, so one row is read repeatedly without being copied. reshape succeeds as a view only if the new shape can be produced by splitting or merging axes with compatible strides. Otherwise NumPy copies silently. Vectorized operations are fast because their inner loops are C loops that walk strides, not Python loops that dispatch bytecode (idea 4).

Contract

The language makes very few atomicity promises. Some built-in operations are documented as thread-safe in CPython (list.append, dict[k] = v, queue.Queue). Compound operations such as x += 1, check-then-act sequences and iterating while another thread mutates need a threading.Lock, whichever build you run.

How it works

With the GIL, a thread holds the interpreter until another thread asks for it. The holder notices the request at an "eval breaker" check and drops the GIL once the switch interval (sys.getswitchinterval(), 5 ms by default) has passed. Since 3.10 those checks happen only at specific points, mainly backward jumps and function entry. So a straight-line LOAD, BINARY_OP, STORE sequence is rarely interrupted in practice, which hides races that used to show up immediately. The free-threaded build (PEP 703, supported since 3.14) removes the GIL. Threads truly run at once, and built-in containers protect themselves with per-object locks, but += on a shared variable is still three separate steps.

counter = 0
def work():
    global counter
    for _ in range(100_000):
        counter += 1      # LOAD_GLOBAL, LOAD_CONST, BINARY_OP, STORE_GLOBAL

Contract

Inside one event loop, no two coroutines run at the same moment, and a coroutine is never interrupted between await points. asyncio.gather and TaskGroup (3.11) run tasks concurrently. asyncio.to_thread pushes blocking calls onto a thread pool. Cancellation is delivered as CancelledError at an await.

How it works

A task wraps a coroutine. Running one step means calling coro.send(None) until it yields a Future. The task then registers a callback on that future and goes back to the loop. Each iteration of BaseEventLoop._run_once works out how long it may sleep (until the earliest timer, or zero if there are ready callbacks), polls the selector for I/O, moves expired timers to the ready queue, and runs every callback that was ready at the start of the iteration. await asyncio.sleep(d) is just a timer on that heap.

Contract

Annotations have no runtime effect (apart from tools that read them). Type checkers such as mypy and pyright implement gradual typing: Any is compatible in both directions, which lets typed and untyped code mix. For a generic $G$ and $A<:B$ ($A$ is a subtype of $B$):

How it works

Variance follows from where the type parameter appears. If list[int] were a list[object], you could append a str through the list[object] view and then read it back through the list[int] name, which breaks soundness. Java arrays are covariant for historical reasons and pay with a runtime ArrayStoreException. A function that accepts any object can stand in wherever a function accepting int is expected, but not the other way around. PEP 695 (3.12) lets checkers infer variance for new-style type parameters.