#internals

Deep Reads

Deep Reads In-depth exploration of how systems and languages are built from the inside out. Book About [CPython Internals]({{< relref "deep/cpython/_index.md" >}}) Architecture, object model, memory management, compilation pipeline, and the evaluation loop

85. Sanitizers

85. Sanitizers Sanitizers are compiler instrumentation tools that detect low-level C and C++ defects at runtime. They are especially useful for CPython development because CPython is a large C program with manual memory management, custom allocators, platform-specific code paths, and many extension-module boundaries. A debug build catches CPython invariant violations. Sanitizers catch classes of C undefined behavior that may survive ordinary assertions. 85.1 What Sanitizers Detect Sanitizers insert checks into...

82. Running the Test Suite

82. Running the Test Suite The CPython test suite is one of the most important parts of the project. It protects language semantics, runtime behavior, standard library correctness, ABI stability, memory management invariants, and platform compatibility across operating systems and architectures. A CPython contributor spends a large amount of time inside the test system. Even small changes to parser logic, object lifetime handling, reference counting, imports, or threading can break...

37. Pattern Matching

37. Pattern Matching Pattern matching is Python’s structural matching system. It is implemented by the match statement and case clauses. match value: case 0: result = "zero" case [x, y]: result = x + y case {"name": name}: result = name case _: result = None Pattern matching is not a switch statement over constants only. It can inspect structure, bind names, test classes, match sequences, match mappings, apply guards,...

79. Memory Locality

79. Memory Locality Memory locality is the degree to which a program accesses memory that is close together in time and space. CPython is a dynamic object runtime. Most Python values are heap-allocated objects, accessed through pointers. This gives Python flexibility, but it also means execution often follows chains of references through memory. Example: total += obj.value At the machine level, this may touch: current frame evaluation stack local variable...

19. Parsing

19. Parsing Parsing is the stage that turns a token stream into syntax structure. The tokenizer recognizes lexical units. The parser recognizes grammatical structure. It decides whether a sequence of tokens is a valid Python program and, when it is valid, builds an abstract syntax tree. For this source: def add(a, b): return a + b the tokenizer produces tokens such as: NAME "def" NAME "add" LPAR "(" NAME "a"...

83. Debug Builds

83. Debug Builds A CPython debug build is a development build of the interpreter with extra runtime checks enabled. It is slower than a normal release build, but it exposes bugs that would otherwise appear as random crashes, memory corruption, reference leaks, or undefined behavior. Debug builds are used when modifying CPython itself, writing C extensions, investigating object lifetime bugs, or validating changes to the runtime. 83.1 What a Debug...

5. Runtime Systems

Chapter Title 40 Modules and Imports 41 Packages 42 The Import Lock 43 Descriptors 44 Classes and Metaclasses 45 The MRO 46 The GIL 47 Threads 48 Subinterpreters 49 Signals 50 Context Variables 51 Audit Hooks

46. The GIL

46. The GIL The Global Interpreter Lock, usually called the GIL, is CPython’s process-level execution lock for Python bytecode in the traditional build. It ensures that only one thread at a time executes Python code in a given interpreter. The GIL is not the same as Python’s threading API. Python can create many operating system threads. The restriction is that, in the normal CPython runtime, those threads do not run...

38. Comprehensions

38. Comprehensions Comprehensions are compact syntax for building containers or generator-like iterators from another iterable. CPython implements them as compiled code objects with their own execution scope. Common forms: [x * 2 for x in xs] {x * 2 for x in xs} {x: x * 2 for x in xs} (x * 2 for x in xs) These correspond to: list comprehension set comprehension dict comprehension generator expression They...

10. The Garbage Collector

10. The Garbage Collector CPython uses reference counting as its main memory management mechanism. Reference counting destroys most objects as soon as their last strong reference disappears. Reference counting has one major limitation: it cannot reclaim reference cycles by itself. The garbage collector exists to find unreachable cycles of container objects and reclaim them. It is a supplement to reference counting, not a replacement for it. 10.1 Why Reference Counting...

28. Frames

28. Frames A frame is the runtime record for one active execution of Python code. When CPython calls a Python function, executes a module body, runs a class body, resumes a generator, or resumes a coroutine, it uses a frame-like execution record to hold the current state. A code object says what to execute. A frame says where execution currently is and what values are currently live. code object =...

30. Bytecode Instructions

30. Bytecode Instructions Bytecode instructions are the operations executed by the CPython evaluation loop. They are the compact, interpreter-level form of Python code after parsing, AST construction, symbol analysis, and compilation. A Python function such as: def add(a, b): return a + b does not execute as source text. CPython compiles it into a code object. That code object contains an instruction stream. You can inspect that stream with dis...

81. Benchmarking CPython

81. Benchmarking CPython Benchmarking CPython means measuring execution speed in a controlled, repeatable way. Profiling answers where time is spent. Benchmarking answers how much a change affects performance. A benchmark should compare two states: baseline candidate The baseline may be an older CPython build, an earlier version of a function, or a different implementation strategy. The candidate is the version being tested. The goal is not to get one impressive...

21. Symbol Tables

21. Symbol Tables After parsing produces an AST, CPython performs scope analysis. This stage builds symbol tables. A symbol table records how names behave inside each scope. It determines whether a name is local, global, free, cell, parameter, imported, annotated, or referenced from nested scopes. For this source: x = 10 def outer(): y = 20 def inner(): return x + y return inner the parser only knows that names...

