ae.inspector

inspection and debugging helper functions

this ae namespace portion provides useful helper functions for inspection and debugging.

call stack inspection

module_callable() dynamically determines a reference to any callable object (function, class, …) in a module.

module_name(), stack_frames(), stack_var() and stack_vars() are inspecting the call stack frames to determine e.g. variable values of the callers of a function/method.

Hint

the AppBase class uses these helper functions to determine the version and title of an application, if these values are not specified in the instance initializer.

another useful helper function provided by this portion to inspect and debug your code is full_stack_trace().

dynamic execution of code blocks and expressions

for the dynamic execution of functions and code blocks the helper functions try_call(), try_exec() and exec_with_return() are provided. the helper function try_eval() evaluates dynamic expressions.

Note

make sure the dynamically executed code block or expression string is secure to prevent code injections of malware.

Hint

these functions are e.g. used by the Literal class to dynamically determine literal values.

Module Attributes

SKIPPED_MODULES

skipped modules used as default by module_name(), stack_var() and stack_vars()

base_globals

default if no global variables get passed in dynamic code/expression evaluations

Functions

exec_with_return(code_block[, …])

execute python code block and return the resulting value of its last code line.

full_stack_trace(ex)

get full stack trace from an exception.

module_callable(entry_point[, module_path])

determine dynamically a reference to a module and to a callable declared within the module.

module_file_path([local_object])

determine the absolute path of the module from which this function got called.

module_name(*skip_modules[, depth])

find the first module in the call stack that is not in skip_modules.

stack_frames([depth])

generator returning the call stack frame from the level given in depth.

stack_var(name, *skip_modules[, scope, depth])

determine variable value in calling stack/frames.

stack_vars(*skip_modules[, find_name, …])

determine all global and local variables in a calling stack/frames.

try_call(callee, *args[, ignored_exceptions])

execute callable while ignoring specified exceptions and return callable return value.

try_eval(expr[, ignored_exceptions, …])

evaluate expression string ignoring specified exceptions and return evaluated value.

try_exec(code_block[, ignored_exceptions, …])

execute python code block string ignoring specified exceptions and return value of last code line in block.

SKIPPED_MODULES = ('ae.base', 'ae.paths', 'ae.inspector', 'ae.core', 'ae.console', 'ae.gui_app', 'ae.gui_help', 'ae.kivy_app', 'ae.enaml_app', 'ae.beeware_app', 'ae.pyglet_app', 'ae.pygobject_app', 'ae.dabo_app', 'ae.qpython_app', 'ae.appjar_app')

skipped modules used as default by module_name(), stack_var() and stack_vars()

exec_with_return(code_block, ignored_exceptions=(), glo_vars=None, loc_vars=None)[source]

execute python code block and return the resulting value of its last code line.

Parameters
  • code_block (str) – python code block to execute.

  • ignored_exceptions (Tuple[Type[Exception], …]) – tuple of ignored exceptions.

  • glo_vars (Optional[Dict[str, Any]]) – optional globals() available in the code execution.

  • loc_vars (Optional[Dict[str, Any]]) – optional locals() available in the code execution.

Return type

Optional[Any]

Returns

value of the expression at the last code line or UNSET if either code block is empty, only contains comment lines, or one of the ignorable exceptions raised or if last code line is no expression.

inspired by this SO answer https://stackoverflow.com/questions/33409207/how-to-return-value-from-exec-in-function/52361938#52361938.

full_stack_trace(ex)[source]

get full stack trace from an exception.

Parameters

ex (Exception) – exception instance.

Return type

str

Returns

str with stack trace info.

module_callable(entry_point, module_path='')[source]

determine dynamically a reference to a module and to a callable declared within the module.

Parameters
  • entry_point (str) – callable specified in the form <module_name>:<callable_name>. for modules not installed in sys.path pass also the module_path argument.

  • module_path (str) – optional path where the module is situated (only needed if path is not is sys.path).

Return type

Tuple[Optional[module], Optional[Callable]]

Returns

tuple of module object and callable object (UNSET if module/callable doesn’t exist).

module_file_path(local_object=None)[source]

determine the absolute path of the module from which this function got called.

Parameters

