line_profiler.line_profiler module

This module defines the core LineProfiler class as well as methods to inspect its output. This depends on the line_profiler._line_profiler Cython backend.

line_profiler.line_profiler.get_column_widths(config: bool | str | None = False) → Mapping[Literal['line', 'hits', 'time', 'perhit', 'percent'], int][source]
Arguments
config (bool | str | None)

Passed to ConfigSource.from_config().

Note

  • Results are cached.

  • The default value (False) loads the config from the default TOML file that the package ships with.

line_profiler.line_profiler.load_ipython_extension(ip: object) → None[source]

API for IPython to recognize this module as an IPython extension.

line_profiler.line_profiler.get_code_block(filename: PathLike[str] | str, lineno: int) → list[str][source]

Get the lines in the code block in a file starting from required line number; understands Cython code.

Parameters:

  • filename (Union[os.PathLike, str]) – Path to the source file.

  • lineno (int) – 1-indexed line number of the first line in the block.

Returns:

lines (list[str])

Newline-terminated string lines.

Note

This function makes use of inspect.getblock(), which is public but undocumented API. That said, it has been in use in this repo since 2008 (fb60664), so we will continue using it until we can’t.

Example

>>> from os.path import join
>>> from tempfile import TemporaryDirectory
>>> from textwrap import dedent
>>>
>>>
>>> def get_last_line(*args, **kwargs):
...     lines = get_code_block(*args, **kwargs)
...     return lines[-1].rstrip('\n')
...
>>>
>>> with TemporaryDirectory() as tmpdir:
...     fname = join(tmpdir, 'cython_source.pyx')
...     with open(fname, mode='w') as fobj:
...         print(dedent('''
...     class NormalClass:                   # 1
...         def __init__(self):              # 2
...             pass                         # 3
...
...         def normal_method(self, *args):  # 5
...             pass                         # 6
...
...     cdef class CythonClass:              # 8
...         cpdef cython_method(self):       # 9
...             pass                         # 10
...
...         property legacy_cython_prop:     # 12
...             def __get__(self):           # 13
...                 return None              # 14
...             def __set__(self, value):    # 15
...                 pass                     # 16
...
...     def normal_func(x, y, z):            # 18
...         with some_ctx():                 # 19
...             ...                          # 20
...
...     cdef cython_function(                # 22
...             int x, int y, int z):        # 23
...         ...                              # 24
...                      ''').strip('\n'),
...               file=fobj)
...     # Vanilla Python code blocks:
...     # - `NormalClass`
...     assert get_last_line(fname, 1).endswith('# 6')
...     # - `NormalClass.__init__()`
...     assert get_last_line(fname, 2).endswith('# 3')
...     # - `normal_func()`
...     assert get_last_line(fname, 18).endswith('# 20')
...     # Cython code blocks:
...     # - `CythonClass`
...     assert get_last_line(fname, 8).endswith('# 16')
...     # - `CythonClass.cython_method()`
...     assert get_last_line(fname, 9).endswith('# 10')
...     # - `CythonClass.legacy_cython_prop`
...     assert get_last_line(fname, 12).endswith('# 16')
...     # - `cython_function()`
...     assert get_last_line(fname, 22).endswith('# 24')
class line_profiler.line_profiler.LineStats(timings: _TimingsMap, unit: float)[source]

Bases: LineStats

timings: _TimingsMap
unit: float
print(stream: TextIOBase | None = None, output_unit: float | None = None, stripzeros: bool = False, details: bool = True, summarize: bool = False, sort: bool = False, rich: bool = False, *, config: str | PathLike[str] | bool | None = None) → None[source]
to_file(filename: PathLike[str] | str) → None[source]

Pickle the instance to the given filename.

classmethod from_files(file: PathLike[str] | str, /, *files: PathLike[str] | str) → Self[source]

Utility function to load an instance from the given filenames.

classmethod from_stats_objects(stats: _StatsLike, /, *more_stats: _StatsLike) → Self[source]

