Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

brainprep.utils.find_stack_level

brainprep.utils.find_stack_level()

Return the index of the first stack frame outside the brainprep package.

This function walks backward through the current call stack and finds the first frame whose file path does not belong to the brainprep package directory. Test files (i.e., files whose names start with test_) are always treated as external. This is useful for producing cleaner warnings and error messages by pointing to user code rather than internal library frames.

Returns:

int

The number of internal frames to skip before reaching user code.

Notes

Adapted from the pandas codebase.

Examples

>>> import warnings
>>> from brainprep.utils import find_stack_level
>>>
>>> def load_data(path):
...     if not path.exists():
...         warnings.warn(
...             "The provided path does not exist.",
...             stacklevel=find_stack_level()
...         )