71. Calling C From Python

71. Calling C From Python Calling C from Python means exposing native functions, objects, or libraries so Python code can invoke them as if they were ordinary Python APIs. This is the most common direction for native integration: Python code calls wrapper wrapper calls C function C returns native result wrapper converts result to Python object CPython supports several ways to do this: Mechanism Main use C extension module Fast,...

77. Dictionary Performance

77. Dictionary Performance Dictionaries are one of the most important data structures in CPython. Python uses dictionaries for: global namespaces module namespaces instance attributes class attributes keyword arguments caches sets internals JSON-like data configuration objects symbol tables Many Python operations ultimately become dictionary operations. Examples: x = globals()["name"] obj.attr module.value kwargs["limit"] Because dictionaries are everywhere, CPython invests heavily in dictionary performance. Modern CPython dictionaries are compact, cache-friendly, insertion-ordered hash tables...

93. Immortal Objects

93. Immortal Objects Immortal objects are objects whose lifetime is treated as effectively permanent by the CPython runtime. Their reference counts no longer behave like ordinary objects, and the interpreter avoids many normal reference counting operations on them. Immortal objects were introduced as part of larger runtime optimization work, especially in support of free-threaded CPython and multicore scalability. The main idea is simple: some objects exist for the entire interpreter...

72. Interpreter Dispatch

72. Interpreter Dispatch Interpreter dispatch is the mechanism that drives bytecode execution inside CPython. The compiler transforms Python source code into bytecode instructions. The interpreter loop then repeatedly fetches, decodes, and executes those instructions. Dispatch is the process that selects the implementation for each opcode and transfers control to it. This chapter focuses on the execution engine inside CPython: Python source ↓ compiler ↓ bytecode ↓ evaluation loop ↓ opcode...

98. Serialization Internals

98. Serialization Internals Serialization is the process of converting Python objects into a representation that can be stored, transmitted, copied, or reconstructed later. In CPython, serialization appears in several forms: pickle marshal json copy protocols multiprocessing transfer bytecode cache files interpreter state exchange These systems are related, but they have different goals. The most important distinction is between general object serialization and CPython-internal serialization. pickle is a public object serialization...

59. `multiprocessing`

59. multiprocessing The multiprocessing module provides process-based concurrency. It lets Python programs create child processes, communicate between them, share limited state, coordinate execution, and distribute work across CPU cores. For CPython internals, multiprocessing matters because it is the standard library answer to a central runtime constraint: ordinary Python threads in one traditional CPython interpreter are limited by the Global Interpreter Lock during bytecode execution. Separate processes have separate interpreters, separate...

47. Threads

47. Threads A thread is an operating system execution context inside a process. CPython exposes threads through the threading module and implements lower-level support through _thread , platform thread APIs, interpreter thread state, locks, condition variables, and GIL coordination. Threads let a Python program perform multiple activities concurrently inside one process. In traditional CPython, threads do not usually execute Python bytecode in parallel because of the GIL. They are still...

1. Orientation

Chapter Title 1 What CPython Is 2 Building CPython From Source 3 Repository Layout 4 Reading CPython C Code 5 The Runtime Model 6 From Source Code to Execution

32. Method Calls

32. Method Calls Method calls are function calls that usually begin with attribute access. They are central to Python’s object model because most object behavior is exposed through methods. A method call such as: obj.method(arg) looks like one operation, but CPython executes several conceptual steps: load obj look up attribute method bind obj if needed load arg call the resolved callable return result or raise exception At the language level,...

25. Bytecode Generation

25. Bytecode Generation Bytecode generation is the stage where CPython transforms structured syntax into executable virtual machine instructions. The parser builds an AST. The symbol table determines scope behavior. The compiler then emits bytecode instructions that implement Python semantics. For this source: def add(a, b): return a + b CPython generates bytecode shaped like: LOAD_FAST a LOAD_FAST b BINARY_OP + RETURN_VALUE The exact instruction names and formats vary across Python...

97. Import System Edge Cases

97. Import System Edge Cases The CPython import system is the machinery that finds, loads, initializes, caches, and returns modules. It looks simple at the Python level: import json But internally, import is one of CPython’s most complex runtime systems. It must handle: source files bytecode cache files built-in modules frozen modules extension modules packages namespace packages relative imports import hooks path hooks module caching reloads partially initialized modules circular...

44. Classes and Metaclasses

44. Classes and Metaclasses A class is a runtime object that creates instances, stores attributes, participates in inheritance, and defines behavior through the Python object model. In CPython, a class is an object whose type is usually type . A metaclass is the class of a class. It controls how class objects are created, initialized, represented, and called. For normal classes: class User: pass print(type(User)) Output: <class 'type'> This means...

16. Dictionaries and Sets

16. Dictionaries and Sets Dictionaries and sets are CPython’s primary hash-table containers. A dictionary maps keys to values. A set stores keys without associated values. They are used everywhere in Python: module globals class namespaces instance attributes keyword arguments function annotations import caches memoization tables membership indexes deduplication sets A large part of Python’s runtime performance depends on dictionary performance. 16.1 Dictionary Semantics A dictionary maps hashable keys to values....

11. Memory Allocators

