Skip to content

CLI reference

profit run

Profile a Python script or module.

profit run <script> [options] [-- <script-args>]
profit run -m <module> [options]

Options

-p TARGET, --profile TARGET
Callable to show in the output table. Can be repeated to show multiple functions side by side. When omitted, all functions are shown ranked by cumulative time.
-b TARGET, --baseline TARGET
Baseline callable. Each -p target is shown with a Delta column giving its mean time difference and ratio relative to this baseline.
-m MODULE
Run a module as a script, equivalent to python -m MODULE.
--sort {cumulative,tottime,calls}
Column to sort by. Default: cumulative.
--limit N
Maximum number of rows to show. Default: 20.

Target format

Targets passed to -p and -b are importable names:

Format Example Resolves to
module:name mymod:my_func mymod.my_func
module:Class.method mymod:MyClass.run MyClass.run in mymod
pkg.module:name mymod.utils:helper helper in mymod.utils
bare name my_func matched by function name at runtime

Bare names for scripts

When profiling a script (not an installed module), a bare name like -p my_func is the easiest option. It matches by function name after the script runs, without needing the function to be importable beforehand.

Examples

Full profile of a script:

profit run script.py

Focus on a single function:

profit run script.py -p my_func

Compare two implementations:

profit run script.py -b old_impl -p new_impl

Profile a module:

profit run -m mypackage.cli

Pass arguments through to the script:

profit run script.py -- --input data.csv --verbose

profit timeit

Profile a Python statement run in a loop, similar to the standard library timeit module.

profit timeit '<stmt>' [options]

Options

STMT
The statement to execute repeatedly. Passed to exec(), so multi-line statements and imports work.
--setup STMT
A setup statement run once before the timed loop. Use it to import modules or build data structures. Default: pass.
-n N
Number of iterations. When 0 (the default), the count is chosen automatically so the total run takes around 0.2 s.
-p TARGET, --profile TARGET
Callable to show in the output. Same format as profit run. Can be repeated.
-b TARGET, --baseline TARGET
Baseline callable for delta comparison.
--sort {cumulative,tottime,calls}
Column to sort by. Default: cumulative.
--limit N
Maximum number of rows to show. Default: 20.

Examples

Time a built-in operation:

profit timeit 'sorted(data)' --setup 'data = list(range(1000, 0, -1))'

Time a function from an installed module:

profit timeit 'f()' --setup 'from mymod import f'

Fix the iteration count:

profit timeit 'sum(range(10_000))' -n 5000

Compare two functions:

profit timeit 'g()' \
  --setup 'from mymod import f, g' \
  -b f -p g