Example

>>> stats1 = LineStats(
...     {('foo', 1, 'spam.py'): [(2, 10, 300)],
...      ('bar', 10, 'spam.py'):
...      [(11, 2, 1000), (12, 1, 500)]},
...     1E-6)
>>> stats2 = LineStats(
...     {('bar', 10, 'spam.py'):
...      [(11, 10, 20000), (12, 5, 1000)],
...      ('baz', 5, 'eggs.py'): [(5, 2, 5000)]},
...     1E-7)
>>> stats_combined = LineStats.from_stats_objects(
...     stats1, stats2)
>>> assert stats_combined.unit == 1E-6
>>> assert stats_combined.timings == {
...     ('foo', 1, 'spam.py'): [(2, 10, 300)],
...     ('bar', 10, 'spam.py'):
...     [(11, 12, 3000), (12, 6, 600)],
...     ('baz', 5, 'eggs.py'): [(5, 2, 500)]}
class line_profiler.line_profiler.LineProfiler[source]

Bases: LineProfiler, ByCountProfilerMixin

A profiler that records the execution times of individual lines.

This provides the core line-profiler functionality.

Example

>>> import line_profiler
>>> profile = line_profiler.LineProfiler()
>>> @profile
... def func():
...     x1 = list(range(10))
...     x2 = list(range(100))
...     x3 = list(range(1000))
>>> func()
>>> profile.print_stats()
__call__(func: Callable) → Callable[source]

Decorate a function, method, property, partial() object etc. to start the profiler on function entry and stop it on function exit.

wrap_callable(func: Callable) → Callable[source]
add_callable(func: object, guard: Callable[[Callable], bool] | None = None, name: str | None = None) → Literal[0, 1][source]

Register a function, method, property, partial() object, etc. with the underlying Cython profiler.

Parameters:

  • func (…) – Function, class/static/bound method, property, etc.

  • guard (Optional[Callable[[Callable], bool]]) – Optional checker callable, which takes a function object and returns true(-y) if it should not be passed to add_function(). Defaults to checking whether the function is already a profiling wrapper.

  • name (Optional[str]) – Optional name for func, to be used in log messages.

Returns:

1 if any function is added to the profiler, 0 otherwise.

Note

This method should in general be called instead of the more low-level add_function().

get_stats() → LineStats[source]
dump_stats(filename: PathLike[str] | str) → None[source]

Dump a representation of the data to a file as a pickled LineStats object from get_stats().

print_stats(stream: TextIOBase | None = None, output_unit: float | None = None, stripzeros: bool = False, details: bool = True, summarize: bool = False, sort: bool = False, rich: bool = False, *, config: str | PathLike[str] | bool | None = None) → None[source]

Show the gathered statistics.

add_class(cls: type, *, scoping_policy: ScopingPolicy | str | ScopingPolicyDict | None = None, wrap: bool = False) → int[source]

Add the members (callables (wrappers), methods, classes, …) in a class’ local namespace and profile them.

Parameters:

  • cls (type) – Class to be profiled.

  • scoping_policy (Union[str, ScopingPolicy, ScopingPolicyDict, None]) – Whether (and how) to match the scope of members and decide on whether to add them:

    str (incl. ScopingPolicy):

    Strings are converted to ScopingPolicy instances in a case-insensitive manner, and the same policy applies to all members.

    {'func': ..., 'class': ..., 'module': ...}

    Mapping specifying individual policies to be enacted for the corresponding member types.

    None

    The default, equivalent to DEFAULT_SCOPING_POLICIES.

    See ScopingPolicy and ScopingPolicy.to_policies() for details.

  • wrap (bool) – Whether to replace the wrapped members with wrappers which automatically enable/disable the profiler when called.

Returns:

Number of members added to the profiler.

Return type:

n (int)

add_module(mod: ModuleType, *, scoping_policy: ScopingPolicy | str | ScopingPolicyDict | None = None, wrap: bool = False) → int[source]

