pydecorium.decorators.FunctionProfiler#

To use the FunctionProfiler decorator, refer to the documentation FunctionProfiler Usage.

class pydecorium.decorators.FunctionProfiler(profiler_utils: Type | List[Type] | None = None, report_format: str = 'datetime', *args, **kwargs)[source]#

FunctionProfiler is a pydecorium.Decorator that profile the execution of a function such as execution time, memory usage etc.

Several profiler utils pydecorium.decorators.ProfilerUtils can be connected to the FunctionProfiler according to the user’s needs. Each profiler utils is used to collect a specific data during the function execution. For example, the pydecorium.decorators.Timer is used to collect the execution time of the function and the pydecorium.decorators.Memory is used to collect the memory usage of the function.

The various functions and methods decorated with the FunctionProfiler are identified by their func pointer. When the report of the profiled data is generated, the function signature name is used to help the user to identify the profiled data. The signature_name_format attribute of this decorator can be used to customize the function signature name (see pydecorium.Decorator).

The report of the profiled data can be formatted in three different ways: “datetime”, “function”, “cumulative”.

Parameters:

  • profiler_utils (Union[Type, List[Type]]) – The list of sub-classes of the ProfilerUtils class to connect to the FunctionProfiler. Default is None.

  • report_format (str) – The format of the string to report the profiled data. (see pydecorium.decorators.FunctionProfiler.set_report_format()). The valid values are: “datetime”, “function”, “cumulative”. Default is “datetime”.

report_format#

The format of the string to report the profiled data. (see pydecorium.decorators.FunctionProfiler.set_report_format()).

Type:

str

profiled_functions#

The list containing the functions/methods actually profiled by the FunctionProfiler.

Type:

List[Callable]

profiled_functions_signature_name#

The list containing the signature name of the functions/methods actually profiled by the FunctionProfiler.

Type:

List[str]

connected_profiler_utils#

The list of the connected ProfilerUtils to the FunctionProfiler.

Type:

List[ProfilerUtils]

profiled_data#

The list of the profiled data containing the datetime, the index of the function and the data collected by the connected ProfilerUtils. The data are a dictionary with the index of the connected ProfilerUtils as key and the data collected as value.

Type:

List[List]

report#

The string reporting the profiled data according to the selected report_format.

Type:

str

connect_profiler_utils(profiler_utils: Type | List[Type] | None = None) → None[source]#

Connects a sub-class of the ProfilerUtils class to the FunctionProfiler. If a logger utils is None, it will be ignored.

Parameters:

profiler_utils (Union[Type, List[Type]]) – The sub-class of the ProfilerUtils class to connect to the FunctionProfiler.

Raises:

TypeError – If the logger is not an instance of ProfilerUtils or a list of FunctionProfiler.

disconnect_all() → None[source]#

Disconnects all the profiler utils connected to the FunctionProfiler.

Note

The profiled data are removed.

extract_connected_profiler_utils() → List[ProfilerUtils][source]#

Extracts the list of the connected ProfilerUtils to the FunctionProfiler. Note that the list contains the instances of the connected ProfilerUtils and not the classes.

Note

The list can also be get using the ‘connected_profiler_utils’ attribute.

Returns:

The list of the connected ProfilerUtils to the FunctionProfiler.

Return type:

List[ProfilerUtils]

extract_loggeg_functions() → List[Callable][source]#

Extracts the list containing the functions/methods actually profiled by the FunctionProfiler. The list is sorted by the order of the function calls.

Note

The list can also be get using the ‘profiled_functions’ attribute.

Returns:

The list containing the functions/methods actually profiled by the FunctionProfiler.

Return type:

List[Callable]

extract_loggeg_functions_signature_name() → List[str][source]#

Extracts the list containing the signature name of the functions/methods actually profiled by the FunctionProfiler. The list is sorted by the order of the function calls.

Note

The list can also be get using the ‘profiled_functions_signature_name’ attribute.

Returns:

The list containing the signature name of the functions/methods actually profiled by the FunctionProfiler.

Return type:

List[str]

extract_profiled_data() → List[List][source]#

Extracts the list of the profiled data containing the datetime, the function and the data collected by the connected ProfilerUtils. The list is sorted by the order of the function calls.

