ProfilerWrapper

Singleton wrapper around QgsRuntimeProfiler with hierarchical result parsing.

Contains ProfilerWrapper, the central access point for all profiling operations, and ProfilerResult, a dataclass representing hierarchical profiling results.

class qgis_profiler.profiler.ProfilerResult(name, group, duration, children=<factory>)[source]

Bases: object

Represents the result of a profiling operation with hierarchical structure.

This class encapsulates information about a single profiling result, including its name, associated group, duration, and any child profiling results. It is designed to represent profiles in a nested format, allowing hierarchical analysis of performance metrics.

Parameters:

  • name (str) – Name of the profiling result.

  • group (str) – Group or category associated with the profiling result.

  • duration (float) – Duration in seconds for the profiling result.

  • children (list[ProfilerResult]) – List of child profiling results nested under this result.

name: str
group: str
duration: float
children: list[ProfilerResult]
static parse_from_text(text, group)[source]

Parse a given text into a list of ProfilerResult objects.

Process the hierarchical structure denoted by indentation and the specified group. Each line is expected to contain profiling data.

Parameters:

  • text (str) – The textual data representing the profiling information. Each line in the text is expected to contain data in a specific format.

  • group (str) – The group under which the profiling results belong. Provides categorization for the parsed results.

Returns:

Returns a list of ProfilerResult objects constructed from the provided text input, including all nested hierarchical levels.

Return type:

list[ProfilerResult]

class qgis_profiler.profiler.ProfilerWrapper[source]

Bases: object

Wrap QgsRuntimeProfiler with additional functionality.

Do not initialize directly, use ProfilerWrapper.get() instead.

Example:

from qgis_profiler.profiler import ProfilerWrapper

profiler = ProfilerWrapper.get()

# Context manager
with profiler.profile("Loading layers", "My Plugin"):
    load_layers()

# Manual start/stop
event_id = profiler.start("Processing", "My Plugin")
do_work()
profiler.end("My Plugin")

# Retrieve results
results = profiler.get_profiler_data(group="My Plugin")
for result in results:
    print(f"{result.name}: {result.duration}s")
static get()[source]

Return the singleton ProfilerWrapper instance.

Return type:

ProfilerWrapper

property groups: set[str]

Set of all groups in the profiler.

qgis_groups()[source]

Return a dictionary of all QGIS groups in the profiler.

Key is the translated/descriptive name, value is the actual name.

Return type:

dict[str, str]

property cprofiler: QCProfiler

QCProfiler instance. Only available if cProfile is installed.

property cprofiler_available: bool

Return whether cProfile is installed and available.

profile(name, group=None)[source]

Profile a block of code.

Parameters:

  • name (str)

  • group (str | None)

Return type:

Generator[str, None, None]

create_group(group_name)[source]

Create an empty group in the profiler.

Parameters:

group_name (str)

Return type:

None

start(name, group)[source]

Start a new profiling event.

Returns:

A unique identifier for the event.

Parameters:

  • name (str)

  • group (str)

Return type:

str

end(group)[source]

End the current profiling event for a group.

Returns:

A unique identifier for the event.

Parameters:

group (str)

Return type:

str

end_all(group)[source]

End all profiling events for a group.

Parameters:

group (str)

Return type:

None

add_record(name, group, time)[source]

Add a performance profiling record.

Parameters:

  • name (str) – Name for the profiling event.

  • group (str) – Group category for the event being profiled.

  • time (float) – Time duration associated with the profiling event in seconds.

Returns:

A unique identifier for the record.

Return type:

str

get_event_time(event_id, group=None)[source]

Get the duration of a profiling event in seconds.

Parameters:

  • event_id (str)

  • group (str | None)

Return type:

float

get_profiler_data(name=None, group=None)[source]

Return profiler data filtered by name and/or group.

Extract profiling data from a resolved group and parse it into structured results. Allow optional filtering by entity name.

Parameters:

  • name (str | None)

  • group (str | None)

Return type:

list[ProfilerResult]

save_profiler_results_as_prof_file(group, file_path)[source]

Save profiler data as a cprofiler binary file for further analysis.

Compatible with tools like https://github.com/jrfonseca/gprof2dot or https://jiffyclub.github.io/snakeviz/#snakeviz.

Parameters:

  • group (str)

  • file_path (Path)

Return type:

None

is_profiling(group=None)[source]

Check if profiling is active for a given group.

Return True if the group has an entry which has started and not yet stopped.

Parameters:

group (str | None)

Return type:

bool

item_model()[source]

:return the underlying QAbstractItemModel for the profiler.

Return type:

_Stub

clear(group=None)[source]

Clear all profiling data for a given group.

Note that this does not remove the group.

Parameters:

group (str | None)

Return type:

None

clear_all()[source]

Clear all profiling data from all groups.

Note that this does not remove any group.

Return type:

None