Decorators

Decorators for profiling functions and classes.

Provides profile() and profile_class() for QgsRuntimeProfiler-based timing, and cprofile() and cprofile_plugin() for cProfile-based profiling with optional file output.

qgis_profiler.decorators.profile(function=None, *, name=None, group=None, event_args=None)[source]

Create a profiling decorator for the given function.

Measure the time taken by a function and group the profiler data under a specified name using QgsApplication’s profiling infrastructure.

Parameters:

function (Callable | None) – Provided here to support both @profile and @profile() syntax.
name (str | None) – Optional name for the profiler item. If not provided, the function’s name will be used as the name.
group (str | None) – Optional name for the profiler group. If not provided, the group name is read from settings.
event_args (list[str] | None) – Optional list of argument names to include in the event name. If specified, the event name will include these argument values.

Returns:

A decorator that wraps the specified function for profiling.

Return type:

Callable

Example:

from qgis_profiler.decorators import profile

@profile
def process_features():
    pass

# With custom name and group
@profile(name="Feature Processing", group="My Plugin")
def another_function():
    pass

# With argument values in event name
@profile(event_args=["layer_name"])
def process_layer(layer_name: str):
    pass
# Event name will be: "process_layer(layer_name=roads)"

qgis_profiler.decorators.profile_class(*, group=None, include=None, exclude=None)[source]

Wrap public methods of a class with the ‘profile’ decorator.

Skip methods already decorated with ‘profile’ and all __dunder__ methods.

Parameters:

group (str | None) – Optional name for the profiler group. If not provided, the group name is read from settings.
include (list[str] | None) – List of method names to include (only these will be wrapped if provided).
exclude (list[str] | None) – List of method names to exclude (these will NOT be wrapped, overrides include).

Returns:

A class with decorated methods based on the include/exclude criteria.

Return type:

Callable[[type], type]

Example:

from qgis_profiler.decorators import profile_class

@profile_class(group="My Plugin", exclude=["helper"])
class LayerProcessor:
    def load(self):
        pass  # profiled

    def process(self):
        pass  # profiled

    def helper(self):
        pass  # NOT profiled (excluded)

qgis_profiler.decorators.cprofile(function=None, *, log_stats=True, trim_zeros=True, sort=('cumtime',), output_file_path=None)[source]

Profile the execution of a function using cProfile.

Can be used as a decorator with or without arguments.

Parameters:

function (Callable | None) – Function to be profiled. Defaults to None.
log_stats (bool) – Whether to log profiling statistics. Defaults to True.
trim_zeros (bool) – Trim lines with zero times from the report.
sort (tuple[str, ...]) – Tuple of columns used for sorting profiling output.
output_file_path (Path | None) – File path to save profiling output, if provided.

Returns:

Callable decorator or wrapped function.

Return type:

Callable

Example:

from pathlib import Path
from qgis_profiler.decorators import cprofile

@cprofile(output_file_path=Path("/tmp/report.prof"))
def expensive_operation():
    pass

qgis_profiler.decorators.cprofile_plugin(*, output_file_path)[source]

Apply a decorator to a QGIS plugin class to enable profiling.

This function decorates a class to integrate profiling functionality via cProfile. Profiling is enabled during the plugin’s execution and additional profiling statistics are logged after the plugin unloads.

The output file can then be further analysed for example with tools like

https://github.com/jrfonseca/gprof2dot and https://jiffyclub.github.io/snakeviz/#snakeviz

Parameters:: output_file_path (Path) – Path to save profiling results. If the file exists, a suffix will be added to the filename.
Returns:: Decorated class.
Return type:: Callable[[type], type]

Example:

from pathlib import Path
from qgis_profiler.decorators import cprofile_plugin

@cprofile_plugin(output_file_path=Path("/tmp/my_plugin.prof"))
class MyPlugin:
    def __init__(self, iface):
        self.iface = iface

    def initGui(self):
        pass

    def unload(self):
        # cProfile results are saved here automatically
        pass

The output .prof file can be analyzed with snakeviz:

pip install snakeviz
snakeviz /tmp/my_plugin.prof