11. Memory Allocators CPython allocates memory constantly. Every integer object, list object, frame, tuple, dict entry array, string buffer, code object, exception, module, and function needs memory. The allocator system exists to make these allocations fast, structured, debuggable, and portable across platforms. CPython does not use only one allocator. It uses several allocator domains and layers. Small Python objects often go through CPython’s specialized small-object allocator, while larger buffers may...

58. `ctypes`

58. ctypes The ctypes module is CPython’s built-in foreign function interface. It lets Python code load shared libraries, call C functions, define C-compatible data types, pass pointers, receive callbacks from native code, and inspect or mutate raw memory. ctypes is part of the standard library, but it sits very close to the C ABI. It can cross the normal safety boundary of Python. Correct use requires understanding memory layout, calling...

68. Limited API

68. Limited API The limited API is a restricted source-level subset of the CPython C API. It is selected at compile time and designed to let extension modules target the stable ABI. The stable ABI is the binary promise. The limited API is the programming surface used to reach that promise. extension source code ↓ #define Py_LIMITED_API ↓ limited API declarations ↓ stable ABI compatible binary ↓ abi3 wheel The...

15. Lists, Tuples, and Arrays

15. Lists, Tuples, and Arrays Lists, tuples, and array-like objects represent ordered collections. They all support indexed access, but they have different storage models, mutability rules, and performance tradeoffs. A list is a mutable sequence of object references. A tuple is an immutable sequence of object references. An array-like object stores compact typed data or exposes a contiguous buffer. These distinctions matter because CPython containers store references unless the type...

1. What CPython Is

1. What CPython Is CPython is the primary implementation of the Python programming language. It is the implementation most people use when they install Python from python.org, package managers, Linux distributions, Homebrew, pyenv, Docker images, or most cloud runtimes. CPython has two roles. First, it implements the Python language. It defines how Python source code is parsed, compiled, executed, and connected to the standard library. Second, it acts as the...

94. Per-Interpreter GIL

94. Per-Interpreter GIL The per-interpreter GIL is a CPython runtime design where each subinterpreter owns its own Global Interpreter Lock instead of all interpreters sharing one process-wide lock. The traditional model used one GIL for the whole process: process runtime global GIL interpreter A interpreter B interpreter C The per-interpreter model moves the lock down into each interpreter: process runtime interpreter A GIL A interpreter B GIL B interpreter C...

6. Standard Library Interfaces to the Core

Chapter Title 52 sys 53 inspect 54 dis 55 gc 56 types 57 importlib 58 ctypes 59 multiprocessing 60 asyncio

9. Reference Counting

9. Reference Counting Reference counting is CPython’s primary memory management mechanism. Every ordinary object carries a count of strong references that currently point to it. When that count falls to zero, CPython can destroy the object immediately. This design is one of the clearest differences between CPython and many other language runtimes. CPython does have a cyclic garbage collector, but the collector supplements reference counting. Most objects are reclaimed by...

3. Repository Layout

3. Repository Layout The CPython repository is organized around the major subsystems of the interpreter: object implementations, runtime machinery, compiler pipeline, parser, built-in modules, standard library, tests, documentation, and platform build files. A good first pass is to treat the source tree as a map of responsibilities. cpython/ Include/ Objects/ Python/ Parser/ Modules/ Lib/ Programs/ Tools/ Doc/ Grammar/ PC/ PCbuild/ Mac/ Each directory has a different role. Some contain core...

92. Free-Threaded CPython

92. Free-Threaded CPython Free-threaded CPython is a major redesign of the interpreter runtime that removes the traditional Global Interpreter Lock (GIL) and allows multiple threads to execute Python bytecode concurrently within the same interpreter. Historically, CPython relied on the GIL to serialize execution of Python code. The GIL simplified memory management, reference counting, object mutation, allocator coordination, and internal runtime invariants. Only one thread at a time executed Python bytecode...

100. Future Directions

100. Future Directions CPython’s future direction is shaped by one central pressure: keep Python compatible and understandable while making the runtime scale better on modern hardware. The main areas are: free-threaded execution per-interpreter isolation JIT compilation adaptive specialization C API modernization extension compatibility memory layout optimization startup-time reduction better tooling and observability CPython changes slowly because it carries a large ecosystem. The interpreter cannot optimize by breaking the language model,...

50. Context Variables

50. Context Variables Context variables provide task-local state for concurrent Python programs. They are implemented by the contextvars module and are designed mainly for asynchronous code, where many logical tasks can run on the same operating system thread. A context variable looks like a global variable from the caller’s point of view, but its value belongs to the current logical execution context. This solves a problem that thread-local storage cannot...

67. Stable ABI

67. Stable ABI The stable ABI is CPython’s binary compatibility interface for extension modules. It lets an extension module be compiled once and loaded by multiple CPython versions, as long as those versions support the requested ABI level. The normal CPython C API exposes many implementation details. An extension compiled against those details often needs a separate binary wheel for each Python version. The stable ABI reduces that burden by...

8. PyObject and PyVarObject

8. PyObject and PyVarObject PyObject and PyVarObject are the base layouts behind CPython objects. They are not Python classes. They are C-level struct conventions that allow the runtime to treat many different object implementations through a common pointer type. At runtime, most object references in CPython are represented as: PyObject * This means “pointer to some Python object.” The pointed-to memory may actually be an integer object, list object, dict...

