find_outside_stacklevel

lsst.utils.introspection.find_outside_stacklevel(*module_names: str, allow_modules: Set[str] = frozenset({}), allow_methods: Set[str] = frozenset({}), stack_info: dict[str, Any] | None = None) → int

Find the stacklevel for outside of the given module.

This can be used to determine the stacklevel parameter that should be passed to log messages or warnings in order to make them appear to come from external code and not this package.

Parameters:

*module_namesstr

The names of the modules to skip when calculating the relevant stack level.

allow_modulesset [str]

Names that should not be skipped when calculating the stacklevel. If the module name starts with any of the names in this set the corresponding stacklevel is used.

allow_methodsset [str]

Method names that are allowed to be treated as “outside”. Fully qualified method names must match exactly. Method names without path components will match solely the method name itself. On Python 3.10 fully qualified names are not supported.

stack_infodict or None, optional

If given, the dictionary is filled with information from the relevant stack frame. This can be used to form your own warning message without having to call inspect.stack() yourself with the stack level.

Returns:

stacklevelint

The stacklevel to use matching the first stack frame outside of the given module.

Examples

warnings.warn(
    "A warning message",
    stacklevel=find_outside_stacklevel("lsst.daf")
)