unittest2doc.utils

Functions:

collect_module_attr(module, *[, all, names, ...])

Collect attributes from a module to construct a globals dictionary.

load_main(somemodule[, code_filter, locals, ...])

Load and execute the code from if __name__ == "__main__" block of a module.

load_module(module)

Resolve a module from string (module name or file path) or return the module if already loaded.
unittest2doc.utils.collect_module_attr(module: str | ModuleType, *, all: bool = False, names: Dict[str, str | Pattern] | list[str, Pattern] | None = None, classes: list[type] | bool | None = None, functions: bool = False, names_mapping: Dict | Callable | None = None) → Dict[str, Any]

Collect attributes from a module to construct a globals dictionary.

Parameters:

  • module (str | ModuleType) – Module object or module name/path to resolve

  • names (Dict[str, str | Pattern] | list[str, Pattern] | None) – Dictionary mapping source names to target names, or list of names to collect

  • classes (list[type] | bool | None) – List of class types to collect instances of using isinstance, or True to collect all classes

  • functions (bool) – If True, collect all top-level functions (callable but not class)

  • names_mapping (Dict | Callable | None) – Additional name mapping after collection (dict or callable)

Returns:

Dictionary of collected attributes suitable for use as globals

Return type:

Dict[str, Any]

unittest2doc.utils.load_main(somemodule: str | ModuleType, code_filter: Callable[[str], str] | None = None, locals: Dict[str, Any] | None = None, globals: Dict[str, Any] | None = None, add_code_object: bool = False) → Dict[str, Any]

Load and execute the code from if __name__ == “__main__” block of a module.

This function allows you to execute the code that would normally only run when a module is executed directly (i.e., code within if __name__ == “__main__” block).

IMPORTANT: Users are responsible for providing the correct locals and globals environment. Typically, you should import the module first to make its functions and variables available.

NOTE: This function does NOT automatically execute the module code. This is by design because modules often use relative imports (e.g., from .submodule import foo), making automatic module execution non-trivial and error-prone. The user should handle the module import process properly according to their package structure.

Parameters:

  • somemodule (str | ModuleType) – Either a module object or a file path string

  • code_filter (Callable[[str], str] | None) – Optional function to modify the code before execution

  • locals (Dict[str, Any] | None) – Local variables for code execution

  • globals (Dict[str, Any] | None) – Global variables for code execution (should contain module’s functions/vars)

  • add_code_object (bool) – If True, add source code information to functions and classes so that inspect.getsource() can work with them

Returns:

Dictionary containing the locals after execution

Return type:

Dict[str, Any]

Example:

# Typical usage pattern:
import somemodule
from somemodule import *

# Execute the __main__ block with proper environment
main_vars = load_main(somemodule, locals=locals(), globals=globals())

# With source code support for inspect.getsource():
main_vars = load_main(somemodule, add_code_object=True, globals=globals())
func = main_vars['some_function']
source = inspect.getsource(func)  # This will work!

# Or with a file path:
import importlib.util
spec = importlib.util.spec_from_file_location("mymodule", "path/to/module.py")
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)

# Prepare globals with module's functions and variables
module_globals = globals().copy()
module_globals.update(module.__dict__)

main_vars = load_main("path/to/module.py", globals=module_globals)
unittest2doc.utils.load_module(module: str | ModuleType) → ModuleType

Resolve a module from string (module name or file path) or return the module if already loaded.

Parameters:

module (str | ModuleType) – Either a module object, module name (e.g., “os.path”), or file path (e.g., “/path/to/module.py”)

Returns:

The resolved module object

Raises:

  • ImportError – If module cannot be imported or loaded

  • FileNotFoundError – If file path doesn’t exist

Return type:

ModuleType

Example

# Import by name
mod = resolve_module("os.path")

# Import by file path
mod = resolve_module("/path/to/mymodule.py")

# Return existing module
import os
mod = resolve_module(os)  # returns os module

Modules

exec_tool