9. Development Workflow

Chapter Title 82 Running the Test Suite 83 Debug Builds 84 GDB and LLDB 85 Sanitizers 86 Tracing Memory Bugs 87 Writing Core Tests 88 Documentation Workflow 89 Making a CPython Patch 90 Reading PEPs 91 Release Process

66. Capsules

66. Capsules A capsule is a CPython object that stores an opaque C pointer. It allows extension modules to expose native pointers to other extension modules without making those pointers directly visible to normal Python code. Capsules are used when C code needs to share a function table, context pointer, type registry, library handle, allocator, or native resource across module boundaries. At Python level, a capsule usually appears as an...

33. Attribute Lookup

33. Attribute Lookup Attribute lookup is the runtime process used to evaluate expressions such as: obj.name It is one of the most important mechanisms in CPython. Method calls, properties, descriptors, inheritance, modules, classes, slots, special methods, and many object protocols depend on it. A simple attribute expression can trigger a large amount of machinery: find the object's type search the type and its base classes handle descriptors check the instance...

5. The Runtime Model

5. The Runtime Model The CPython runtime is the machinery that exists after the process starts and before Python code finishes executing. It owns interpreter state, thread state, modules, builtins, memory allocators, exception state, import state, frames, pending calls, signal handling, and shutdown behavior. A Python program appears to run as a sequence of statements. CPython runs it inside a layered runtime system. operating system process CPython runtime interpreter state...

20. The AST

20. The AST The abstract syntax tree, usually called the AST, is the structured representation of Python source code after parsing. The tokenizer produces a flat stream of tokens. The parser recognizes grammar. The AST records the result as a tree of statements and expressions. For this source: x = 1 + 2 the AST is shaped like this: Module Assign targets: Name id="x", ctx=Store value: BinOp left: Constant value=1...

54. `dis`

54. dis The dis module exposes CPython bytecode in a readable form. It is the standard tool for seeing what CPython actually executes after source code has passed through the compiler. Python source code is not executed directly. CPython compiles it into code objects. Each code object contains bytecode, constants, names, local variable metadata, exception handling metadata, and source position information. The dis module reads those code objects and formats...

7. C API and Extensions

Chapter Title 61 The Python C API 62 Reference Ownership Rules 63 Creating Extension Modules 64 Defining New Types 65 Buffer Protocol 66 Capsules 67 Stable ABI 68 Limited API 69 Embedding Python 70 Calling Python From C 71 Calling C From Python

57. `importlib`

57. importlib The importlib module exposes Python’s import system as ordinary Python APIs. It is both a library for importing modules programmatically and a reference implementation for much of the import machinery. The import system is one of CPython’s central runtime subsystems. Every import statement passes through machinery that checks module caches, resolves names, searches import paths, selects finders, builds module specifications, invokes loaders, initializes module objects, and records the...

99. Security Boundaries

99. Security Boundaries CPython is a language runtime, not a sandbox. It provides mechanisms for executing Python code, loading modules, managing objects, calling native extensions, opening files, creating processes, using sockets, and interacting with the operating system. These features are useful because Python is a general-purpose programming language, but they also mean that executing untrusted Python code inside ordinary CPython is unsafe. A security boundary is a line across which...

73. Inline Caches

73. Inline Caches Inline caches are small cache records stored near bytecode instructions. They let CPython remember facts discovered during previous executions of an instruction, then reuse those facts on later executions. The goal is simple: avoid repeating expensive dynamic lookups when the runtime situation has not changed. For example, this expression looks small: obj.name But generic attribute lookup may involve: look at obj type check descriptors check instance dictionary...

34. Exception Handling

34. Exception Handling Exception handling is the control-flow system CPython uses when an operation cannot complete normally. It covers explicit raise statements, failed operations, failed imports, failed calls, generator termination, context manager cleanup, traceback construction, and propagation through frames. At source level, exceptions look like this: try: value = risky() except ValueError: value = 0 At runtime, CPython must: execute the protected bytecode range detect failure record the active exception...

80. Profiling CPython

80. Profiling CPython Profiling CPython means measuring where time, memory, allocations, and interpreter work are spent. It is the practical bridge between a performance suspicion and a performance explanation. A Python program can be slow for many different reasons: too many Python function calls slow attribute lookup large dictionary workloads excessive allocation poor memory locality I/O waiting bad algorithmic complexity C extension overhead lock contention garbage collection pauses Profiling separates...

62. Reference Ownership Rules

62. Reference Ownership Rules Reference ownership is the core memory discipline of the Python C API. Every PyObject * points to a Python object whose lifetime is controlled by a reference count. Native extension code must follow ownership rules exactly. A single missing Py_DECREF can leak memory. A single extra Py_DECREF can free a live object and corrupt the interpreter. 62.1 Why Ownership Rules Exist CPython stores a reference count...

69. Embedding Python

69. Embedding Python Embedding Python means starting and controlling the CPython runtime from a native application. Instead of Python importing a C extension, a C or C++ program initializes Python, executes Python code, exchanges objects with it, then shuts the interpreter down. The direction is reversed: extension module: Python process imports native code embedding: native process starts Python runtime Embedding is used when Python is the scripting layer inside a...

56. `types`

