line_profiler.scoping_policy module

line_profiler.scoping_policy.DEFAULT_SCOPING_POLICIES: ScopingPolicyDict = {'class': 'siblings', 'func': 'siblings', 'module': 'exact'}

Default scoping policies:

class line_profiler.scoping_policy.ScopingPolicy(*values)[source]

Bases: StringEnum

StrEnum for scoping policies, that is, how it is decided whether to:

  • Profile a function found in a namespace (a class or a module), and

  • Descend into nested namespaces so that their methods and functions are profiled,

when using LineProfiler.add_class(), LineProfiler.add_module(), and add_imported_function_or_module().

Available policies are:

ScopingPolicy.EXACT

Only profile functions found in the namespace fulfilling ScopingPolicy.CHILDREN as defined below, without descending into nested namespaces

ScopingPolicy.CHILDREN

Only profile/descend into child objects, which are:

  • Classes and functions defined locally in the very module, or in the very class as its “inner classes” and methods

  • Direct submodules, in case when the namespace is a module object representing a package

ScopingPolicy.DESCENDANTS

Only profile/descend into descendant objects, which are:

  • Child classes, functions, and modules, as defined above in ScopingPolicy.CHILDREN

  • Their child classes, functions, and modules, …

  • … and so on

Note:

Since imported submodule module objects are by default placed into the namespace of their parent-package module objects, this functions largely identical to ScopingPolicy.CHILDREN for descent from module objects into other modules objects.

ScopingPolicy.SIBLINGS

Only profile/descend into sibling and descendant objects, which are:

  • Descendant classes, functions, and modules, as defined above in ScopingPolicy.DESCENDANTS

  • Classes and functions (and descendants thereof) defined in the same parent namespace to this very class, or in modules (and subpackages and their descendants) sharing a parent package to this very module

  • Modules (and subpackages and their descendants) sharing a parent package, when the namespace is a module

ScopingPolicy.NONE

Don’t check scopes; profile all functions found in the local namespace of the class/module, and descend into all nested namespaces recursively

Note:

This is probably a very bad idea for module scoping, potentially resulting in accidentally recursing through a significant portion of loaded modules; proceed with care.

Note

Other than enum.Enum methods starting and ending with single underscores (e.g. _missing_()), all methods prefixed with a single underscore are to be considered implementation details.

EXACT = 'exact'
CHILDREN = 'children'
DESCENDANTS = 'descendants'
SIBLINGS = 'siblings'
NONE = 'none'
get_filter(namespace: type | ModuleType, obj_type: Literal['func']) → Callable[[Callable], bool][source]
get_filter(namespace: type | ModuleType, obj_type: Literal['class']) → Callable[[type], bool]
get_filter(namespace: type | ModuleType, obj_type: Literal['module']) → Callable[[ModuleType], bool]
Parameters:

  • namespace (Union[type, types.ModuleType]) – Class or module to be profiled.

  • obj_type (Literal[‘func’, ‘class’, ‘module’]) – Type of object encountered in namespace:

    'func'

    Either a function, or a component function of a callable-like object (e.g. property)

    'class' (resp. 'module')

    A class (resp. a module)

Returns:

Filter callable returning whether the argument (as specified by obj_type) should be added via LineProfiler.add_class(), LineProfiler.add_module(), or LineProfiler.add_callable()

Return type:

func (Callable[…, bool])

classmethod to_policies(policies: str | ScopingPolicy | ScopingPolicyDict | None = None) → _ScopingPolicyDict[source]

Normalize policies into a dictionary of policies for various object types.

Parameters:

policies (Union[str, ScopingPolicy, ScopingPolicyDict, None]) – ScopingPolicy, string convertible thereto (case-insensitive), or a mapping containing such values and the keys as outlined in the return value; the default None is equivalent to DEFAULT_SCOPING_POLICIES.

Returns:

Dictionary with the following key-value pairs:

'func'

ScopingPolicy for profiling functions and other callable-like objects composed thereof (e.g. property).

'class'

ScopingPolicy for descending into classes.

'module'

ScopingPolicy for descending into modules (if the namespace is itself a module).

Return type:

normalized_policies (dict[Literal[‘func’, ‘class’, ‘module’], ScopingPolicy])

Note

If policies is a mapping, it is required to contain all three of the aforementioned keys.

Example

>>> assert (ScopingPolicy.to_policies('children')
...         == dict.fromkeys(['func', 'class', 'module'],
...                          ScopingPolicy.CHILDREN))
>>> assert (ScopingPolicy.to_policies({
...             'func': 'NONE',
...             'class': 'descendants',
...             'module': 'exact',
...             'unused key': 'unused value'})
...         == {'func': ScopingPolicy.NONE,
...             'class': ScopingPolicy.DESCENDANTS,
...             'module': ScopingPolicy.EXACT})
>>> ScopingPolicy.to_policies({})
Traceback (most recent call last):
...
KeyError: 'func'
class line_profiler.scoping_policy.ScopingPolicyDict

Bases: TypedDict

func: str | ScopingPolicy
class: str | ScopingPolicy
module: str | ScopingPolicy