Note

The list can also be get using the ‘profiled_data’ attribute.

The structure of the list is as follows:

profiled_data = [[datetime, function_index, {utils_index: data, utils_index: data, ...}], ...]
Returns:

The list of the profiled data containing the datetime, the index of the function and the data collected by the connected ProfilerUtils.

Return type:

List[List]

extract_profiled_data_reorganized_by_function() → Dict[int, List[List]][source]#

Reorganizes the profiled data by function.

For example, the profiled data:

data = [[datetime, function_index_1, {utils_index: data, utils_index: data, ...}],
        [datetime, function_index_2, {utils_index: data, utils_index: data, ...}],
        [datetime, function_index_1, {utils_index: data, utils_index: data, ...}], ...]

becomes:

data = {function_index_1: [[datetime, {utils_index: data, utils_index: data, ...}],
                        [datetime, {utils_index: data, utils_index: data, ...}], ...],
        function_index_2: [[datetime, {utils_index: data, utils_index: data, ...}], ...], ...}
Returns:

The profiled data reorganized by function.

Return type:

Dict[int, List[List]]

generate_report() → str[source]#

Generates the report of the FunctionProfiler according to the log format.

See also

pydecorium.decorators.FunctionProfiler.set_report_format()

Returns:

The report of the FunctionProfiler in the specified log format.

Return type:

str

generate_report_cumulative() → str[source]#

Generates the report of the FunctionProfiler in the “cumulative” format.

See also

pydecorium.decorators.FunctionProfiler.set_report_format()

Returns:

The report of the FunctionProfiler in the “cumulative” format.

Return type:

str

generate_report_datetime() → str[source]#

Generates the report of the FunctionProfiler in the “datetime” format.

See also

pydecorium.decorators.FunctionProfiler.set_report_format()

Returns:

The report of the FunctionProfiler in the “datetime” format.

Return type:

str

generate_report_function() → str[source]#

Generates the report of the FunctionProfiler in the “function” format.

See also

pydecorium.decorators.FunctionProfiler.set_report_format()

Returns:

The report of the FunctionProfiler in the “function” format.

Return type:

str

get_report_format() → str[source]#

Gets the format of the string to report the profiled data.

Note

The reported format can also be get using the ‘report_format’ attribute.

Returns:

The format of the string to report the profiled data.

Return type:

str

initialize() → None[source]#

Initializes the FunctionProfiler by removing all the profiled data.

The connected profiler utils are not removed.

set_report_format(report_format: str) → None[source]#

Sets the report_format of the FunctionProfiler. The report format is used to format the string to report the profiled data.

Note

The format can also be set using the report_format attribute.

Important

The correct format are: “datetime”, “function”, “cumulative”. (see below)

If the report_format is set to “datetime”, the reported string will be formatted as follows:

[datetime] - [function_signature_name] - data_name : data - other_data_name : other_data
[datetime] - [other_function_signature_name] - data_name : data - other_data_name : other_data
[datetime] - [function_signature_name] - data_name : data - other_data_name : other_data

If the report_format is set to “function”, the reported string will be formatted as follows:

[function_signature_name]
    [datetime] - data_name : data - other_data_name : other_data
    [datetime] - data_name : data - other_data_name : other_data
[other_function_signature_name]
    [datetime] - data_name : data - other_data_name : other_data
    [datetime] - data_name : data - other_data_name : other_data

If the report_format is set to “cumulative”, the reported string will be formatted as follows:

[function_signature_name] - N calls - data_name : cumulative_data - other_data_name : cumulative_other_date
[other_function_signature_name] - N calls - data_name : cumulative_data - other_data_name : cumulative_other_date

Warning

The cumulative reported format can’t be use if the linked FunctionProfiler returns non-numeric data.

Parameters:

report_format (str) – The format of the string to report the profiled data.

Raises:

  • TypeError – If the report_format is not a string.

  • ValueError – If the report_format is not in the correct log format.

write_report(file_path: str) → None[source]#

Writes the report of the FunctionProfiler in a file at the specified path according to the selected report_format.

Parameters:

file_path (str) – The path of the file where the report will be written.