56. types The types module exposes names for many runtime object types used internally by CPython. It gives Python code a stable way to ask, “What kind of runtime object is this?” without hard-coding obscure expressions such as type(lambda: None) or type((x for x in [])) . The module is small, but it sits close to the object model. It names function objects, method objects, module objects, frame objects, code...

45. The MRO

45. The MRO The method resolution order, usually called the MRO, is the ordered list of classes CPython searches when resolving attributes through a class hierarchy. For a simple class: class A: pass class B(A): pass the MRO of B is: print(B.__mro__) Output shape: (<class '__main__.B'>, <class '__main__.A'>, <class 'object'>) This means CPython searches B , then A , then object . The MRO is central to inheritance, method lookup,...

29. Stack-Based Execution

29. Stack-Based Execution CPython executes most bytecode with a stack machine. A stack machine uses an implicit operand stack instead of naming explicit source and destination registers in every instruction. In CPython, this stack belongs to the current frame. It stores references to Python objects. Bytecode instructions push objects, pop objects, inspect objects, replace objects, and use objects to compute new results. A simple expression: x = a + b...

96. Stable ABI Design Tradeoffs

96. Stable ABI Design Tradeoffs The CPython Stable ABI is a compatibility layer that allows extension modules compiled against one Python version to continue working across multiple later Python versions without recompilation. The Stable ABI exists to reduce binary compatibility problems in the Python extension ecosystem. Without a stable ABI: extension compiled for Python 3.x may fail on Python 3.y because internal structures, function layouts, macros, or object representations change....

63. Creating Extension Modules

63. Creating Extension Modules An extension module is a native shared library loaded by CPython at runtime. It exposes functions, types, constants, and state implemented in C or C-compatible languages. From Python code, an extension module behaves like a normal module: import math import zlib import _sqlite3 Internally, these modules are compiled native binaries that integrate with the CPython runtime through the Python C API. Extension modules are one of...

2. Building CPython From Source

2. Building CPython From Source Building CPython from source gives you a local interpreter that you can inspect, modify, debug, and test. This is the first practical step before reading internals seriously. A source build lets you do things that a packaged Python install usually hides: change interpreter code add debug prints inspect object layout run CPython tests use debug-only assertions trace reference counts debug crashes in C compare bytecode...

87. Writing Core Tests

87. Writing Core Tests Core tests in CPython are regression tests for the interpreter, the standard library, and the C API. They are written to protect behavior that CPython promises to users, extension authors, and downstream distributors. A good CPython test is small, deterministic, isolated, and directly connected to a specific behavior. It should fail before the fix and pass after the fix. It should avoid timing assumptions, external services,...

23. Code Objects

23. Code Objects A code object is CPython’s compiled representation of executable Python code. It contains bytecode and metadata. The interpreter can execute it, but the code object itself does not carry runtime state such as globals, default arguments, closure cells, or bound methods. For this source: def add(a, b): return a + b the function object add contains a code object: code = add.__code__ print(code.co_name) print(code.co_varnames) print(code.co_consts) print(code.co_names) The...

65. Buffer Protocol

65. Buffer Protocol The buffer protocol is CPython’s low-level interface for sharing raw memory between Python objects without copying. It allows one object to expose a contiguous or strided block of memory, and another object to read or write that memory through a common C structure. The protocol is used by objects such as: Object Buffer use bytes Read-only contiguous byte storage bytearray Mutable contiguous byte storage memoryview General Python-level...

86. Tracing Memory Bugs

86. Tracing Memory Bugs Memory bugs in CPython are difficult because the visible failure often happens far away from the original mistake. A missing Py_INCREF , an extra Py_DECREF , a wrong allocator call, or an incomplete GC traversal may corrupt state silently. The crash may appear thousands of bytecode instructions later. Tracing memory bugs means reconstructing object lifetime: where an object was allocated, who owns it, when its reference...

31. Function Calls

31. Function Calls Function calls are one of the most important execution paths in CPython. A call connects several systems at once: bytecode execution, frames, argument binding, descriptors, methods, closures, the C API, reference counting, exceptions, and return handling. A simple call: result = f(1, 2) looks small at the source level. At runtime, CPython must: load the callable load the arguments choose the correct call protocol bind arguments to...

35. Generators

35. Generators Generators are resumable functions. A normal function starts, runs, and finishes with one return value. A generator can start, produce a value, suspend its frame, later resume from the same instruction position, produce another value, and repeat until it finishes. A generator function is any function body that contains yield . def numbers(): yield 1 yield 2 yield 3 Calling this function does not run the body immediately....

24. Constants, Names, and Locals

24. Constants, Names, and Locals A code object does not store Python source code as text. It stores compact tables and bytecode instructions that refer to those tables by index. Three of the most important tables are: co_consts co_names co_varnames They separate repeated data from the instruction stream. For this function: def f(a): b = len(a) return b + 1 CPython stores: constants: None 1 names: len local variables: a...

17. Integers, Floats, and Complex Numbers

17. Integers, Floats, and Complex Numbers Python’s numeric objects are ordinary objects with specialized implementations. They participate in the same object model as lists, dictionaries, functions, classes, and modules: each value has an object header, a type pointer, reference counting behavior, and type slots for operations. The main built-in numeric types are: Type Python name Main representation Integer int Arbitrary-precision integer Boolean bool Singleton subclass of int Floating point float...

