Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 1 | :mod:`importlib` -- An implementation of :keyword:`import` |
| 2 | ========================================================== |
| 3 | |
| 4 | .. module:: importlib |
| 5 | :synopsis: An implementation of the import machinery. |
| 6 | |
| 7 | .. moduleauthor:: Brett Cannon <brett@python.org> |
| 8 | .. sectionauthor:: Brett Cannon <brett@python.org> |
| 9 | |
| 10 | .. versionadded:: 3.1 |
| 11 | |
| 12 | |
| 13 | Introduction |
| 14 | ------------ |
| 15 | |
| 16 | The purpose of the :mod:`importlib` package is two-fold. One is to provide an |
| 17 | implementation of the :keyword:`import` statement (and thus, by extension, the |
| 18 | :func:`__import__` function) in Python source code. This provides an |
| 19 | implementaiton of :keyword:`import` which is portable to any Python |
| 20 | interpreter. This also provides a reference implementation which is easier to |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 21 | comprehend than one in a programming language other than Python. |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 22 | |
| 23 | Two, the components to implement :keyword:`import` can be exposed in this |
| 24 | package, making it easier for users to create their own custom objects (known |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 25 | generically as an :term:`importer`) to participate in the import process. |
| 26 | Details on providing custom importers can be found in :pep:`302`. |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 27 | |
| 28 | .. seealso:: |
| 29 | |
| 30 | :ref:`import` |
| 31 | The language reference for the :keyword:`import` statement. |
| 32 | |
| 33 | `Packages specification <http://www.python.org/doc/essays/packages.html>`__ |
| 34 | Original specification of packages. Some semantics have changed since |
| 35 | the writing of this document (e.g. redirecting based on :keyword:`None` |
| 36 | in :data:`sys.modules`). |
| 37 | |
| 38 | The :func:`.__import__` function |
| 39 | The built-in function for which the :keyword:`import` statement is |
| 40 | syntactic sugar for. |
| 41 | |
| 42 | :pep:`235` |
| 43 | Import on Case-Insensitive Platforms |
| 44 | |
| 45 | :pep:`263` |
| 46 | Defining Python Source Code Encodings |
| 47 | |
| 48 | :pep:`302` |
| 49 | New Import Hooks. |
| 50 | |
| 51 | :pep:`328` |
| 52 | Imports: Multi-Line and Absolute/Relative |
| 53 | |
| 54 | :pep:`366` |
| 55 | Main module explicit relative imports |
| 56 | |
| 57 | :pep:`3128` |
| 58 | Using UTF-8 as the Default Source Encoding |
| 59 | |
| 60 | |
| 61 | Functions |
| 62 | --------- |
| 63 | |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 64 | .. function:: __import__(name, globals={}, locals={}, fromlist=list(), level=0) |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 65 | |
| 66 | An implementation of the built-in :func:`__import__` function. See the |
| 67 | built-in function's documentation for usage instructions. |
| 68 | |
| 69 | .. function:: import_module(name, package=None) |
| 70 | |
Brett Cannon | 33418c8 | 2009-01-22 18:37:20 +0000 | [diff] [blame] | 71 | Import a module. The *name* argument specifies what module to |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 72 | import in absolute or relative terms |
| 73 | (e.g. either ``pkg.mod`` or ``..mod``). If the name is |
Brett Cannon | 33418c8 | 2009-01-22 18:37:20 +0000 | [diff] [blame] | 74 | specified in relative terms, then the *package* argument must be |
Brett Cannon | 2c318a1 | 2009-02-07 01:15:27 +0000 | [diff] [blame] | 75 | set to the package which is to act as the anchor for resolving the |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 76 | package name (e.g. ``import_module('..mod', 'pkg.subpkg')`` will import |
Brett Cannon | 2c318a1 | 2009-02-07 01:15:27 +0000 | [diff] [blame] | 77 | ``pkg.mod``). |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 78 | |
Brett Cannon | 2c318a1 | 2009-02-07 01:15:27 +0000 | [diff] [blame] | 79 | The :func:`import_module` function acts as a simplifying wrapper around |
| 80 | :func:`__import__`. This means all semantics of the function are derived |
| 81 | from :func:`__import__`, including requiring the package where an import is |
| 82 | occuring from to already be imported (i.e., *package* must already be |
| 83 | imported). |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 84 | |
| 85 | :mod:`importlib.machinery` -- Importers and path hooks |
| 86 | ------------------------------------------------------ |
| 87 | |
| 88 | .. module:: importlib.machinery |
| 89 | :synopsis: Importers and path hooks |
| 90 | |
| 91 | This module contains the various objects that help :keyword:`import` |
| 92 | find and load modules. |
| 93 | |
| 94 | .. class:: BuiltinImporter |
| 95 | |
| 96 | :term:`Importer` for built-in modules. All known built-in modules are |
| 97 | listed in :data:`sys.builtin_module_names`. |
| 98 | |
| 99 | Only class methods are defined by this class to alleviate the need for |
| 100 | instantiation. |
| 101 | |
Benjamin Peterson | 97d3aa5 | 2009-01-25 19:44:16 +0000 | [diff] [blame] | 102 | .. classmethod:: find_module(fullname, path=None) |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 103 | |
| 104 | Class method that allows this class to be a :term:`finder` for built-in |
| 105 | modules. |
| 106 | |
Benjamin Peterson | 97d3aa5 | 2009-01-25 19:44:16 +0000 | [diff] [blame] | 107 | .. classmethod:: load_module(fullname) |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 108 | |
| 109 | Class method that allows this class to be a :term:`loader` for built-in |
| 110 | modules. |
| 111 | |
| 112 | |
| 113 | .. class:: FrozenImporter |
| 114 | |
| 115 | :term:`Importer` for frozen modules. |
| 116 | |
| 117 | Only class methods are defined by this class to alleviate the need for |
| 118 | instantiation. |
| 119 | |
Benjamin Peterson | 97d3aa5 | 2009-01-25 19:44:16 +0000 | [diff] [blame] | 120 | .. classmethod:: find_module(fullname, path=None) |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 121 | |
| 122 | Class method that allows this class to be a :term:`finder` for frozen |
| 123 | modules. |
| 124 | |
Benjamin Peterson | 97d3aa5 | 2009-01-25 19:44:16 +0000 | [diff] [blame] | 125 | .. classmethod:: load_module(fullname) |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 126 | |
| 127 | Class method that allows this class to be a :term:`loader` for frozen |
| 128 | modules. |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 129 | |
| 130 | |
| 131 | .. class:: PathFinder |
| 132 | |
| 133 | :term:`Finder` for :data:`sys.path`. |
| 134 | |
| 135 | This class does not perfectly mirror the semantics of :keyword:`import` in |
| 136 | terms of :data:`sys.path`. No implicit path hooks are assumed for |
| 137 | simplification of the class and its semantics. |
| 138 | |
| 139 | Only class method are defined by this class to alleviate the need for |
| 140 | instantiation. |
| 141 | |
| 142 | .. classmethod:: find_module(fullname, path=None) |
| 143 | |
| 144 | Class method that attempts to find a :term:`loader` for the module |
| 145 | specified by *fullname* either on :data:`sys.path` or, if defined, on |
| 146 | *path*. For each path entry that is searched, |
| 147 | :data:`sys.path_importer_cache` is checked. If an non-false object is |
| 148 | found then it is used as the :term:`finder` to query for the module |
| 149 | being searched for. For no entry is found in |
| 150 | :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is |
| 151 | searched for a finder for the path entry and, if found, is stored in |
| 152 | :data:`sys.path_importer_cache` along with being queried about the |
| 153 | module. |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 154 | |
| 155 | |
| 156 | :mod:`importlib.util` -- Utility code for importers |
| 157 | --------------------------------------------------- |
| 158 | |
| 159 | .. module:: importlib.util |
| 160 | :synopsis: Importers and path hooks |
| 161 | |
| 162 | This module contains the various objects that help in the construction of |
| 163 | an :term:`importer`. |
| 164 | |
| 165 | .. function:: module_for_loader(method) |
| 166 | |
| 167 | A :term:`decorator` for a :term:`loader` which handles selecting the proper |
| 168 | module object to load with. The decorated method is expected to have a call |
| 169 | signature of ``method(self, module_object)`` for which the second argument |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame^] | 170 | will be the module object to be used by the loader (note that the decorator |
| 171 | will not work on static methods because of the assumption of two |
| 172 | arguments). |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 173 | |
| 174 | The decorated method will take in the name of the module to be loaded as |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame^] | 175 | expected for a :term:`loader`. If the module is not found in |
| 176 | :data:`sys.modules` then a new one is constructed with its |
| 177 | :attr:`__name__` attribute set. Otherwise the module found in |
| 178 | :data:`sys.modules` will be passed into the method. If an |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 179 | exception is raised by the decorated method and a module was added to |
| 180 | :data:`sys.modules` it will be removed to prevent a partially initialized |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame^] | 181 | module from being in left in :data:`sys.modules`. If the module was already |
| 182 | in :data:`sys.modules` then it is left alone. |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 183 | |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame^] | 184 | Use of this decorator handles all the details of what module object a |
| 185 | loader should initialize as specified by :pep:`302`. |
| 186 | |
| 187 | |
| 188 | .. function:: set___package__(method) |
| 189 | |
| 190 | A :term:`decorator` for a :term:`loader` to set the :attr:`__package__` |
| 191 | attribute on the module returned by the loader. If :attr:`__package__` is |
| 192 | set and has a value other than :keyword:`None` it will not be changed. |
| 193 | Note that the module returned by the loader is what has the attribute |
| 194 | set on and not the module found in :data:`sys.modules`. |