Go to the latest version of this document.

# ``twisted`.`python`.`modules``

module documentation
(source)

This module aims to provide a unified, object-oriented view of Python's runtime hierarchy.

Python is a very dynamic language with wide variety of introspection utilities. However, these utilities can be hard to use, because there is no consistent API. The introspection API in python is made up of attributes (__name__, __module__, func_name, etc) on instances, modules, classes and functions which vary between those four types, utility modules such as 'inspect' which provide some functionality, the 'imp' module, the "compiler" module, the semantics of PEP 302 support, and setuptools, among other things.

At the top, you have "PythonPath", an abstract representation of sys.path which includes methods to locate top-level modules, with or without loading them. The top-level exposed functions in this module for accessing the system path are "walkModules", "iterModules", and "getModule".

From most to least specific, here are the objects provided:

                      PythonPath  # sys.path
                          |
                          v
                      PathEntry   # one entry on sys.path: an importer
                          |
                          v
                     PythonModule # a module or package that can be loaded
                          |
                          v
                     PythonAttribute # an attribute of a module (function or class)
                          |
                          v
                     PythonAttribute # an attribute of a function or class
                          |
                          v
                         ...

Here's an example of idiomatic usage: this is what you would do to list all of the modules outside the standard library's python-files directory:

        import os
        stdlibdir = os.path.dirname(os.__file__)

        from twisted.python.modules import iterModules

        for modinfo in iterModules():
            if (modinfo.pathEntry.filePath.path != stdlibdir
                and not modinfo.isPackage()):
                print('unpackaged: %s: %s' % (
                    modinfo.name, modinfo.filePath.path))

Interface | `IPathImportMapper` | This is an internal interface, used to map importers to factories for FilePath-like objects.
Class | `PathEntry` | I am a proxy for a single entry on sys.path.
Class | `PythonAttribute` | I represent a function, class, or other object that is present.
Class | `PythonModule` | Representation of a module which could be imported from sys.path.
Class | `PythonPath` | I represent the very top of the Python object-space, the module list in `sys.path` and the modules list in `sys.modules`.
Function | `getModule` | Retrieve a module from the system path.
Function | `iterModules` | Iterate all modules and top-level packages on the global Python path, but do not descend into packages.
Function | `walkModules` | Deeply iterate all modules on the global python path.
Constant | `OPTIMIZED_MODE` | Undocumented
Constant | `PYTHON_EXTENSIONS` | Undocumented
Variable | `theSystemPath` | The very top of the Python object space.
Class | `_DefaultMapImpl` | Wrapper for the default importer, i.e. None.
Class | `_ModuleIteratorHelper` | This mixin provides common behavior between python module and path entries, since the mechanism for searching sys.path and __path__ attributes is remarkably similar.
Class | `_ZipMapImpl` | IPathImportMapper implementation for zipimport.ZipImporter.
Function | `_defaultSysPathFactory` | Provide the default behavior of PythonPath's sys.path factory, which is to return the current value of sys.path.
Function | `_isPackagePath` | Undocumented
Function | `_isPythonIdentifier` | cheezy fake test for proper identifier-ness.
Variable | `_nothing` | Undocumented
Variable | `_theDefaultMapper` | Undocumented

def getModule(moduleName): (source)

Retrieve a module from the system path.

def iterModules(): (source)

Iterate all modules and top-level packages on the global Python path, but do not descend into packages.

def walkModules(importPackages=False): (source)

Deeply iterate all modules on the global python path.

Parameters
importPackages | Import packages as they are seen.

OPTIMIZED_MODE = (source)

Undocumented

Value

    __doc__ is None

PYTHON_EXTENSIONS: `list[str]` = (source)

Undocumented

Value

    ['.py']

theSystemPath: `PythonPath` = (source)

The very top of the Python object space.

def _defaultSysPathFactory(): (source)

Provide the default behavior of PythonPath's sys.path factory, which is to return the current value of sys.path.

Returns
`sys.path`

def _isPackagePath(fpath): (source)

Undocumented

def _isPythonIdentifier(string): (source)

cheezy fake test for proper identifier-ness.

Parameters
string | a `str` which might or might not be a valid python identifier.

Returns
True or False

_nothing = (source)

Undocumented

_theDefaultMapper = (source)

Undocumented