90. Reading PEPs

90. Reading PEPs A Python Enhancement Proposal, or PEP, is a design document for a significant change to Python. PEPs describe language changes, standard library changes, process rules, compatibility policy, governance, release schedules, and implementation plans. For CPython internals work, PEPs matter because many implementation choices exist to satisfy a design accepted years earlier. Reading only the C code often shows what CPython does. Reading the PEP explains why it...

12. Object Layout and Type Slots

12. Object Layout and Type Slots CPython represents every runtime value as an object. Each object has a memory layout, and each object’s type describes how that memory should be interpreted. The object layout answers: What fields exist inside this object? Where are the references to other Python objects? How large is one instance? Does the object have variable-sized trailing storage? Does the object participate in cyclic garbage collection? The...

52. `sys`

52. sys The sys module is CPython’s primary runtime interface exposed to Python code. It acts as a bridge between the interpreter core and user space. Almost every major subsystem in CPython eventually connects to sys in some form: interpreter startup, module imports, exception handling, memory management, execution limits, command-line configuration, standard streams, and runtime introspection. Unlike most standard library modules, sys is deeply tied to interpreter internals. Many values...

53. `inspect`

53. inspect The inspect module exposes structured runtime introspection. It lets Python code examine objects, functions, classes, methods, frames, tracebacks, source files, signatures, annotations, generators, coroutines, and descriptors. Where sys exposes low-level interpreter state, inspect builds higher-level views on top of that state. 53.1 The Role of inspect inspect answers questions about live Python objects: Question Example API What kind of object is this? inspect.isfunction() What parameters does this callable...

42. The Import Lock

42. The Import Lock The import lock is the synchronization machinery that prevents unsafe concurrent imports. In CPython, imports are not only name lookups. They may create module objects, mutate sys.modules , execute arbitrary Python code, initialize extension modules, update package attributes, compile source files, read bytecode caches, and run package initialization code. Without locking, two threads could import the same module at the same time and observe inconsistent module...

74. Specializing Adaptive Interpreter

74. Specializing Adaptive Interpreter The specializing adaptive interpreter is the optimization architecture introduced in modern CPython to reduce the cost of dynamic execution without requiring a full JIT compiler. Traditional interpreters execute generic bytecode instructions: LOAD_ATTR BINARY_OP CALL LOAD_GLOBAL These instructions must support every valid Python behavior. For example: a + b may mean: integer addition float addition string concatenation list concatenation custom __add__ custom __radd__ NumPy vector operation unsupported...

51. Audit Hooks

51. Audit Hooks Audit hooks are CPython’s runtime mechanism for observing security-sensitive and operationally important events. They let embedders, security tools, test harnesses, and monitoring systems receive notifications when Python code performs actions such as importing modules, opening files, starting subprocesses, compiling code, executing dynamic code, loading native extensions, or changing tracing state. Audit hooks do not replace operating system sandboxing. They are an observability and policy-enforcement mechanism inside the...

70. Calling Python From C

70. Calling Python From C Calling Python from C means using the CPython C API to invoke Python objects from native code. The callable may be a function, method, class, instance with __call__ , bound method, coroutine function, or any other object accepted by Python’s call protocol. This operation appears in both extension and embedding code. extension module: Python calls C C calls Python callback embedded application: C application starts...

76. Vectorcall

