Skip to main content

Lib/cProfile.py

cpython 3.14 @ ab2d84fe1023/Lib/cProfile.py

cProfile is the recommended profiler for most Python code. It is a thin Python wrapper around _lsprof, a C extension implementing Robert Kern's lsprof algorithm. Because the heavy lifting happens in C, the per-call overhead is small enough for use on real programs without distorting results badly.

The module exposes a Profile class that mirrors the interface of the older profile module. You call enable() and disable() around the code you want to measure, or use the higher-level runcall and runctx helpers. After profiling, create_stats() populates internal data and dump_stats serialises the result to a file for later analysis by pstats.

Two module-level convenience functions, run and runctx, let you profile a string statement without instantiating Profile directly. Both accept an optional filename argument; when supplied the stats are written to disk rather than printed immediately.

Map​

LinesSymbolRolegopy
1-30module headerImports, __all__, author note
31-60Profile.__init__Wraps _lsprof.Profiler, stores timer
61-80Profile.enable / Profile.disableDelegate to the C profiler
81-110Profile.runcallProfile a callable with arguments
111-135Profile.runctxProfile a string in explicit namespaces
136-160Profile.runProfile a string in caller's globals
161-185Profile.create_stats / print_stats / dump_statsResults post-processing
186-210run / runctxModule-level convenience wrappers

Reading​

Module header and imports (lines 1 to 30)​

cpython 3.14 @ ab2d84fe1023/Lib/cProfile.py#L1-30

The file is deliberately short. It imports _lsprof from the C layer, re-exports a small __all__, and records the original author credit for Robert Kern's lsprof.

import _lsprof
import profile as _pyprofile

__all__ = ["run", "runctx", "Profile"]

Profile.__init__ and timer setup (lines 31 to 60)​

cpython 3.14 @ ab2d84fe1023/Lib/cProfile.py#L31-60

The constructor creates a _lsprof.Profiler instance and optionally installs a custom timer function. When no timer is supplied the C extension uses perf_counter-style wall time. The subcalls and builtins flags are forwarded straight to the C layer.

class Profile(_pyprofile.Profile):
    def __init__(self, timer=None, timeunit=0.0, subcalls=True, builtins=True):
        self.profiler = _lsprof.Profiler(timer, timeunit, subcalls, builtins)

enable and disable (lines 61 to 80)​

cpython 3.14 @ ab2d84fe1023/Lib/cProfile.py#L61-80

These are one-liners that delegate to the C profiler. enable installs the C-level trace hook; disable removes it and leaves the accumulated stats intact.

def enable(self):
    self.profiler.enable()

def disable(self):
    self.profiler.disable()

runcall and runctx (lines 81 to 135)​

cpython 3.14 @ ab2d84fe1023/Lib/cProfile.py#L81-135

runcall wraps any callable: it enables the profiler, calls the function, then disables regardless of exception. runctx compiles and executes a string statement inside caller-supplied globals and locals dicts, which is useful for profiling module-level code without polluting the interactive namespace.

def runcall(self, func, /, *args, **kw):
    self.enable()
    try:
        return func(*args, **kw)
    finally:
        self.disable()

def runctx(self, cmd, globals, locals):
    self.enable()
    try:
        exec(cmd, globals, locals)
    finally:
        self.disable()

Module-level run and runctx (lines 186 to 210)​

cpython 3.14 @ ab2d84fe1023/Lib/cProfile.py#L186-210

These functions are the public entry points most users reach for. They create a temporary Profile, run the statement, then either print the stats or dump them to filename. The sort parameter is forwarded to pstats.Stats.sort_stats.

def run(statement, filename=None, sort=-1):
    prof = Profile()
    result = None
    try:
        prof = prof.run(statement)
    except SystemExit:
        pass
    finally:
        if filename is not None:
            prof.dump_stats(filename)
        else:
            result = prof.print_stats(sort)
    return result

gopy mirror​

Not yet ported.