Add the members (callables (wrappers), methods, classes, …) in a module’s local namespace and profile them.

Parameters:

  • mod (ModuleType) – Module to be profiled.

  • scoping_policy (Union[str, ScopingPolicy, ScopingPolicyDict, None]) – Whether (and how) to match the scope of members and decide on whether to add them:

    str (incl. ScopingPolicy):

    Strings are converted to ScopingPolicy instances in a case-insensitive manner, and the same policy applies to all members.

    {'func': ..., 'class': ..., 'module': ...}

    Mapping specifying individual policies to be enacted for the corresponding member types.

    None

    The default, equivalent to DEFAULT_SCOPING_POLICIES.

    See ScopingPolicy and ScopingPolicy.to_policies() for details.

  • wrap (bool) – Whether to replace the wrapped members with wrappers which automatically enable/disable the profiler when called.

Returns:

Number of members added to the profiler.

Return type:

n (int)

line_profiler.line_profiler.is_generated_code(filename: str) → bool[source]

Return True if a filename corresponds to generated code, such as a Jupyter Notebook cell.

line_profiler.line_profiler.show_func(filename: str, start_lineno: int, func_name: str, timings: Sequence[tuple[int, int, int | float]], unit: float, output_unit: float | None = None, stream: TextIOBase | None = None, stripzeros: bool = False, rich: bool = False, *, config: str | PathLike[str] | bool | None = None) → None[source]

Show results for a single function.

Parameters:

  • filename (str) – Path to the profiled file

  • start_lineno (int) – First line number of profiled function

  • func_name (str) – name of profiled function

  • timings (List[Tuple[int, int, float]]) – Measurements for each line (lineno, nhits, time).

  • unit (float) – The number of seconds used as the cython LineProfiler’s unit.

  • output_unit (float | None) – Output unit (in seconds) in which the timing info is displayed.

  • stream (io.TextIOBase | None) – Defaults to sys.stdout

  • stripzeros (bool) – If True, prints nothing if the function was not run

  • rich (bool) – If True, attempt to use rich highlighting.

  • config (Union[str, PurePath, bool, None]) – Optional filename from which to load configurations (e.g. output column widths); default (= True or None) is to look for a config file based on the environment variable ${LINE_PROFILER_RC} and path-based lookup; passing False disables all lookup and falls back to the default configuration

Example

>>> from line_profiler.line_profiler import show_func
>>> import line_profiler
>>> # Use a function in this file as an example
>>> func = line_profiler.line_profiler.show_text
>>> start_lineno = func.__code__.co_firstlineno
>>> filename = func.__code__.co_filename
>>> func_name = func.__name__
>>> # Build fake timeings for each line in the example function
>>> import inspect
>>> num_lines = len(inspect.getsourcelines(func)[0])
>>> line_numbers = list(range(start_lineno + 3,
...                           start_lineno + num_lines))
>>> timings = [(lineno, idx * 1e13, idx * (2e10 ** (idx % 3)))
...            for idx, lineno
...            in enumerate(line_numbers, start=1)]
>>> unit = 1.0
>>> output_unit = 1.0
>>> stream = None
>>> stripzeros = False
>>> rich = 1
>>> show_func(filename, start_lineno, func_name, timings, unit,
...           output_unit, stream, stripzeros, rich)
line_profiler.line_profiler.show_text(stats: _TimingsMap, unit: float, output_unit: float | None = None, stream: io.TextIOBase | None = None, stripzeros: bool = False, details: bool = True, summarize: bool = False, sort: bool = False, rich: bool = False, *, config: str | PathLike[str] | bool | None = None) → None[source]

Show text for the given timings.

line_profiler.line_profiler.load_stats(file: PathLike[str] | str, /, *files: PathLike[str] | str) → Self

Utility function to load an instance from the given filenames.

line_profiler.line_profiler.main() → None[source]

The line profiler CLI to view output from kernprof -l.