_modules module

exception pyflyby._modules.ErrorDuringImportError

Exception raised by import_module if the module exists but an exception occurred while attempting to import it. That nested exception could be ImportError, e.g. if a module tries to import another module that doesn’t exist.

class pyflyby._modules.ModuleHandle(arg: Any)

A handle to a module.

_cls_cache: Dict[Any, Any] = {}
classmethod _from_filename(filename)
Return type:

ModuleHandle

classmethod _from_module(module)
Return type:

ModuleHandle

classmethod _from_modulename(modulename)
Return type:

ModuleHandle

static _member_from_node(node)
Return type:

List[str]

property ancestors: Tuple[ModuleHandle, ...]
property block: PythonBlock
classmethod containing(identifier)

Try to find the module that defines a name such as a.b.c by trying to import a, a.b, and a.b.c.

Returns:

The name of the ‘deepest’ module (most commonly it would be a.b in this example).

Return type:

ModuleHandle Module

property exists: bool

Return whether the module exists, according to pkgutil. Note that this doesn’t work for things that are only known by using sys.meta_path.

property exports: ImportSet | None

Get symbols exported by this module.

Note that this will not recognize symbols that are dynamically introduced to the module’s namespace or __all__ list.

Return type:

ImportSet or None

Returns:

Exports, or None if nothing exported.

property filename: Filename | None

Return the filename, if appropriate.

The module itself will not be imported, but if the module is not a top-level module/package, accessing this attribute may cause the parent package to be imported.

Return type:

Filename

static list()

Enumerate all top-level packages/modules.

The current working directory is excluded for autoimporting; if we autoimported random python scripts in the current directory, we could accidentally execute code with side effects.

Also exclude any module names that are not legal python module names (e.g. “try.py” or “123.py”).

Return type:

list[str]

Returns:

A list of all importable module names

property module: ModuleType

Return the module instance.

Return type:

types.ModuleType

Raises:

  • ErrorDuringImportError – The module should exist but an error occurred while attempting to import it.

  • ImportError – The module doesn’t exist.

name: DottedIdentifier
property parent: ModuleHandle | None
property submodules: Tuple[ModuleHandle, ...]

Enumerate the importable submodules of this module.

>>> ModuleHandle("email").submodules
(..., ModuleHandle('email.encoders'), ..., ModuleHandle('email.mime'), ...)
Return type:

tuple of ModuleHandle s

property text: FileText
pyflyby._modules._cached_module_finder(importer, prefix='')

Yield the modules found by the importer.

The importer path’s mtime is recorded; if the path and mtime have a corresponding cache file, the modules recorded in the cache file are returned. Otherwise, the cache is rebuilt.

Parameters:

  • importer (FileFinder) – FileFinder importer that points to a path under which imports can be found

  • prefix (str) – String to affix to the beginning of each module name

Returns:

Tuples containing (prefix+module name, a bool indicating whether the module is a package or not)

Return type:

Generator[tuple[str, bool], None, None]

pyflyby._modules._fast_iter_modules()

Return an iterator over all importable python modules.

This function patches pkgutil.iter_importer_modules for importlib.machinery.FileFinder types, causing pkgutil.iter_importer_modules to call our own custom _iter_file_finder_modules instead of pkgutil._iter_file_finder_modules.

Return type:

Generator[ModuleInfo, None, None]

Returns:

The modules that are importable by python

pyflyby._modules._format_path(path)

Format a path for printing as a log message.

If the path is a child of $HOME, the prefix is replaced with “~” for brevity. Otherwise the original path is returned.

Parameters:

path (Union[str, Path]) – Path to format

Returns:

Formatted output path

Return type:

str

pyflyby._modules._my_iter_modules(path, prefix='')
Return type:

Generator[tuple[str, bool], None, None]

pyflyby._modules._remove_import_cache_entry(path)

Remove an entry from the pyflyby import cache.

The cache lives under <user cache dir>/pyflyby/ and has two kinds of entries:

  • per-importer directories, named by the sha256 of the importer path, and

  • the <mtime_ns> cache files inside them, each holding a JSON blob of cached import names.

rebuild_import_cache removes whole per-importer directories, while _cached_module_finder removes stale <mtime_ns> files before writing a fresh one. Either kind may be passed here, so a directory is removed recursively and a file is unlinked directly.

Parameters:

path (Path) – Import cache entry (file or directory) to remove

Return type:

None

pyflyby._modules.import_module(module_name)
Return type:

ModuleType

pyflyby._modules.pyc_to_py(filename)
Return type:

str