hbutils.reflection.module

This module provides utilities for temporarily modifying Python’s import path (PYTHONPATH) and module cache.

It allows you to mount additional paths to sys.path and manage sys.modules within a context manager, ensuring that changes are properly isolated and can be reverted when exiting the context.

The main components are: - mount_pythonpath(): Context manager to temporarily add paths to PYTHONPATH - PythonPathEnv: Class representing a Python environment with specific paths and modules

mount_pythonpath

hbutils.reflection.module.mount_pythonpath(*path) → ContextManager[PythonPathEnv][source]

Append paths to PYTHONPATH within a context manager.

This function allows you to temporarily add directories to Python’s import path, making packages in those directories importable. When the context exits, both sys.path and sys.modules are restored to their original state, ensuring isolation.

Parameters:: path (str) – One or more directory paths to prepend to sys.path.
Returns:: Context manager that yields a PythonPathEnv instance representing the mounted environment.
Return type:: ContextManager[PythonPathEnv]

Examples::

Here is the testfile directory structure:

>>> import os
>>> os.system('tree test/testfile')
test/testfile
├── dir1
│   ├── gf1.py
├── dir2
│   ├── gf1.py
└── igm
    └── gf1.py

We can import values from different directories:

>>> from hbutils.reflection import mount_pythonpath
>>> with mount_pythonpath('test/testfile/igm'):
...     from gf1 import FIXED
...     print('FIXED in igm:', FIXED)
FIXED in igm: 1234567
>>>
>>> with mount_pythonpath('test/testfile/dir1'):
...     from gf1 import FIXED
...     print('FIXED in dir1:', FIXED)
FIXED in dir1: 233
>>>
>>> with mount_pythonpath('test/testfile/dir2'):
...     from gf1 import FIXED
...     print('FIXED in dir2:', FIXED)
FIXED in dir2: 455
>>>
>>> from gf1 import FIXED  # cannot import outside the context
ModuleNotFoundError: No module named 'gf1'

PythonPathEnv

class hbutils.reflection.module.PythonPathEnv(pythonpath: List[str], modules: Mapping[str, ModuleType])[source]

Python environment object that encapsulates a specific PYTHONPATH and module set.

This class represents a snapshot of Python’s import environment, including the sys.path entries and loaded modules. It can be mounted to temporarily activate this environment.

__init__(pythonpath: List[str], modules: Mapping[str, ModuleType])[source]

Constructor of PythonPathEnv.

Parameters:

pythonpath (List[str]) – Python path list to be used in this environment.
modules (Mapping[str, types.ModuleType]) – Dictionary of modules loaded in this environment.

mount(keep: bool = True) → ContextManager[PythonPathEnv][source]

Mount the PYTHONPATH and modules of this environment.

This method activates the environment by setting sys.path and sys.modules to the values stored in this PythonPathEnv instance. When the context exits, the original environment is restored.

Parameters:: keep (bool) – If True, changes made during the context (new imports, module modifications) will be kept in this PythonPathEnv instance for future mounts. If False, changes are discarded. Default is True.
Returns:: Context manager that yields this PythonPathEnv instance.
Return type:: ContextManager[PythonPathEnv]

Examples::

>>> from hbutils.reflection import mount_pythonpath
>>> with mount_pythonpath('test/testfile/igm') as env:
...     from gf1 import FIXED
...     print('FIXED in igm:', FIXED)
FIXED in igm: 1234567
>>> with env.mount():
...     from gf1 import FIXED
...     print('FIXED in igm:', FIXED)
FIXED in igm: 1234567