_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

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, by parsing its source.

Note that this will not recognize symbols that are dynamically introduced to the module’s namespace or __all__ list. Modules that build __all__ at run time (e.g. numpy) yield None here; see runtime_exports.

This parses rather than runs the module, but that is not a guarantee that no code is executed: filename imports the parent package to locate a submodule, and a module whose source can’t be read (an extension module, say) is imported outright below to find its __file__. runtime_exports differs in always executing the module itself, not in executing something this never does.

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

get_exports(*, allow_exec=False)

Get symbols exported by this module, using runtime_exports if allow_exec, else exports.

runtime_exports is preferred rather than used only as a fallback, because static analysis is lossy rather than all-or-nothing: it omits names re-exported from unrelated modules, which a star import does bind. A partial list read as complete would make a caller treat a star-provided name as undefined. Static analysis remains the fallback for when importing fails.

Parameters:

allow_exec (bool) – Whether we may execute the module to enumerate its exports. Note that False is not a promise that nothing is executed; see exports.

Return type:

Optional[ImportSet] ImportSet or None

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 runtime_exports: ImportSet | None

Get symbols exported by this module, by importing it.

Unlike exports this sees a dynamically-built __all__, at the cost of executing the module. Returns exactly what from <mod> import * would bind.

Note the answer is cached in sys.modules for the life of the process, so two modules sharing a name can’t both be described in one run; the first imported wins.

Return type:

ImportSet or None

Returns:

Exports, or None if nothing exported.

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