better_launch.utils.introspection module

better_launch.utils.introspection.find_calling_frame(func: Callable) → FrameInfo

Find the most recent stack frame the specified function is called in that is NOT in the same file as the function. This is useful to e.g. identify the python file a function is imported from and called in.

Note that the function must be part of the current stack frame that led to the invocation of this function.

Parameters

funcCallable: A defined function.

Returns

inspect.FrameInfo: A frame which called the provided function but lives in a different file than the function itself.

Raises

ValueError: If no such frame could be found.

better_launch.utils.introspection.find_decorated_function_args(decorator_func: Callable) → dict[str, Any]

Retrieve the arguments of the function that the specified decorator is wrapping.

Note that the function must be part of the current stack frame that led to the invocation of this function.

Parameters

decorator_funcCallable: A decorator function.

Returns

dict[str, Any]: The arguments that were used to invoke the function decorated by the provided decorator.

Raises

ValueError: If the function could not be extracted from the decorator or the function frame could not be identified.

better_launch.utils.introspection.find_function_frame(func: Callable) → FrameInfo

Find the most recent stack frame the specified function is called in.

Note that the function must be part of the current stack frame that led to the invocation of this function.

Parameters

funcCallable: A defined function.

Returns

inspect.FrameInfo: The frame the specified function was called from.

Raises

ValueError: If no such frame could be found.

better_launch.utils.introspection.find_launchthis_function(filepath: str) → FunctionDef

Parses a source file into an AST tree and searches for a function decorated by better_launch.launch_this().

Parameters

filepathstr: Path to a python source file.

Returns

ast.FunctionDef: A representation of the function decorated by launch_this, or None if it could not be found.

better_launch.utils.introspection.get_bound_arguments(func: Callable, with_defaults: bool = True) → dict[str, Any]

Retrieve the arguments that were passed to the specified function.

Note that the function must be part of the current stack frame that led to the invocation of this function.

Parameters

funcCallable: A defined function.
with_defaultsbool: If True the returned dict will include defaults according to the function’s signature for arguments that were not passed to it.

Returns

dict[str, Any]: The arguments that were used to invoke the function.

Raises

ValueError: If the function frame could not be identified.

better_launch.utils.introspection.get_launchfunc_signature_from_file(filepath: str) → tuple[str, Signature, str]

Searches for a launch function in the specified source file and returns its name, signature and docstring.

Parameters

filepathstr: Path to a python source file

Returns

tuple[str, inspect.Signature]: The name, signature and docstring of the function decorated by launch_this. If no docstring is defined for the function it will be None. Likewise, if no such function could be found all parts of the returned tuple will be None.