line_profiler._line_profiler module

This is the Cython backend used in line_profiler.line_profiler.

class line_profiler._line_profiler.LineProfiler

Bases: object

Time the execution of lines of Python code.

This is the Cython base class for line_profiler.line_profiler.LineProfiler.

Parameters:

• *functions (function) – Function objects to be profiled.

• wrap_trace (bool | None) – What to do for existing sys trace callbacks when an instance is enable()-ed:

  True:

  Wrap around said callbacks: when our profiling trace callbacks run, they call the corresponding existing callbacks (where applicable).

  False:

  Suspend said callbacks as long as LineProfiler instances are enabled.

  None (default):

  For the first instance created, resolves to

  True

  If the environment variable LINE_PROFILER_WRAP_TRACE is set to any of {'1', 'on', 'true', 'yes'} (case-insensitive).

  False

  Otherwise.

  If other instances already exist, the value is inherited therefrom.

  In any case, when all instances are disable()-ed, the sys trace system is restored to the state from when the first instance was enable()-ed. See the caveats and also the extra explanation.

• set_frame_local_trace (bool | None) – When using the “legacy” trace system), what to do when entering a function or code block (i.e. an event of type PyTrace_CALL or 'call' is encountered) when an instance is enable()-ed:

  True:

  Set the frame’s f_trace to an object associated with the profiler.

  False:

  Don’t do so.

  None (default):

  For the first instance created, resolves to

  True

  If the environment variable LINE_PROFILER_SET_FRAME_LOCAL_TRACE is set to any of {'1', 'on', 'true', 'yes'} (case-insensitive).

  False

  Otherwise.

  If other instances already exist, the value is inherited therefrom.

  See the caveats and also the extra explanation.

Example

>>> import copy
>>> import line_profiler
>>> # Create a LineProfiler instance
>>> self = line_profiler.LineProfiler()
>>> # Wrap a function
>>> copy_fn = self(copy.copy)
>>> # Call the function
>>> copy_fn(self)
>>> # Inspect internal properties
>>> self.functions
>>> self.c_last_time
>>> self.c_code_map
>>> self.code_map
>>> self.last_time
>>> # Print stats
>>> self.print_stats()

Warning

• Setting wrap_trace and/or set_frame_local_trace helps with using LineProfiler cooperatively with other tools, like coverage and debugging tools, especially when using the “legacy” trace system. However, these parameters should be considered experimental and to be used at one’s own risk – because tools generally assume that they have sole control over system-wide tracing (if using “legacy” tracing), or at least over the sys.monitoring tool ID it acquired.

• When setting wrap_trace and set_frame_local_trace, they are set process-wide for all instances.

Note

There are two “cores”/”backends” for LineProfiler between which users can choose:

'new', 'sys.monitoring', or 'sysmon'

Use sys.monitoring events and callbacks. Only available on (and is the default for) Python 3.12 and newer.

'old', 'legacy', or 'ctrace'

Use the “legacy” trace system (sys.gettrace(), sys.settrace(), and PyEval_SetTrace()). Default for Python < 3.12.

Where both cores are available, the user can choose between the two by supplying a suitable value to the environment variable LINE_PROFILER_CORE.

Note

More on wrap_trace:

• In general, Python allows for trace callbacks to unset themselves, either intentionally (via sys.settrace(None) or sys.monitoring.register_callback(..., None)) or if they error out. If the wrapped/cached trace callbacks do so, profiling would continue, but:

  • The cached callbacks are cleared and are no longer called, and

  • The trace callbacks are unset when all profiler instances are disable()-ed.

• If a wrapped/cached frame-local “legacy” trace callable (f_trace) sets f_trace_lines to false in a frame to disable local line events, f_trace_lines is restored (so that profiling can continue), but said callable will no longer receive said events.

• Likewise, wrapped/cached sys.monitoring callbacks can also disable events:

  • At specific code locations by returning sys.monitoring.DISABLE;

  • By calling sys.monitoring.set_events() and changing the global event set; or

  • By calling sys.monitoring.register_callback() and replacing itself with alternative callbacks (or None).

  When that happens, said disabling acts are again suitably intercepted so that line profiling continues, but:

  • Said callbacks will no longer receive the corresponding events, and

  • The sys.monitoring callbacks and event set are updated correspondingly when all profiler instances are disable()-ed.

  Note that:

  • As with when line profiling is not used, if sys.monitoring.restart_events() is called, the list of code locations where events are suppressed is cleared, and the wrapped/cached callbacks will once again receive events from the previously-DISABLE-d locations.

  • Callbacks which only listen to and alter code-object-local events (via sys.monitoring.set_local_events()) do not interfere with line profiling, and such changes are therefore not intercepted.

Note

More on set_frame_local_trace:

• Since frame-local trace functions is no longer a useful concept in the new sys.monitoring-based system (see also the Note on “cores”), the parameter/attribute always resolves to False when using the new LineProfiler core.

• With the “legacy” trace system, when LineProfiler instances are enable()-ed, sys.gettrace() returns an object which manages profiling on the thread between all active profiler instances. Said object has the same call signature as callables that sys.settrace() takes, so that pure-Python code which temporarily overrides the trace callable (e.g. doctest.DocTestRunner.run()) can function with profiling. After the object is restored with sys.settrace() by said code:

  • If set_frame_local_trace is true, line profiling resumes immediately, because the object has already been set to the frame’s f_trace.

  • However, if set_frame_local_trace is false, line profiling only resumes upon entering another code block (e.g. by calling a callable), because trace callables set via sys.settrace() is only called for 'call' events (see the C implementation of sys).