76. Vectorcall Vectorcall is CPython’s fast calling convention for many callable objects. Its purpose is to avoid building temporary argument containers for common function calls. Older generic calls often packaged positional arguments into a tuple and keyword arguments into a dictionary. That representation is flexible, but expensive. Vectorcall passes arguments as a compact C array of PyObject * pointers, often pointing directly into the interpreter stack. Conceptually: generic call: callable(args_tuple,...

84. GDB and LLDB

84. GDB and LLDB Native debuggers are essential when working on CPython internals. Python-level tools can show frames, variables, exceptions, and source lines, but they cannot fully explain crashes inside the C runtime. When a bug involves reference counts, object layout, frame state, memory corruption, invalid pointers, or C extension behavior, you need a native debugger. On Linux, CPython developers usually use GDB. On macOS, LLDB is common. Both can...

4. The Interpreter

Chapter Title 27 Evaluation Loop 28 Frames 29 Stack-Based Execution 30 Bytecode Instructions 31 Function Calls 32 Method Calls 33 Attribute Lookup 34 Exception Handling 35 Generators 36 Coroutines and Async 37 Pattern Matching 38 Comprehensions 39 Closures and Cells

36. Coroutines and Async

36. Coroutines and Async Coroutines are resumable computations used for asynchronous programming. They let Python code suspend at an await point, return control to an event loop, and later resume when the awaited operation has a result. A coroutine is similar to a generator because both preserve execution state across suspension. The difference is protocol and purpose. A generator yields values to an iterator consumer. A coroutine awaits other asynchronous...

60. `asyncio`

60. asyncio The asyncio module is CPython’s standard library framework for asynchronous I/O. It provides an event loop, tasks, futures, transports, streams, synchronization primitives, subprocess integration, timers, and APIs for coordinating many waiting operations in one thread. For CPython internals, asyncio matters because it exposes how async def , coroutine objects, await , futures, event loops, callbacks, and I/O readiness fit together. 60.1 The Role of asyncio asyncio is built...

7. The Python Object Model

7. The Python Object Model The Python object model is the foundation of CPython. Everything that runs in Python eventually becomes an operation on objects: integers, strings, lists, modules, functions, classes, exceptions, frames, and even compiled code. At the language level, Python says every object has an identity, a type, and a value. Object identity stays fixed after creation, is compares identity, and id() returns an integer representing that identity....

95. JIT Work in CPython

95. JIT Work in CPython A Just-In-Time compiler, usually called a JIT, dynamically compiles frequently executed program paths into native machine code during runtime execution. Traditional CPython primarily uses interpretation: Python source ↓ bytecode ↓ evaluation loop ↓ C implementation A JIT changes this model: Python source ↓ bytecode ↓ runtime profiling ↓ native machine code generation ↓ direct CPU execution The goal is improving performance by reducing interpreter overhead....

10. Advanced Topics

Chapter Title 92 Free-Threaded CPython 93 Immortal Objects 94 Per-Interpreter GIL 95 JIT Work in CPython 96 Stable ABI Design Tradeoffs 97 Import System Edge Cases 98 Serialization Internals 99 Security Boundaries 100 Future Directions

41. Packages

41. Packages A package is a module that can contain other modules. In CPython, a package is not a separate object category. It is still a module object, but it has import metadata that tells the import system where to look for submodules. At the Python level, this directory can be a package: app/ __init__.py config.py server.py You can import it as: import app import app.config from app.server import run...

40. Modules and Imports

40. Modules and Imports A module is Python’s basic unit of code loading, namespace isolation, and reuse. In CPython, a module is both a language-level object and a runtime record in the import system. At the Python level, a module is what you get after executing: import math import os import json Each imported name is bound to a module object, package object, function, class, or other exported object. At...

3. Compilation Pipeline

Chapter Title 18 Tokenization 19 Parsing 20 The AST 21 Symbol Tables 22 Compiler Passes 23 Code Objects 24 Constants, Names, and Locals 25 Bytecode Generation 26 Bytecode Optimization

89. Making a CPython Patch

89. Making a CPython Patch A CPython patch is a coordinated change to the interpreter, runtime, standard library, tests, documentation, and development metadata. Even a small fix may affect object lifetime, bytecode behavior, platform compatibility, import state, or public APIs. Making a good CPython patch requires more than changing code. The patch must preserve runtime invariants, include regression tests, follow repository conventions, build correctly across platforms, and explain user-visible behavior...

43. Descriptors

43. Descriptors A descriptor is an object that controls attribute access on another object. Descriptors are one of the main mechanisms behind Python’s object model. They explain how methods bind to instances, how property works, how staticmethod and classmethod work, how slots work, and how many CPython-level type operations connect to Python-level syntax. At the language level, a descriptor is any object that defines one or more of these methods:...

61. The Python C API

61. The Python C API The Python C API is the native programming interface exposed by CPython. It allows C programs to create Python objects, execute Python code, define extension modules, implement new object types, call Python functions, manipulate interpreter state, and embed the Python runtime inside larger applications. The C API is one of the central architectural features of CPython. It defines the boundary between the interpreter runtime and...

6. From Source Code to Execution

6. From Source Code to Execution CPython does not execute Python source text directly. It transforms source text through several internal representations before the first bytecode instruction runs. The path is: source text ↓ tokens ↓ parse tree ↓ abstract syntax tree ↓ symbol table ↓ code object ↓ frame ↓ bytecode evaluation ↓ object operations Each stage has a separate job. The tokenizer understands characters. The parser understands syntax....

48. Subinterpreters

48. Subinterpreters A subinterpreter is an interpreter instance inside the same CPython process. It has its own interpreter state, module table, builtins, import state, and execution context. It shares the same operating system process with other interpreters, but it is logically separated from them at the Python runtime level. A normal Python program usually runs with one main interpreter: process main interpreter modules builtins sys thread states frames With subinterpreters,...

55. `gc`

55. gc The gc module exposes CPython’s cyclic garbage collector. It gives Python code a way to inspect, configure, disable, enable, and manually run the collector that handles unreachable reference cycles. CPython’s main memory management mechanism is reference counting. Most objects are destroyed as soon as their reference count reaches zero. The cyclic garbage collector exists for the cases reference counting cannot solve: groups of objects that keep each other...

8. Performance Internals

Chapter Title 72 Interpreter Dispatch 73 Inline Caches 74 Specializing Adaptive Interpreter 75 Function Call Fast Paths 76 Vectorcall 77 Dictionary Performance 78 Attribute Access Performance 79 Memory Locality 80 Profiling CPython 81 Benchmarking CPython

4. Reading CPython C Code

4. Reading CPython C Code Reading CPython C code requires two mental models at the same time. The first model is ordinary C: structs, pointers, macros, function pointers, reference ownership, allocation, error returns, and conditional compilation. The second model is Python’s runtime model: objects, types, frames, exceptions, reference counts, descriptors, iterators, modules, and bytecode. Most CPython source files combine both. A line of C code may look like ordinary pointer...

49. Signals

49. Signals Signals are operating system notifications delivered to a process. CPython exposes them through the signal module and integrates them with the interpreter’s evaluation loop, thread model, pending-call machinery, and exception system. A signal is not a normal Python function call. It can arrive asynchronously from outside the program. Common examples: SIGINT interrupt from Ctrl-C SIGTERM termination request SIGALRM timer alarm on Unix SIGHUP terminal hangup or reload request...

78. Attribute Access Performance

78. Attribute Access Performance Attribute access is one of the most frequent operations in Python. It appears whenever code reads, writes, or deletes a named field on an object. obj.name obj.name = value del obj.name At source level, attribute access looks like a simple field operation. In CPython, it is a dynamic protocol involving object types, dictionaries, descriptors, slots, method binding, inheritance, inline caches, and specialization. A simple expression: obj.x...

14. Strings, Bytes, and Unicode

14. Strings, Bytes, and Unicode Text and binary data are separate object families in Python. str represents Unicode text. bytes represents immutable binary data. bytearray represents mutable binary data. This separation is one of Python 3’s most important runtime design choices. Text has characters and encodings. Binary data has bytes. CPython implements these concepts with different object layouts, APIs, and invariants. 14.1 Text vs Binary Data A string is text:...

22. Compiler Passes

22. Compiler Passes Compiler passes turn the AST and symbol table information into an executable code object. Earlier stages answer structural questions. tokenizer: What lexical units are in the source? parser: What syntax tree do these tokens form? symbol table: What scope does each name belong to? The compiler answers execution questions. Which bytecode instructions should be emitted? Which constants belong in co_consts? Which names belong in co_names? Which local...

13. Built-in Object Implementations

13. Built-in Object Implementations Built-in objects are the concrete data structures behind Python’s core types. They are ordinary Python objects in the sense that they have identities, types, reference counts, attributes where supported, and behavior defined by type slots. They are special because their storage and operations are implemented directly in C. This chapter gives a broad map. Later chapters go deeper into strings, lists, tuples, dictionaries, sets, numbers, functions,...

27. Evaluation Loop

27. Evaluation Loop The evaluation loop is the central execution engine of CPython. It takes a compiled code object, executes its bytecode instructions, and produces a result or an exception. At a high level, CPython execution looks like this: Python source ↓ tokens ↓ parser ↓ AST ↓ symbol table ↓ compiler ↓ code object ↓ frame ↓ evaluation loop ↓ Python result or exception This chapter focuses on the...

26. Bytecode Optimization

26. Bytecode Optimization Bytecode optimization is the final cleanup and refinement stage before a code object is ready for execution. Earlier compiler stages decide what the program means and emit instructions. Optimization tries to make those instructions smaller, simpler, or faster while preserving Python semantics. For example: x = 1 + 2 can compile as if written: x = 3 because both operands are constants and integer addition has no...

CPython Internals

2. Objects and Memory

Chapter Title 7 The Python Object Model 8 PyObject and PyVarObject 9 Reference Counting 10 The Garbage Collector 11 Memory Allocators 12 Object Layout and Type Slots 13 Built-in Object Implementations 14 Strings, Bytes, and Unicode 15 Lists, Tuples, and Arrays 16 Dictionaries and Sets 17 Integers, Floats, and Complex Numbers

88. Documentation Workflow

88. Documentation Workflow CPython documentation is part of the implementation. It describes the language, the standard library, the C API, command-line behavior, build configuration, and development process. A CPython change is incomplete when the behavior changes but the documentation still describes the old behavior. The documentation is maintained in the CPython repository, reviewed with code changes, built locally by contributors, and published for Python users and extension authors. 88.1 Where...

75. Function Call Fast Paths

75. Function Call Fast Paths Function calls are one of the most important performance paths in CPython. Python programs call functions constantly: len(xs) str(x) range(n) obj.method() f(a, b) callback(event) decorator(fn) A call looks simple at the source level, but CPython must support many callable forms: Python functions bound methods builtin functions builtin methods C extension callables classes objects with __call__ classmethod objects staticmethod objects partial objects decorated wrappers A generic...

91. Release Process

91. Release Process The CPython release process turns the development branch into a stable Python version. It covers feature planning, branch management, release candidates, build artifacts, documentation publication, security updates, maintenance releases, and end-of-life policy. A release is not just a Git tag. It is a coordinated handoff from development to users, distributors, package maintainers, platform vendors, and downstream projects. 91.1 Why the Release Process Matters CPython is the reference...

64. Defining New Types

64. Defining New Types A CPython extension module can expose new Python types implemented in C. These types behave like normal Python classes from user code, but their memory layout, allocation, methods, attribute access, numeric operations, sequence operations, and deallocation logic are controlled by C structures and function pointers. A built-in type such as list , dict , int , or str is implemented this way. Extension modules can use...

39. Closures and Cells

39. Closures and Cells Closures let a nested function use variables from an enclosing function after that enclosing function has returned. def make_adder(n): def add(x): return x + n return add add10 = make_adder(10) print(add10(5)) Output: 15 The variable n belongs to make_adder , but add still uses it later. CPython supports this by moving captured variables into cell objects. The inner function keeps references to those cells. 39.1 Nested...

18. Tokenization

18. Tokenization Tokenization is the first structural stage in CPython’s compilation pipeline. It receives Python source text and produces a stream of tokens. The parser consumes that token stream and builds syntax structure from it. At this stage, CPython does not yet know whether a program is meaningful. It only recognizes lexical units: names, numbers, strings, operators, newlines, indentation, and end-of-file markers. The tokenizer turns this: def add(a, b): return...