kernprof module

Script to conveniently run profilers on code in a variety of circumstances.

To profile a script, decorate the functions of interest with @profile

echo "if 1:
    @profile
    def main():
        1 + 1
    main()
" > script_to_profile.py

Note

New in 4.1.0: Instead of relying on injecting profile into the builtins you can now import line_profiler and use line_profiler.profile to decorate your functions. This allows the script to remain functional even if it is not actively profiled. See line_profiler for details.

Then run the script using kernprof:

kernprof -b script_to_profile.py

By default this runs with the default cProfile profiler and does not require compiled modules. Instructions to view the results will be given in the output. Alternatively, adding -v to the command line will write results to stdout.

To enable line-by-line profiling, then line_profiler must be available and compiled. Add the -l argument to the kernprof invocation.

kernprof -lb script_to_profile.py

For more details and options, refer to the CLI help. To view kernprof help run:

kenprof --help

which displays:

usage: kernprof [-h] [-V] [-l] [-b] [-o OUTFILE] [-s SETUP] [-v] [-r] [-u UNIT] [-z] [-i [OUTPUT_INTERVAL]] [-p PROF_MOD] [--prof-imports] script ...

Run and profile a python script.

positional arguments:
  script                The python script file to run
  args                  Optional script arguments

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -l, --line-by-line    Use the line-by-line profiler instead of cProfile. Implies --builtin.
  -b, --builtin         Put 'profile' in the builtins. Use 'profile.enable()'/'.disable()', '@profile' to decorate functions, or 'with profile:' to profile a section of code.
  -o OUTFILE, --outfile OUTFILE
                        Save stats to <outfile> (default: 'scriptname.lprof' with --line-by-line, 'scriptname.prof' without)
  -s SETUP, --setup SETUP
                        Code to execute before the code to profile
  -v, --view            View the results of the profile in addition to saving it
  -r, --rich            Use rich formatting if viewing output
  -u UNIT, --unit UNIT  Output unit (in seconds) in which the timing info is displayed (default: 1e-6)
  -z, --skip-zero       Hide functions which have not been called
  -i [OUTPUT_INTERVAL], --output-interval [OUTPUT_INTERVAL]
                        Enables outputting of cumulative profiling results to file every n seconds. Uses the threading module. Minimum value is 1 (second). Defaults to disabled.
  -p PROF_MOD, --prof-mod PROF_MOD
                        List of modules, functions and/or classes to profile specified by their name or path. List is comma separated, adding the current script path profiles
                        full script. Only works with line_profiler -l, --line-by-line
  --prof-imports        If specified, modules specified to `--prof-mod` will also autoprofile modules that they import. Only works with line_profiler -l, --line-by-line

kernprof.execfile(filename, globals=None, locals=None)

Python 3.x doesn’t have ‘execfile’ builtin

kernprof.is_generator(f)

Return True if a function is a generator.

class kernprof.ContextualProfile(*args, **kwds)

Bases: Profile

A subclass of Profile that adds a context manager for Python 2.5 with: statements and a decorator.

enable_by_count(subcalls=True, builtins=True)

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

disable_by_count()

Disable the profiler if the number of disable requests matches the number of enable requests.

wrap_generator(func)

Wrap a generator to profile it.

wrap_function(func)

Wrap a function to profile it.

class kernprof.RepeatedTimer(interval, dump_func, outfile)

Bases: object

Background timer for outputting file every n seconds.

Adapted from [SO474528].

References

[SO474528]

https://stackoverflow.com/questions/474528/execute-function-every-x-seconds/40965385#40965385

_run()

start()

stop()

kernprof.find_script(script_name)

Find the script.

If the input is not a file, then $PATH will be searched.

kernprof._python_command()

Return a command that corresponds to sys.executable.

kernprof.main(args=None)

Runs the command line interface