add_function(func)

Record line profiling information for the given Python function.

Note

This is a low-level method and is intended for types.FunctionType; users should in general use line_profiler.LineProfiler.add_callable() for adding general callables and callable wrappers (e.g. property).

c_code_map

A Python view of the internal C lookup table.

c_last_time

Raises: KeyError

If no profiling data is available on the current thread.

code_hash_map

code_map

line_profiler 4.0 no longer directly maintains code_map, but this will construct something similar for backwards compatibility.

disable()

disable_by_count()

Disable the profiler if the number of disable requests matches (or exceeds) the number of enable requests.

dupes_map

enable()

enable_by_count()

Enable the profiler if it hasn’t been enabled before.

enable_count

functions

get_stats()

Returns:

LineStats object containing the timings.

last_time

line_profiler 4.0 no longer directly maintains last_time, but this will construct something similar for backwards compatibility.

set_frame_local_trace

threaddata

timer_unit

tool_id = 2

wrap_trace

class line_profiler._line_profiler.LineStats(timings, unit)

Bases: object

Object to encapsulate line-profile statistics.

Variables:

• timings (dict[tuple[str, int, str], list[tuple[int, int, int]]]) – Mapping from (filename, first_lineno, function_name) of the profiled function to a list of (lineno, nhits, total_time) tuples for each profiled line. total_time is an integer in the native units of the timer.

• unit (float) – The number of seconds per timer unit.

class line_profiler._line_profiler._LineProfilerManager

Bases: object

Helper object for managing the thread-local state. Supports being called with the same signature as a legacy trace function (see sys.settrace()).

Other methods of interest:

handle_line_event()

Callback for sys.monitoring.events.LINE events

handle_return_event()

Callback for sys.monitoring.events.PY_RETURN events

handle_yield_event()

Callback for sys.monitoring.events.PY_YIELD events

handle_raise_event()

Callback for sys.monitoring.events.RAISE events

handle_reraise_event()

Callback for sys.monitoring.events.RERAISE events

Note

Documentations are for reference only, and all APIs are to be considered private and subject to change.

Parameters:

• tool_id (int) – Tool ID for use with sys.monitoring.

• wrap_trace (bool) – Whether to wrap around legacy and sys.monitoring trace functions and call them.

• set_frame_local_trace (bool) – If using the legacy trace system, whether to insert the instance as a frame’s f_trace upon entering a function scope.

See also

LineProfiler

__call__()

Calls legacy_trace_callback(). If sys.gettrace() returns this instance, replaces the default C-level trace function trace_trampoline() with legacy_trace_callback() to reduce overhead.

Returns:

This instance.

Return type:

self (_LineProfilerManager)

active_instances

handle_line_event(code, lineno)

Line-event (sys.monitoring.events.LINE) callback passed to sys.monitoring.register_callback().

handle_raise_event(code, instruction_offset, exception)

Raise-event (sys.monitoring.events.RAISE) callback passed to sys.monitoring.register_callback().

handle_reraise_event(code, instruction_offset, exception)

Re-raise-event (sys.monitoring.events.RERAISE) callback passed to sys.monitoring.register_callback().

handle_return_event(code, instruction_offset, retval)

Return-event (sys.monitoring.events.PY_RETURN) callback passed to sys.monitoring.register_callback().

handle_yield_event(code, instruction_offset, retval)

Yield-event (sys.monitoring.events.PY_YIELD) callback passed to sys.monitoring.register_callback().

set_frame_local_trace

wrap_local_f_trace(trace_func: Callable) → Callable

Parameters:

trace_func (Callable[[frame, str, Any], Any]) – Frame-local trace function, presumably set by another global trace function.

Returns:

wrapper (Callable[[frame, str, Any], Any])

Thin wrapper around trace_func() which calls it, calls the instance, then returns the return value of trace_func(). This helps prevent other frame-local trace functions from displacing the instance when its set_frame_local_trace is true.

Note

• The .__line_profiler_manager__ attribute of the returned wrapper is set to the instance.

• Line events are not passed to the wrapped callable if wrapper.disable_line_events is set to true.

wrap_trace

line_profiler._line_profiler.disable_line_events(trace_func: Callable) → Callable

Returns:

trace_func (Callable)

If it is a wrapper created by _LineProfilerManager.wrap_local_f_trace; trace_func.disable_line_events is also set to true

wrapper (Callable)

Otherwise, a thin wrapper around trace_func() which withholds line events.

Note

This is for when a frame-local f_trace disables f_trace_lines – we would like to keep line events enabled (so that line profiling works) while “unsubscribing” the trace function from it.

line_profiler._line_profiler.find_cython_source_file(cython_func)

Resolve the absolute path to a Cython function’s source file.

Returns:

result (str | None)

Cython source file if found, else None.

line_profiler._line_profiler.label(code)

Return a (filename, first_lineno, _name) tuple for a given code object.

This is the similar labelling as used by the cProfile module in Python 2.5.

Note

In Python >= 3.11 we return qualname for _name. In older versions of Python we just return name.