local_object (Optional[Callable]) – optional local module, class, method, function, traceback, frame, or code object of the calling module (passing lambda: 0 also works). omit to use instead the __file__ module variable (which will not work if the module is frozen (by py2exe/PyInstaller).

Return type

str

Returns

module path (inclusive module file name) or empty string if path not found/determinable.

module_name(*skip_modules, depth=0)[source]

find the first module in the call stack that is not in skip_modules.

Parameters
  • skip_modules (str) – module names to skip (def=this ae.core module).

  • depth (int) – the calling level from which on to search. the default value 0 refers the frame and the module of the caller of this function. pass 1 or a even higher value if you want to get the module name of a function/method in a deeper level in the call stack.

Return type

Optional[str]

Returns

the module name of the call stack level specified by depth.

stack_frames(depth=1)[source]

generator returning the call stack frame from the level given in depth.

Parameters

depth (int) – the stack level to start; the first returned frame by this generator. the default value (1) refers the next deeper stack frame, respectively the one of the caller of this function. pass 2 or a higher value if you want to start with an even deeper frame/level.

Return type

Generator

Returns

generated frames of the call stack.

stack_var(name, *skip_modules, scope='', depth=1)[source]

determine variable value in calling stack/frames.

Parameters
  • name (str) – variable name to search in the calling stack frames.

  • skip_modules (str) – module names to skip (def=see SKIPPED_MODULES module constant).

  • scope (str) – pass ‘locals’ to only check for local variables (ignoring globals) or ‘globals’ to only check for global variables (ignoring locals). the default value (an empty string) will not restrict the scope, returning either a local or global value.

  • depth (int) – the calling level from which on to search. the default value (1) refers the next deeper stack frame, which is the caller of the function). pass 2 or a even higher value if you want to start the variable search from a deeper level in the call stack.

Return type

Optional[Any]

Returns

the variable value of a deeper level within the call stack or UNSET if the variable was not found.

stack_vars(*skip_modules, find_name='', min_depth=1, max_depth=0, scope='')[source]

determine all global and local variables in a calling stack/frames.

Parameters
  • skip_modules (str) – module names to skip (def=see SKIPPED_MODULES module constant).

  • find_name (str) – if passed then the returned stack frame must contain a variable with the passed name.

  • scope (str) – scope to search the variable name passed via find_name. pass ‘locals’ to only search for local variables (ignoring globals) or ‘globals’ to only check for global variables (ignoring locals). passing an empty string will find the variable within either locals and globals.

  • min_depth (int) – the call stack level from which on to search. the default value (1) refers the next deeper stack frame, respectively to the caller of this function. pass 2 or a higher value if you want to get the variables from a deeper level in the call stack.

  • max_depth (int) – the maximum depth in the call stack from which to return the variables. if the specified argument is not zero and no skip_modules are specified then the first deeper stack frame that is not within the default SKIPPED_MODULES will be returned. if this argument and find_name get not passed then the variables of the top stack frame will be returned.

Return type

Tuple[Dict[str, Any], Dict[str, Any], int]

Returns

tuple of the global and local variable dicts and the depth in the call stack.

try_call(callee, *args, ignored_exceptions=(), **kwargs)[source]

execute callable while ignoring specified exceptions and return callable return value.

Parameters
  • callee (Callable) – pointer to callable (either function pointer, lambda expression, a class, …).

  • args – function arguments tuple.

  • ignored_exceptions (Tuple[Type[Exception], …]) – tuple of ignored exceptions.

  • kwargs – function keyword arguments dict.

Return type

Optional[Any]

Returns

function return value or UNSET if a ignored exception got thrown.

try_eval(expr, ignored_exceptions=(), glo_vars=None, loc_vars=None)[source]

evaluate expression string ignoring specified exceptions and return evaluated value.

Parameters
  • expr (str) – expression to evaluate.

  • ignored_exceptions (Tuple[Type[Exception], …]) – tuple of ignored exceptions.

  • glo_vars (Optional[Dict[str, Any]]) – optional globals() available in the expression evaluation.

  • loc_vars (Optional[Dict[str, Any]]) – optional locals() available in the expression evaluation.

Return type

Optional[Any]

Returns

function return value or UNSET if a ignored exception got thrown.

try_exec(code_block, ignored_exceptions=(), glo_vars=None, loc_vars=None)[source]

execute python code block string ignoring specified exceptions and return value of last code line in block.

Parameters
  • code_block (str) – python code block to be executed.

  • ignored_exceptions (Tuple[Type[Exception], …]) – tuple of ignored exceptions.

  • glo_vars (Optional[Dict[str, Any]]) – optional globals() available in the code execution.

  • loc_vars (Optional[Dict[str, Any]]) – optional locals() available in the code execution.

Return type

Optional[Any]

Returns

function return value or UNSET if a ignored exception got thrown.

base_globals

default if no global variables get passed in dynamic code/expression evaluations