line_profiler package¶

Submodules¶

Module contents¶

Line Profiler¶

The line_profiler module for doing line-by-line profiling of functions

Github	https://github.com/pyutils/line_profiler
Pypi	https://pypi.org/project/line_profiler
ReadTheDocs	https://kernprof.readthedocs.io/en/latest/

Installation¶

Releases of line_profiler and kernprof can be installed using pip

pip install line_profiler

The package also provides extras for optional dependencies, which can be installed via:

pip install line_profiler[all]

Line Profiler Basic Usage¶

To demonstrate line profiling, we first need to generate a Python script to profile. Write the following code to a file called demo_primes.py.

from line_profiler import profile


@profile
def is_prime(n):
    '''
    Check if the number "n" is prime, with n > 1.

    Returns a boolean, True if n is prime.
    '''
    max_val = n ** 0.5
    stop = int(max_val + 1)
    for i in range(2, stop):
        if n % i == 0:
            return False
    return True


@profile
def find_primes(size):
    primes = []
    for n in range(size):
        flag = is_prime(n)
        if flag:
            primes.append(n)
    return primes


@profile
def main():
    print('start calculating')
    primes = find_primes(100000)
    print(f'done calculating. Found {len(primes)} primes.')


if __name__ == '__main__':
    main()

In this script we explicitly import the profile function from line_profiler, and then we decorate function of interest with @profile.

By default nothing is profiled when running the script.

python demo_primes.py

The output will be

start calculating
done calculating. Found 9594 primes.

The quickest way to enable profiling is to set the environment variable LINE_PROFILE=1 and running your script as normal.

LINE_PROFILE=1 python demo_primes.py

This will output 3 files: profile_output.txt, profile_output_<timestamp>.txt, and profile_output.lprof and stdout will look something like:

start calculating
done calculating. Found 9594 primes.
Timer unit: 1e-09 s

  0.65 seconds - demo_primes.py:4 - is_prime
  1.47 seconds - demo_primes.py:19 - find_primes
  1.51 seconds - demo_primes.py:29 - main
Wrote profile results to profile_output.txt
Wrote profile results to profile_output_2023-08-12T193302.txt
Wrote profile results to profile_output.lprof
To view details run:
python -m line_profiler -rtmz profile_output.lprof

For more control over the outputs, run your script using kernprof. The following invocation will run your script, dump results to demo_primes.py.lprof, and display results.

python -m kernprof -lvr demo_primes.py

Note: the -r flag will use “rich-output” if you have the rich module installed.

See also

autoprofiling usage in: line_profiler.autoprofile

class line_profiler.LineProfiler[source]¶

Bases: LineProfiler

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()

wrap_classmethod(func)[source]¶: Wrap a classmethod to profile it.

wrap_coroutine(func)[source]¶: Wrap a Python 3.5 coroutine to profile it.

wrap_generator(func)[source]¶: Wrap a generator to profile it.

wrap_function(func)[source]¶: Wrap a function to profile it.

dump_stats(filename)[source]¶: Dump a representation of the data to a file as a pickled LineStats object from get_stats().

print_stats(stream=None, output_unit=None, stripzeros=False, details=True, summarize=False, sort=False, rich=False)[source]¶: Show the gathered statistics.

run(cmd)[source]¶: Profile a single executable statment in the main namespace.

runctx(cmd, globals, locals)[source]¶: Profile a single executable statement in the given namespaces.

runcall(func, *args, **kw)[source]¶: Profile a single function call.

add_module(mod)[source]¶: Add all the functions in a module and its classes.

line_profiler.load_ipython_extension(ip)[source]¶: API for IPython to recognize this module as an IPython extension.

line_profiler.load_stats(filename)[source]¶: Utility function to load a pickled LineStats object from a given filename.

line_profiler.main()[source]¶: The line profiler CLI to view output from kernprof -l.

line_profiler.show_func(filename, start_lineno, func_name, timings, unit, output_unit=None, stream=None, stripzeros=False, rich=False)[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.