Developer Tools and Debugging

This section documents the suite of tools and APIs provided by CPython for developers to inspect, debug, and optimize Python code. The infrastructure spans from high-level interactive environments to low-level runtime instrumentation and remote process attachment.

CPython's developer tooling is divided into three primary categories:

1. Debugger and Tracing: Tools for controlled execution, breakpoint management, and remote process attachment.
2. Profiling and Performance Analysis: Utilities for measuring execution time, identifying bottlenecks, and sampling runtime state.
3. Interactive REPL and Code Introspection: The user-facing interactive interpreter and the underlying APIs for code and object inspection.

High-Level Tooling Architecture

The following diagram illustrates the relationship between the developer-facing tools and the internal CPython runtime components they interact with.

Developer Tools to Runtime Mapping

Sources: Lib/pdb.py72-73 Lib/profiling/sampling/sample.py78-88 Lib/_pyrepl/simple_interact.py101-111 Lib/_pyrepl/readline.py35

Debugger and Tracing

The primary debugging tool is pdb, which provides an interactive source code debugger Lib/pdb.py1-4 It is built upon the bdb base debugger class Lib/bdb.py73 which manages breakpoints and execution flow.

Key capabilities include:

• Breakpoint Management: Setting conditional and temporary breakpoints via the bdb.Bdb interface.
• Execution Control: Stepping through code (step, next), jumping to specific lines (jump), and returning from functions (return) Lib/test/test_pdb.py106-128
• Remote Debugging: Python 3.14 introduces a safe external debugger interface (:pep:768) Doc/whatsnew/3.14.rst106-107 Support for attaching to running processes via PIDs is implemented using _remote_debugging and socket-based communication via _PdbServer and _PdbClient Lib/pdb.py84-85 Lib/test/test_remote_pdb.py20
• Instrumentation: Utilizing sys.monitoring for execution tracking. The debugger can find executable lines by identifying instructions following a RESUME opcode Lib/pdb.py119-134

For details, see Debugger and Tracing.

Sources: Lib/pdb.py1-4 Lib/pdb.py73 Lib/test/test_pdb.py106-128 Doc/whatsnew/3.14.rst106-107 Lib/test/test_remote_pdb.py20 Lib/pdb.py119-134

Profiling and Performance Analysis

CPython provides multiple strategies for performance analysis, ranging from deterministic tracing to statistical sampling.

• Deterministic Profiling: cProfile tracks every function call and return.
• Sampling Profiler (Tachyon): The profiling.sampling package provides a non-intrusive way to analyze performance by periodically capturing the stack of the target process using a RemoteUnwinder Lib/profiling/sampling/sample.py78-88 It supports various modes including WALL, CPU, GIL, and EXCEPTION Lib/profiling/sampling/sample.py27-33
• Collectors: Data can be aggregated into various formats including pstats, flamegraph, gecko (for Firefox Profiler), and binary Lib/profiling/sampling/cli.py98-118 The BinaryCollector handles the binary profiling format Lib/profiling/sampling/cli.py117
• External Inspection: The _remote_debugging module provides the RemoteUnwinder to read memory and unwind stacks from a separate process, even resolving child PIDs for Windows venv launchers Lib/profiling/sampling/sample.py50-75

Sampling Profiler Workflow

Sources: Lib/profiling/sampling/sample.py78-88 Lib/profiling/sampling/sample.py27-33 Lib/profiling/sampling/cli.py98-118 Lib/profiling/sampling/sample.py50-75 Lib/profiling/sampling/sample.py151-176

For details, see Profiling and Performance Analysis.

Interactive REPL and Code Introspection

The interactive experience in Python 3.14 is enhanced with syntax highlighting and improved multiline support Doc/whatsnew/3.14.rst119-121

• _pyrepl: A pure-Python implementation of the interactive interpreter that supports multiline editing and syntax highlighting via _colorize Lib/_pyrepl/simple_interact.py21-24 Lib/_pyrepl/utils.py118-123
• Input Handling: The REPL manages multiline input via multiline_input and handles platform-specific console logic through UnixConsole or WindowsConsole Lib/_pyrepl/simple_interact.py35-42 Lib/_pyrepl/windows_console.py154-162
• Introspection: The inspect module provides APIs to examine live objects. In 3.14, annotationlib is introduced to handle deferred evaluation of annotations Doc/whatsnew/3.14.rst162-168
• Completion: The ModuleCompleter and FancyCompleter provide context-aware tab completion for imports and object attributes Lib/test/test_pyrepl/test_pyrepl.py43-48
• MIME Detection: The mimetypes module provides utilities for guessing file types and extensions based on URLs or paths Lib/mimetypes.py1-8

For details, see Interactive REPL and Code Introspection.

Sources: Doc/whatsnew/3.14.rst119-121 Lib/_pyrepl/simple_interact.py21-24 Lib/_pyrepl/utils.py118-123 Lib/_pyrepl/simple_interact.py35-42 Lib/_pyrepl/windows_console.py154-162 Doc/whatsnew/3.14.rst162-168 Lib/mimetypes.py1-8