blob: 681f1d99cbfd1cd1888ffd6eb5313879c780143d [file] [log] [blame]
Brett Cannonafccd632009-01-20 02:21:27 +00001: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
13Introduction
14------------
15
16The purpose of the :mod:`importlib` package is two-fold. One is to provide an
17implementation of the :keyword:`import` statement (and thus, by extension, the
18:func:`__import__` function) in Python source code. This provides an
Tarek Ziadé434caaa2009-05-14 12:48:09 +000019implementation of :keyword:`import` which is portable to any Python
Brett Cannonafccd632009-01-20 02:21:27 +000020interpreter. This also provides a reference implementation which is easier to
Brett Cannonf23e3742010-06-27 23:57:46 +000021comprehend than one implemented in a programming language other than Python.
Brett Cannonafccd632009-01-20 02:21:27 +000022
Brett Cannonf23e3742010-06-27 23:57:46 +000023Two, the components to implement :keyword:`import` are exposed in this
Brett Cannonafccd632009-01-20 02:21:27 +000024package, making it easier for users to create their own custom objects (known
Brett Cannondebb98d2009-02-16 04:18:01 +000025generically as an :term:`importer`) to participate in the import process.
Brett Cannonf23e3742010-06-27 23:57:46 +000026Details on custom importers can be found in :pep:`302`.
Brett Cannonafccd632009-01-20 02:21:27 +000027
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
Georg Brandl375aec22011-01-15 17:03:02 +000035 the writing of this document (e.g. redirecting based on ``None``
Brett Cannonafccd632009-01-20 02:21:27 +000036 in :data:`sys.modules`).
37
38 The :func:`.__import__` function
Brett Cannon0e13c942010-06-29 18:26:11 +000039 The :keyword:`import` statement is syntactic sugar for this function.
Brett Cannonafccd632009-01-20 02:21:27 +000040
41 :pep:`235`
42 Import on Case-Insensitive Platforms
43
44 :pep:`263`
45 Defining Python Source Code Encodings
46
47 :pep:`302`
Brett Cannonf23e3742010-06-27 23:57:46 +000048 New Import Hooks
Brett Cannonafccd632009-01-20 02:21:27 +000049
50 :pep:`328`
51 Imports: Multi-Line and Absolute/Relative
52
53 :pep:`366`
54 Main module explicit relative imports
55
Brett Cannon8917d5e2010-01-13 19:21:00 +000056 :pep:`3120`
Brett Cannonafccd632009-01-20 02:21:27 +000057 Using UTF-8 as the Default Source Encoding
58
Brett Cannon30b7a902010-06-27 21:49:22 +000059 :pep:`3147`
60 PYC Repository Directories
61
Brett Cannonafccd632009-01-20 02:21:27 +000062
63Functions
64---------
65
Brett Cannoncb4996a2012-08-06 16:34:44 -040066.. function:: __import__(name, globals=None, locals=None, fromlist=(), level=0)
Brett Cannonafccd632009-01-20 02:21:27 +000067
Brett Cannonf23e3742010-06-27 23:57:46 +000068 An implementation of the built-in :func:`__import__` function.
Brett Cannonafccd632009-01-20 02:21:27 +000069
70.. function:: import_module(name, package=None)
71
Brett Cannon33418c82009-01-22 18:37:20 +000072 Import a module. The *name* argument specifies what module to
Brett Cannonafccd632009-01-20 02:21:27 +000073 import in absolute or relative terms
74 (e.g. either ``pkg.mod`` or ``..mod``). If the name is
Guido van Rossum09613542009-03-30 20:34:57 +000075 specified in relative terms, then the *package* argument must be set to
76 the name of the package which is to act as the anchor for resolving the
Brett Cannonafccd632009-01-20 02:21:27 +000077 package name (e.g. ``import_module('..mod', 'pkg.subpkg')`` will import
Brett Cannon2c318a12009-02-07 01:15:27 +000078 ``pkg.mod``).
Brett Cannon78246b62009-01-25 04:56:30 +000079
Brett Cannon2c318a12009-02-07 01:15:27 +000080 The :func:`import_module` function acts as a simplifying wrapper around
Brett Cannon9f4cb1c2009-04-01 23:26:47 +000081 :func:`importlib.__import__`. This means all semantics of the function are
82 derived from :func:`importlib.__import__`, including requiring the package
83 from which an import is occurring to have been previously imported
84 (i.e., *package* must already be imported). The most important difference
85 is that :func:`import_module` returns the most nested package or module
86 that was imported (e.g. ``pkg.mod``), while :func:`__import__` returns the
Guido van Rossum09613542009-03-30 20:34:57 +000087 top-level package or module (e.g. ``pkg``).
88
Brett Cannonee78a2b2012-05-12 17:43:17 -040089.. function:: find_loader(name, path=None)
90
91 Find the loader for a module, optionally within the specified *path*. If the
92 module is in :attr:`sys.modules`, then ``sys.modules[name].__loader__`` is
93 returned (unless the loader would be ``None``, in which case
94 :exc:`ValueError` is raised). Otherwise a search using :attr:`sys.meta_path`
95 is done. ``None`` is returned if no loader is found.
96
97 A dotted name does not have its parent's implicitly imported. If that is
98 desired (although not nessarily required to find the loader, it will most
99 likely be needed if the loader actually is used to load the module), then
100 you will have to import the packages containing the module prior to calling
101 this function.
102
Antoine Pitrouc541f8e2012-02-20 01:48:16 +0100103.. function:: invalidate_caches()
104
Brett Cannonf4dc9202012-08-10 12:21:12 -0400105 Invalidate the internal caches of finders stored at
106 :data:`sys.meta_path`. If a finder implements ``invalidate_caches()`` then it
107 will be called to perform the invalidation. This function may be needed if
108 some modules are installed while your program is running and you expect the
109 program to notice the changes.
Antoine Pitrouc541f8e2012-02-20 01:48:16 +0100110
111 .. versionadded:: 3.3
112
Brett Cannon78246b62009-01-25 04:56:30 +0000113
Brett Cannon2a922ed2009-03-09 03:35:50 +0000114:mod:`importlib.abc` -- Abstract base classes related to import
115---------------------------------------------------------------
116
117.. module:: importlib.abc
118 :synopsis: Abstract base classes related to import
119
120The :mod:`importlib.abc` module contains all of the core abstract base classes
121used by :keyword:`import`. Some subclasses of the core abstract base classes
122are also provided to help in implementing the core ABCs.
123
Andrew Svetlova8656542012-08-13 22:19:01 +0300124ABC hierarchy::
125
126 object
Brett Cannon1b799182012-08-17 14:08:24 -0400127 +-- Finder (deprecated)
Andrew Svetlova8656542012-08-13 22:19:01 +0300128 | +-- MetaPathFinder
129 | +-- PathEntryFinder
130 +-- Loader
131 +-- ResourceLoader --------+
132 +-- InspectLoader |
133 +-- ExecutionLoader --+
134 +-- FileLoader
135 +-- SourceLoader
Brett Cannon1b799182012-08-17 14:08:24 -0400136 +-- PyLoader (deprecated)
137 +-- PyPycLoader (deprecated)
Andrew Svetlova8656542012-08-13 22:19:01 +0300138
Brett Cannon2a922ed2009-03-09 03:35:50 +0000139
140.. class:: Finder
141
Brett Cannon1b799182012-08-17 14:08:24 -0400142 An abstract base class representing a :term:`finder`.
143
144 .. deprecated:: 3.3
145 Use :class:`MetaPathFinder` or :class:`PathEntryFinder` instead.
Brett Cannon2a922ed2009-03-09 03:35:50 +0000146
Brett Cannonf4dc9202012-08-10 12:21:12 -0400147 .. method:: find_module(fullname, path=None)
Brett Cannonb46a1792012-02-27 18:15:42 -0500148
Brett Cannonf4dc9202012-08-10 12:21:12 -0400149 An abstact method for finding a :term:`loader` for the specified
150 module. Originally specified in :pep:`302`, this method was meant
151 for use in :data:`sys.meta_path` and in the path-based import subsystem.
Nick Coghlan8a9080f2012-08-02 21:26:03 +1000152
153
Brett Cannon077ef452012-08-02 17:50:06 -0400154.. class:: MetaPathFinder
Nick Coghlan8a9080f2012-08-02 21:26:03 +1000155
Brett Cannonf4dc9202012-08-10 12:21:12 -0400156 An abstract base class representing a :term:`meta path finder`. For
157 compatibility, this is a subclass of :class:`Finder`.
Nick Coghlan8a9080f2012-08-02 21:26:03 +1000158
159 .. versionadded:: 3.3
160
161 .. method:: find_module(fullname, path)
162
163 An abstract method for finding a :term:`loader` for the specified
164 module. If this is a top-level import, *path* will be ``None``.
Ezio Melotti1f67e802012-10-21 07:24:13 +0300165 Otherwise, this is a search for a subpackage or module and *path*
Nick Coghlan8a9080f2012-08-02 21:26:03 +1000166 will be the value of :attr:`__path__` from the parent
167 package. If a loader cannot be found, ``None`` is returned.
168
Brett Cannonf4dc9202012-08-10 12:21:12 -0400169 .. method:: invalidate_caches()
170
171 An optional method which, when called, should invalidate any internal
Brett Cannona6e85812012-08-11 19:41:27 -0400172 cache used by the finder. Used by :func:`importlib.invalidate_caches`
173 when invalidating the caches of all finders on :data:`sys.meta_path`.
Brett Cannonf4dc9202012-08-10 12:21:12 -0400174
Nick Coghlan8a9080f2012-08-02 21:26:03 +1000175
Brett Cannon077ef452012-08-02 17:50:06 -0400176.. class:: PathEntryFinder
Nick Coghlan8a9080f2012-08-02 21:26:03 +1000177
Brett Cannonf4dc9202012-08-10 12:21:12 -0400178 An abstract base class representing a :term:`path entry finder`. Though
179 it bears some similarities to :class:`MetaPathFinder`, ``PathEntryFinder``
180 is meant for use only within the path-based import subsystem provided
181 by :class:`PathFinder`. This ABC is a subclass of :class:`Finder` for
182 compatibility.
Nick Coghlan8a9080f2012-08-02 21:26:03 +1000183
184 .. versionadded:: 3.3
185
Brett Cannon773468f2012-08-02 17:35:34 -0400186 .. method:: find_loader(fullname):
Nick Coghlan8a9080f2012-08-02 21:26:03 +1000187
188 An abstract method for finding a :term:`loader` for the specified
Brett Cannonf4dc9202012-08-10 12:21:12 -0400189 module. Returns a 2-tuple of ``(loader, portion)`` where ``portion``
190 is a sequence of file system locations contributing to part of a namespace
191 package. The loader may be ``None`` while specifying ``portion`` to
192 signify the contribution of the file system locations to a namespace
193 package. An empty list can be used for ``portion`` to signify the loader
194 is not part of a package. If ``loader`` is ``None`` and ``portion`` is
195 the empty list then no loader or location for a namespace package were
196 found (i.e. failure to find anything for the module).
197
198 .. method:: find_module(fullname):
199
200 A concrete implementation of :meth:`Finder.find_module` which is
201 equivalent to ``self.find_loader(fullname)[0]``.
202
203 .. method:: invalidate_caches()
204
205 An optional method which, when called, should invalidate any internal
Brett Cannona6e85812012-08-11 19:41:27 -0400206 cache used by the finder. Used by :meth:`PathFinder.invalidate_caches`
Brett Cannonf4dc9202012-08-10 12:21:12 -0400207 when invalidating the caches of all cached finders.
Brett Cannonb46a1792012-02-27 18:15:42 -0500208
Brett Cannon2a922ed2009-03-09 03:35:50 +0000209
210.. class:: Loader
211
212 An abstract base class for a :term:`loader`.
Guido van Rossum09613542009-03-30 20:34:57 +0000213 See :pep:`302` for the exact definition for a loader.
Brett Cannon2a922ed2009-03-09 03:35:50 +0000214
Brett Cannon9c751b72009-03-09 16:28:16 +0000215 .. method:: load_module(fullname)
Brett Cannon2a922ed2009-03-09 03:35:50 +0000216
217 An abstract method for loading a module. If the module cannot be
218 loaded, :exc:`ImportError` is raised, otherwise the loaded module is
219 returned.
220
Guido van Rossum09613542009-03-30 20:34:57 +0000221 If the requested module already exists in :data:`sys.modules`, that
Brett Cannon2a922ed2009-03-09 03:35:50 +0000222 module should be used and reloaded.
Guido van Rossum09613542009-03-30 20:34:57 +0000223 Otherwise the loader should create a new module and insert it into
224 :data:`sys.modules` before any loading begins, to prevent recursion
225 from the import. If the loader inserted a module and the load fails, it
Brett Cannon2a922ed2009-03-09 03:35:50 +0000226 must be removed by the loader from :data:`sys.modules`; modules already
227 in :data:`sys.modules` before the loader began execution should be left
228 alone. The :func:`importlib.util.module_for_loader` decorator handles
229 all of these details.
230
Guido van Rossum09613542009-03-30 20:34:57 +0000231 The loader should set several attributes on the module.
232 (Note that some of these attributes can change when a module is
233 reloaded.)
Brett Cannon2a922ed2009-03-09 03:35:50 +0000234
235 - :attr:`__name__`
236 The name of the module.
237
238 - :attr:`__file__`
239 The path to where the module data is stored (not set for built-in
240 modules).
241
242 - :attr:`__path__`
Guido van Rossum09613542009-03-30 20:34:57 +0000243 A list of strings specifying the search path within a
Brett Cannon2a922ed2009-03-09 03:35:50 +0000244 package. This attribute is not set on modules.
245
246 - :attr:`__package__`
247 The parent package for the module/package. If the module is
248 top-level then it has a value of the empty string. The
249 :func:`importlib.util.set_package` decorator can handle the details
250 for :attr:`__package__`.
251
252 - :attr:`__loader__`
Guido van Rossum09613542009-03-30 20:34:57 +0000253 The loader used to load the module.
254 (This is not set by the built-in import machinery,
255 but it should be set whenever a :term:`loader` is used.)
Brett Cannon2a922ed2009-03-09 03:35:50 +0000256
Barry Warsawd7d21942012-07-29 16:36:17 -0400257 .. method:: module_repr(module)
258
259 An abstract method which when implemented calculates and returns the
260 given module's repr, as a string.
261
262 .. versionadded: 3.3
263
Brett Cannon2a922ed2009-03-09 03:35:50 +0000264
265.. class:: ResourceLoader
266
267 An abstract base class for a :term:`loader` which implements the optional
268 :pep:`302` protocol for loading arbitrary resources from the storage
269 back-end.
270
Brett Cannon9c751b72009-03-09 16:28:16 +0000271 .. method:: get_data(path)
Brett Cannon2a922ed2009-03-09 03:35:50 +0000272
273 An abstract method to return the bytes for the data located at *path*.
Guido van Rossum09613542009-03-30 20:34:57 +0000274 Loaders that have a file-like storage back-end
Brett Cannon16248a42009-04-01 20:47:14 +0000275 that allows storing arbitrary data
Guido van Rossum09613542009-03-30 20:34:57 +0000276 can implement this abstract method to give direct access
Brett Cannon2a922ed2009-03-09 03:35:50 +0000277 to the data stored. :exc:`IOError` is to be raised if the *path* cannot
278 be found. The *path* is expected to be constructed using a module's
Brett Cannon16248a42009-04-01 20:47:14 +0000279 :attr:`__file__` attribute or an item from a package's :attr:`__path__`.
Brett Cannon2a922ed2009-03-09 03:35:50 +0000280
281
282.. class:: InspectLoader
283
284 An abstract base class for a :term:`loader` which implements the optional
Guido van Rossum09613542009-03-30 20:34:57 +0000285 :pep:`302` protocol for loaders that inspect modules.
Brett Cannon2a922ed2009-03-09 03:35:50 +0000286
Brett Cannona113ac52009-03-15 01:41:33 +0000287 .. method:: get_code(fullname)
Brett Cannon2a922ed2009-03-09 03:35:50 +0000288
Brett Cannona113ac52009-03-15 01:41:33 +0000289 An abstract method to return the :class:`code` object for a module.
Georg Brandl375aec22011-01-15 17:03:02 +0000290 ``None`` is returned if the module does not have a code object
Brett Cannona113ac52009-03-15 01:41:33 +0000291 (e.g. built-in module). :exc:`ImportError` is raised if loader cannot
292 find the requested module.
Brett Cannon2a922ed2009-03-09 03:35:50 +0000293
R David Murray1b00f252012-08-15 10:43:58 -0400294 .. index::
295 single: universal newlines; importlib.abc.InspectLoader.get_source method
296
Brett Cannon9c751b72009-03-09 16:28:16 +0000297 .. method:: get_source(fullname)
Brett Cannon2a922ed2009-03-09 03:35:50 +0000298
299 An abstract method to return the source of a module. It is returned as
R David Murray1b00f252012-08-15 10:43:58 -0400300 a text string using :term:`universal newlines`, translating all
R David Murrayee0a9452012-08-15 11:05:36 -0400301 recognized line separators into ``'\n'`` characters. Returns ``None``
302 if no source is available (e.g. a built-in module). Raises
303 :exc:`ImportError` if the loader cannot find the module specified.
Brett Cannon2a922ed2009-03-09 03:35:50 +0000304
Brett Cannona113ac52009-03-15 01:41:33 +0000305 .. method:: is_package(fullname)
Brett Cannon2a922ed2009-03-09 03:35:50 +0000306
Brett Cannona113ac52009-03-15 01:41:33 +0000307 An abstract method to return a true value if the module is a package, a
308 false value otherwise. :exc:`ImportError` is raised if the
309 :term:`loader` cannot find the module.
Brett Cannon2a922ed2009-03-09 03:35:50 +0000310
311
Brett Cannon69194272009-07-20 04:23:48 +0000312.. class:: ExecutionLoader
313
314 An abstract base class which inherits from :class:`InspectLoader` that,
Brett Cannon23460292009-07-20 22:59:00 +0000315 when implemented, helps a module to be executed as a script. The ABC
Brett Cannon69194272009-07-20 04:23:48 +0000316 represents an optional :pep:`302` protocol.
317
318 .. method:: get_filename(fullname)
319
Brett Cannonf23e3742010-06-27 23:57:46 +0000320 An abstract method that is to return the value of :attr:`__file__` for
Brett Cannon69194272009-07-20 04:23:48 +0000321 the specified module. If no path is available, :exc:`ImportError` is
322 raised.
323
Brett Cannonf23e3742010-06-27 23:57:46 +0000324 If source code is available, then the method should return the path to
325 the source file, regardless of whether a bytecode was used to load the
326 module.
327
328
Brett Cannon938d44d2012-04-22 19:58:33 -0400329.. class:: FileLoader(fullname, path)
330
331 An abstract base class which inherits from :class:`ResourceLoader` and
332 :class:`ExecutionLoader`, providing concreate implementations of
333 :meth:`ResourceLoader.get_data` and :meth:`ExecutionLoader.get_filename`.
334
335 The *fullname* argument is a fully resolved name of the module the loader is
336 to handle. The *path* argument is the path to the file for the module.
337
338 .. versionadded:: 3.3
339
340 .. attribute:: name
341
342 The name of the module the loader can handle.
343
344 .. attribute:: path
345
346 Path to the file of the module.
347
Barry Warsawd7d21942012-07-29 16:36:17 -0400348 .. method:: load_module(fullname)
Brett Cannonc0499522012-05-11 14:48:41 -0400349
Barry Warsawd7d21942012-07-29 16:36:17 -0400350 Calls super's ``load_module()``.
Brett Cannonc0499522012-05-11 14:48:41 -0400351
Brett Cannon938d44d2012-04-22 19:58:33 -0400352 .. method:: get_filename(fullname)
353
Barry Warsawd7d21942012-07-29 16:36:17 -0400354 Returns :attr:`path`.
Brett Cannon938d44d2012-04-22 19:58:33 -0400355
356 .. method:: get_data(path)
357
358 Returns the open, binary file for *path*.
359
360
Brett Cannonf23e3742010-06-27 23:57:46 +0000361.. class:: SourceLoader
362
363 An abstract base class for implementing source (and optionally bytecode)
364 file loading. The class inherits from both :class:`ResourceLoader` and
365 :class:`ExecutionLoader`, requiring the implementation of:
366
367 * :meth:`ResourceLoader.get_data`
368 * :meth:`ExecutionLoader.get_filename`
Brett Cannon6dfbff32010-07-21 09:48:31 +0000369 Should only return the path to the source file; sourceless
Brett Cannonf23e3742010-06-27 23:57:46 +0000370 loading is not supported.
371
372 The abstract methods defined by this class are to add optional bytecode
373 file support. Not implementing these optional methods causes the loader to
374 only work with source code. Implementing the methods allows the loader to
375 work with source *and* bytecode files; it does not allow for *sourceless*
376 loading where only bytecode is provided. Bytecode files are an
377 optimization to speed up loading by removing the parsing step of Python's
378 compiler, and so no bytecode-specific API is exposed.
379
Brett Cannon773468f2012-08-02 17:35:34 -0400380 .. method:: path_stats(path)
Antoine Pitrou5136ac02012-01-13 18:52:16 +0100381
382 Optional abstract method which returns a :class:`dict` containing
383 metadata about the specifed path. Supported dictionary keys are:
384
385 - ``'mtime'`` (mandatory): an integer or floating-point number
386 representing the modification time of the source code;
387 - ``'size'`` (optional): the size in bytes of the source code.
388
389 Any other keys in the dictionary are ignored, to allow for future
390 extensions.
391
392 .. versionadded:: 3.3
393
Brett Cannon773468f2012-08-02 17:35:34 -0400394 .. method:: path_mtime(path)
Brett Cannonf23e3742010-06-27 23:57:46 +0000395
396 Optional abstract method which returns the modification time for the
397 specified path.
398
Antoine Pitrou5136ac02012-01-13 18:52:16 +0100399 .. deprecated:: 3.3
400 This method is deprecated in favour of :meth:`path_stats`. You don't
401 have to implement it, but it is still available for compatibility
402 purposes.
403
Brett Cannon773468f2012-08-02 17:35:34 -0400404 .. method:: set_data(path, data)
Brett Cannonf23e3742010-06-27 23:57:46 +0000405
406 Optional abstract method which writes the specified bytes to a file
Brett Cannon61b14252010-07-03 21:48:25 +0000407 path. Any intermediate directories which do not exist are to be created
408 automatically.
409
410 When writing to the path fails because the path is read-only
411 (:attr:`errno.EACCES`), do not propagate the exception.
Brett Cannonf23e3742010-06-27 23:57:46 +0000412
Brett Cannon773468f2012-08-02 17:35:34 -0400413 .. method:: get_code(fullname)
Brett Cannonf23e3742010-06-27 23:57:46 +0000414
415 Concrete implementation of :meth:`InspectLoader.get_code`.
416
Brett Cannon773468f2012-08-02 17:35:34 -0400417 .. method:: load_module(fullname)
Brett Cannonf23e3742010-06-27 23:57:46 +0000418
419 Concrete implementation of :meth:`Loader.load_module`.
420
Brett Cannon773468f2012-08-02 17:35:34 -0400421 .. method:: get_source(fullname)
Brett Cannonf23e3742010-06-27 23:57:46 +0000422
423 Concrete implementation of :meth:`InspectLoader.get_source`.
424
Brett Cannon773468f2012-08-02 17:35:34 -0400425 .. method:: is_package(fullname)
Brett Cannonf23e3742010-06-27 23:57:46 +0000426
427 Concrete implementation of :meth:`InspectLoader.is_package`. A module
Brett Cannonea0b8232012-06-15 20:00:53 -0400428 is determined to be a package if its file path (as provided by
429 :meth:`ExecutionLoader.get_filename`) is a file named
430 ``__init__`` when the file extension is removed **and** the module name
431 itself does not end in ``__init__``.
Brett Cannonf23e3742010-06-27 23:57:46 +0000432
Brett Cannon69194272009-07-20 04:23:48 +0000433
Brett Cannon2a922ed2009-03-09 03:35:50 +0000434.. class:: PyLoader
435
Brett Cannon69194272009-07-20 04:23:48 +0000436 An abstract base class inheriting from
Brett Cannonf23e3742010-06-27 23:57:46 +0000437 :class:`ExecutionLoader` and
438 :class:`ResourceLoader` designed to ease the loading of
Brett Cannon2a922ed2009-03-09 03:35:50 +0000439 Python source modules (bytecode is not handled; see
Brett Cannonf23e3742010-06-27 23:57:46 +0000440 :class:`SourceLoader` for a source/bytecode ABC). A subclass
Brett Cannon2a922ed2009-03-09 03:35:50 +0000441 implementing this ABC will only need to worry about exposing how the source
442 code is stored; all other details for loading Python source code will be
443 handled by the concrete implementations of key methods.
444
Brett Cannonf23e3742010-06-27 23:57:46 +0000445 .. deprecated:: 3.2
446 This class has been deprecated in favor of :class:`SourceLoader` and is
447 slated for removal in Python 3.4. See below for how to create a
Georg Brandl6faee4e2010-09-21 14:48:28 +0000448 subclass that is compatible with Python 3.1 onwards.
Brett Cannonf23e3742010-06-27 23:57:46 +0000449
450 If compatibility with Python 3.1 is required, then use the following idiom
451 to implement a subclass that will work with Python 3.1 onwards (make sure
452 to implement :meth:`ExecutionLoader.get_filename`)::
453
454 try:
455 from importlib.abc import SourceLoader
456 except ImportError:
457 from importlib.abc import PyLoader as SourceLoader
458
459
460 class CustomLoader(SourceLoader):
461 def get_filename(self, fullname):
462 """Return the path to the source file."""
463 # Implement ...
464
465 def source_path(self, fullname):
466 """Implement source_path in terms of get_filename."""
467 try:
468 return self.get_filename(fullname)
469 except ImportError:
470 return None
471
472 def is_package(self, fullname):
473 """Implement is_package by looking for an __init__ file
474 name as returned by get_filename."""
475 filename = os.path.basename(self.get_filename(fullname))
476 return os.path.splitext(filename)[0] == '__init__'
477
478
Brett Cannon9c751b72009-03-09 16:28:16 +0000479 .. method:: source_path(fullname)
Brett Cannon2a922ed2009-03-09 03:35:50 +0000480
481 An abstract method that returns the path to the source code for a
Georg Brandl375aec22011-01-15 17:03:02 +0000482 module. Should return ``None`` if there is no source code.
Brett Cannon3e761a92009-12-10 00:24:21 +0000483 Raises :exc:`ImportError` if the loader knows it cannot handle the
484 module.
Brett Cannon2a922ed2009-03-09 03:35:50 +0000485
Brett Cannon69194272009-07-20 04:23:48 +0000486 .. method:: get_filename(fullname)
487
488 A concrete implementation of
489 :meth:`importlib.abc.ExecutionLoader.get_filename` that
490 relies on :meth:`source_path`. If :meth:`source_path` returns
Georg Brandl375aec22011-01-15 17:03:02 +0000491 ``None``, then :exc:`ImportError` is raised.
Brett Cannon69194272009-07-20 04:23:48 +0000492
Brett Cannon9c751b72009-03-09 16:28:16 +0000493 .. method:: load_module(fullname)
Brett Cannon2a922ed2009-03-09 03:35:50 +0000494
495 A concrete implementation of :meth:`importlib.abc.Loader.load_module`
Brett Cannonad876c72009-03-09 07:53:09 +0000496 that loads Python source code. All needed information comes from the
497 abstract methods required by this ABC. The only pertinent assumption
498 made by this method is that when loading a package
499 :attr:`__path__` is set to ``[os.path.dirname(__file__)]``.
Brett Cannon2a922ed2009-03-09 03:35:50 +0000500
Brett Cannon9c751b72009-03-09 16:28:16 +0000501 .. method:: get_code(fullname)
Brett Cannon2a922ed2009-03-09 03:35:50 +0000502
503 A concrete implementation of
504 :meth:`importlib.abc.InspectLoader.get_code` that creates code objects
Guido van Rossum09613542009-03-30 20:34:57 +0000505 from Python source code, by requesting the source code (using
Benjamin Peterson0089d752009-11-13 00:52:43 +0000506 :meth:`source_path` and :meth:`get_data`) and compiling it with the
507 built-in :func:`compile` function.
Brett Cannon2a922ed2009-03-09 03:35:50 +0000508
Brett Cannond43b30b2009-03-10 03:29:23 +0000509 .. method:: get_source(fullname)
510
511 A concrete implementation of
512 :meth:`importlib.abc.InspectLoader.get_source`. Uses
Brett Cannon69194272009-07-20 04:23:48 +0000513 :meth:`importlib.abc.ResourceLoader.get_data` and :meth:`source_path`
514 to get the source code. It tries to guess the source encoding using
Guido van Rossum09613542009-03-30 20:34:57 +0000515 :func:`tokenize.detect_encoding`.
Brett Cannond43b30b2009-03-10 03:29:23 +0000516
Brett Cannon2a922ed2009-03-09 03:35:50 +0000517
518.. class:: PyPycLoader
519
Brett Cannonf23e3742010-06-27 23:57:46 +0000520 An abstract base class inheriting from :class:`PyLoader`.
Brett Cannon2a922ed2009-03-09 03:35:50 +0000521 This ABC is meant to help in creating loaders that support both Python
522 source and bytecode.
523
Brett Cannonf23e3742010-06-27 23:57:46 +0000524 .. deprecated:: 3.2
525 This class has been deprecated in favor of :class:`SourceLoader` and to
526 properly support :pep:`3147`. If compatibility is required with
527 Python 3.1, implement both :class:`SourceLoader` and :class:`PyLoader`;
528 instructions on how to do so are included in the documentation for
529 :class:`PyLoader`. Do note that this solution will not support
530 sourceless/bytecode-only loading; only source *and* bytecode loading.
531
Brett Cannon1e331562012-07-02 14:35:34 -0400532 .. versionchanged:: 3.3
533 Updated to parse (but not use) the new source size field in bytecode
534 files when reading and to write out the field properly when writing.
535
Brett Cannon9c751b72009-03-09 16:28:16 +0000536 .. method:: source_mtime(fullname)
Brett Cannon2a922ed2009-03-09 03:35:50 +0000537
538 An abstract method which returns the modification time for the source
539 code of the specified module. The modification time should be an
Georg Brandl375aec22011-01-15 17:03:02 +0000540 integer. If there is no source code, return ``None``. If the
Brett Cannon2a922ed2009-03-09 03:35:50 +0000541 module cannot be found then :exc:`ImportError` is raised.
542
Brett Cannon9c751b72009-03-09 16:28:16 +0000543 .. method:: bytecode_path(fullname)
Brett Cannon2a922ed2009-03-09 03:35:50 +0000544
545 An abstract method which returns the path to the bytecode for the
Georg Brandl375aec22011-01-15 17:03:02 +0000546 specified module, if it exists. It returns ``None``
Guido van Rossum09613542009-03-30 20:34:57 +0000547 if no bytecode exists (yet).
Brett Cannon3e761a92009-12-10 00:24:21 +0000548 Raises :exc:`ImportError` if the loader knows it cannot handle the
549 module.
Brett Cannon2a922ed2009-03-09 03:35:50 +0000550
Brett Cannon69194272009-07-20 04:23:48 +0000551 .. method:: get_filename(fullname)
552
553 A concrete implementation of
Brett Cannonf23e3742010-06-27 23:57:46 +0000554 :meth:`ExecutionLoader.get_filename` that relies on
555 :meth:`PyLoader.source_path` and :meth:`bytecode_path`.
Brett Cannon69194272009-07-20 04:23:48 +0000556 If :meth:`source_path` returns a path, then that value is returned.
557 Else if :meth:`bytecode_path` returns a path, that path will be
558 returned. If a path is not available from both methods,
559 :exc:`ImportError` is raised.
560
Brett Cannon9c751b72009-03-09 16:28:16 +0000561 .. method:: write_bytecode(fullname, bytecode)
Brett Cannon2a922ed2009-03-09 03:35:50 +0000562
563 An abstract method which has the loader write *bytecode* for future
Georg Brandl375aec22011-01-15 17:03:02 +0000564 use. If the bytecode is written, return ``True``. Return
565 ``False`` if the bytecode could not be written. This method
Brett Cannon2a922ed2009-03-09 03:35:50 +0000566 should not be called if :data:`sys.dont_write_bytecode` is true.
Guido van Rossum09613542009-03-30 20:34:57 +0000567 The *bytecode* argument should be a bytes string or bytes array.
Brett Cannon2a922ed2009-03-09 03:35:50 +0000568
569
Brett Cannon78246b62009-01-25 04:56:30 +0000570:mod:`importlib.machinery` -- Importers and path hooks
571------------------------------------------------------
572
573.. module:: importlib.machinery
574 :synopsis: Importers and path hooks
575
576This module contains the various objects that help :keyword:`import`
577find and load modules.
578
Brett Cannoncb66eb02012-05-11 12:58:42 -0400579.. attribute:: SOURCE_SUFFIXES
580
581 A list of strings representing the recognized file suffixes for source
582 modules.
583
584 .. versionadded:: 3.3
585
586.. attribute:: DEBUG_BYTECODE_SUFFIXES
587
588 A list of strings representing the file suffixes for non-optimized bytecode
589 modules.
590
591 .. versionadded:: 3.3
592
593.. attribute:: OPTIMIZED_BYTECODE_SUFFIXES
594
595 A list of strings representing the file suffixes for optimized bytecode
596 modules.
597
598 .. versionadded:: 3.3
599
600.. attribute:: BYTECODE_SUFFIXES
601
602 A list of strings representing the recognized file suffixes for bytecode
603 modules. Set to either :attr:`DEBUG_BYTECODE_SUFFIXES` or
604 :attr:`OPTIMIZED_BYTECODE_SUFFIXES` based on whether ``__debug__`` is true.
605
606 .. versionadded:: 3.3
607
608.. attribute:: EXTENSION_SUFFIXES
609
Nick Coghlan76e07702012-07-18 23:14:57 +1000610 A list of strings representing the recognized file suffixes for
Brett Cannoncb66eb02012-05-11 12:58:42 -0400611 extension modules.
612
613 .. versionadded:: 3.3
614
Nick Coghlanc5afd422012-07-18 23:59:08 +1000615.. function:: all_suffixes()
Nick Coghlan76e07702012-07-18 23:14:57 +1000616
617 Returns a combined list of strings representing all file suffixes for
Nick Coghlanc5afd422012-07-18 23:59:08 +1000618 modules recognized by the standard import machinery. This is a
Nick Coghlan76e07702012-07-18 23:14:57 +1000619 helper for code which simply needs to know if a filesystem path
Nick Coghlanc5afd422012-07-18 23:59:08 +1000620 potentially refers to a module without needing any details on the kind
621 of module (for example, :func:`inspect.getmodulename`)
Nick Coghlan76e07702012-07-18 23:14:57 +1000622
623 .. versionadded:: 3.3
624
625
Brett Cannon78246b62009-01-25 04:56:30 +0000626.. class:: BuiltinImporter
627
Brett Cannon2a922ed2009-03-09 03:35:50 +0000628 An :term:`importer` for built-in modules. All known built-in modules are
629 listed in :data:`sys.builtin_module_names`. This class implements the
Nick Coghlan8a9080f2012-08-02 21:26:03 +1000630 :class:`importlib.abc.MetaPathFinder` and
631 :class:`importlib.abc.InspectLoader` ABCs.
Brett Cannon78246b62009-01-25 04:56:30 +0000632
633 Only class methods are defined by this class to alleviate the need for
634 instantiation.
635
Brett Cannon78246b62009-01-25 04:56:30 +0000636
637.. class:: FrozenImporter
638
Brett Cannon2a922ed2009-03-09 03:35:50 +0000639 An :term:`importer` for frozen modules. This class implements the
Nick Coghlan8a9080f2012-08-02 21:26:03 +1000640 :class:`importlib.abc.MetaPathFinder` and
641 :class:`importlib.abc.InspectLoader` ABCs.
Brett Cannon78246b62009-01-25 04:56:30 +0000642
643 Only class methods are defined by this class to alleviate the need for
644 instantiation.
645
Brett Cannondebb98d2009-02-16 04:18:01 +0000646
Nick Coghlanff794862012-08-02 21:45:24 +1000647.. class:: WindowsRegistryFinder
648
649 :term:`Finder` for modules declared in the Windows registry. This class
Nick Coghlan49417742012-08-02 23:03:58 +1000650 implements the :class:`importlib.abc.Finder` ABC.
Nick Coghlanff794862012-08-02 21:45:24 +1000651
652 Only class methods are defined by this class to alleviate the need for
653 instantiation.
654
655 .. versionadded:: 3.3
656
657
Brett Cannondebb98d2009-02-16 04:18:01 +0000658.. class:: PathFinder
659
Brett Cannon1b799182012-08-17 14:08:24 -0400660 A :term:`Finder` for :data:`sys.path` and package ``__path__`` attributes.
661 This class implements the :class:`importlib.abc.MetaPathFinder` ABC.
Brett Cannondebb98d2009-02-16 04:18:01 +0000662
Brett Cannon1b799182012-08-17 14:08:24 -0400663 Only class methods are defined by this class to alleviate the need for
664 instantiation.
Brett Cannondebb98d2009-02-16 04:18:01 +0000665
Brett Cannon1b799182012-08-17 14:08:24 -0400666 .. classmethod:: find_module(fullname, path=None)
Brett Cannondebb98d2009-02-16 04:18:01 +0000667
Brett Cannon1b799182012-08-17 14:08:24 -0400668 Class method that attempts to find a :term:`loader` for the module
669 specified by *fullname* on :data:`sys.path` or, if defined, on
670 *path*. For each path entry that is searched,
671 :data:`sys.path_importer_cache` is checked. If a non-false object is
672 found then it is used as the :term:`finder` to look for the module
673 being searched for. If no entry is found in
674 :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is
675 searched for a finder for the path entry and, if found, is stored in
676 :data:`sys.path_importer_cache` along with being queried about the
677 module. If no finder is ever found then ``None`` is both stored in
678 the cache and returned.
Brett Cannond2e7b332009-02-17 02:45:03 +0000679
Brett Cannonf4dc9202012-08-10 12:21:12 -0400680 .. classmethod:: invalidate_caches()
681
Brett Cannon1b799182012-08-17 14:08:24 -0400682 Calls :meth:`importlib.abc.PathEntryFinder.invalidate_caches` on all
683 finders stored in :attr:`sys.path_importer_cache`.
Brett Cannonf4dc9202012-08-10 12:21:12 -0400684
Brett Cannond2e7b332009-02-17 02:45:03 +0000685
Brett Cannon938d44d2012-04-22 19:58:33 -0400686.. class:: FileFinder(path, \*loader_details)
687
Nick Coghlan8a9080f2012-08-02 21:26:03 +1000688 A concrete implementation of :class:`importlib.abc.PathEntryFinder` which
689 caches results from the file system.
Brett Cannon938d44d2012-04-22 19:58:33 -0400690
691 The *path* argument is the directory for which the finder is in charge of
692 searching.
693
Brett Cannonac9f2f32012-08-10 13:47:54 -0400694 The *loader_details* argument is a variable number of 2-item tuples each
695 containing a loader and a sequence of file suffixes the loader recognizes.
Brett Cannon938d44d2012-04-22 19:58:33 -0400696
697 The finder will cache the directory contents as necessary, making stat calls
698 for each module search to verify the cache is not outdated. Because cache
699 staleness relies upon the granularity of the operating system's state
700 information of the file system, there is a potential race condition of
701 searching for a module, creating a new file, and then searching for the
702 module the new file represents. If the operations happen fast enough to fit
703 within the granularity of stat calls, then the module search will fail. To
704 prevent this from happening, when you create a module dynamically, make sure
705 to call :func:`importlib.invalidate_caches`.
706
707 .. versionadded:: 3.3
708
709 .. attribute:: path
710
711 The path the finder will search in.
712
713 .. method:: find_module(fullname)
714
715 Attempt to find the loader to handle *fullname* within :attr:`path`.
716
717 .. method:: invalidate_caches()
718
719 Clear out the internal cache.
720
721 .. classmethod:: path_hook(\*loader_details)
722
723 A class method which returns a closure for use on :attr:`sys.path_hooks`.
724 An instance of :class:`FileFinder` is returned by the closure using the
725 path argument given to the closure directly and *loader_details*
726 indirectly.
727
728 If the argument to the closure is not an existing directory,
729 :exc:`ImportError` is raised.
730
731
732.. class:: SourceFileLoader(fullname, path)
733
734 A concrete implementation of :class:`importlib.abc.SourceLoader` by
735 subclassing :class:`importlib.abc.FileLoader` and providing some concrete
736 implementations of other methods.
737
738 .. versionadded:: 3.3
739
740 .. attribute:: name
741
742 The name of the module that this loader will handle.
743
744 .. attribute:: path
745
746 The path to the source file.
747
748 .. method:: is_package(fullname)
749
750 Return true if :attr:`path` appears to be for a package.
751
752 .. method:: path_stats(path)
753
754 Concrete implementation of :meth:`importlib.abc.SourceLoader.path_stats`.
755
756 .. method:: set_data(path, data)
757
758 Concrete implementation of :meth:`importlib.abc.SourceLoader.set_data`.
759
Brett Cannon938d44d2012-04-22 19:58:33 -0400760
Marc-Andre Lemburg4fe29c92012-04-25 02:31:37 +0200761.. class:: SourcelessFileLoader(fullname, path)
Brett Cannon938d44d2012-04-22 19:58:33 -0400762
763 A concrete implementation of :class:`importlib.abc.FileLoader` which can
764 import bytecode files (i.e. no source code files exist).
765
Marc-Andre Lemburg4fe29c92012-04-25 02:31:37 +0200766 Please note that direct use of bytecode files (and thus not source code
767 files) inhibits your modules from being usable by all Python
768 implementations or new versions of Python which change the bytecode
769 format.
Brett Cannon938d44d2012-04-22 19:58:33 -0400770
771 .. versionadded:: 3.3
772
773 .. attribute:: name
774
775 The name of the module the loader will handle.
776
777 .. attribute:: path
778
779 The path to the bytecode file.
780
781 .. method:: is_package(fullname)
782
783 Determines if the module is a package based on :attr:`path`.
784
785 .. method:: get_code(fullname)
786
787 Returns the code object for :attr:`name` created from :attr:`path`.
788
789 .. method:: get_source(fullname)
790
791 Returns ``None`` as bytecode files have no source when this loader is
792 used.
793
Brett Cannon938d44d2012-04-22 19:58:33 -0400794
795.. class:: ExtensionFileLoader(fullname, path)
796
797 A concrete implementation of :class:`importlib.abc.InspectLoader` for
798 extension modules.
799
800 The *fullname* argument specifies the name of the module the loader is to
801 support. The *path* argument is the path to the extension module's file.
802
803 .. versionadded:: 3.3
804
805 .. attribute:: name
806
807 Name of the module the loader supports.
808
809 .. attribute:: path
810
811 Path to the extension module.
812
Barry Warsawd7d21942012-07-29 16:36:17 -0400813 .. method:: load_module(fullname)
Brett Cannon938d44d2012-04-22 19:58:33 -0400814
Brett Cannonc0499522012-05-11 14:48:41 -0400815 Loads the extension module if and only if *fullname* is the same as
816 :attr:`name` or is ``None``.
Brett Cannon938d44d2012-04-22 19:58:33 -0400817
818 .. method:: is_package(fullname)
819
Brett Cannonac9f2f32012-08-10 13:47:54 -0400820 Returns ``True`` if the file path points to a package's ``__init__``
821 module based on :attr:`EXTENSION_SUFFIXES`.
Brett Cannon938d44d2012-04-22 19:58:33 -0400822
823 .. method:: get_code(fullname)
824
825 Returns ``None`` as extension modules lack a code object.
826
827 .. method:: get_source(fullname)
828
829 Returns ``None`` as extension modules do not have source code.
830
831
Brett Cannond2e7b332009-02-17 02:45:03 +0000832:mod:`importlib.util` -- Utility code for importers
833---------------------------------------------------
834
835.. module:: importlib.util
Brett Cannon75321e82012-03-02 11:58:25 -0500836 :synopsis: Utility code for importers
Brett Cannond2e7b332009-02-17 02:45:03 +0000837
838This module contains the various objects that help in the construction of
839an :term:`importer`.
840
Brett Cannond200bf52012-05-13 13:45:09 -0400841.. function:: resolve_name(name, package)
842
843 Resolve a relative module name to an absolute one.
844
845 If **name** has no leading dots, then **name** is simply returned. This
846 allows for usage such as
847 ``importlib.util.resolve_name('sys', __package__)`` without doing a
848 check to see if the **package** argument is needed.
849
850 :exc:`ValueError` is raised if **name** is a relative module name but
851 package is a false value (e.g. ``None`` or the empty string).
852 :exc:`ValueError` is also raised a relative name would escape its containing
853 package (e.g. requesting ``..bacon`` from within the ``spam`` package).
854
855 .. versionadded:: 3.3
856
Georg Brandl8a1caa22010-07-29 16:01:11 +0000857.. decorator:: module_for_loader
Brett Cannond2e7b332009-02-17 02:45:03 +0000858
Guido van Rossum09613542009-03-30 20:34:57 +0000859 A :term:`decorator` for a :term:`loader` method,
860 to handle selecting the proper
Brett Cannond2e7b332009-02-17 02:45:03 +0000861 module object to load with. The decorated method is expected to have a call
Brett Cannon2a922ed2009-03-09 03:35:50 +0000862 signature taking two positional arguments
863 (e.g. ``load_module(self, module)``) for which the second argument
Guido van Rossum09613542009-03-30 20:34:57 +0000864 will be the module **object** to be used by the loader.
Brett Cannonefad00d2012-04-27 17:27:14 -0400865 Note that the decorator will not work on static methods because of the
866 assumption of two arguments.
Brett Cannond2e7b332009-02-17 02:45:03 +0000867
Guido van Rossum09613542009-03-30 20:34:57 +0000868 The decorated method will take in the **name** of the module to be loaded
869 as expected for a :term:`loader`. If the module is not found in
Brett Cannon57b46f52009-03-02 14:38:26 +0000870 :data:`sys.modules` then a new one is constructed with its
Brett Cannonefad00d2012-04-27 17:27:14 -0400871 :attr:`__name__` attribute set to **name**, :attr:`__loader__` set to
872 **self**, and :attr:`__package__` set if
873 :meth:`importlib.abc.InspectLoader.is_package` is defined for **self** and
874 does not raise :exc:`ImportError` for **name**. If a new module is not
875 needed then the module found in :data:`sys.modules` will be passed into the
876 method.
877
878 If an exception is raised by the decorated method and a module was added to
Brett Cannond2e7b332009-02-17 02:45:03 +0000879 :data:`sys.modules` it will be removed to prevent a partially initialized
Brett Cannon57b46f52009-03-02 14:38:26 +0000880 module from being in left in :data:`sys.modules`. If the module was already
881 in :data:`sys.modules` then it is left alone.
Brett Cannond2e7b332009-02-17 02:45:03 +0000882
Guido van Rossum09613542009-03-30 20:34:57 +0000883 Use of this decorator handles all the details of which module object a
Brett Cannonefad00d2012-04-27 17:27:14 -0400884 loader should initialize as specified by :pep:`302` as best as possible.
885
886 .. versionchanged:: 3.3
Georg Brandl61063cc2012-06-24 22:48:30 +0200887 :attr:`__loader__` and :attr:`__package__` are automatically set
888 (when possible).
Brett Cannon57b46f52009-03-02 14:38:26 +0000889
Georg Brandl8a1caa22010-07-29 16:01:11 +0000890.. decorator:: set_loader
Brett Cannon2cf03a82009-03-10 05:17:37 +0000891
Guido van Rossum09613542009-03-30 20:34:57 +0000892 A :term:`decorator` for a :term:`loader` method,
893 to set the :attr:`__loader__`
Brett Cannon2cf03a82009-03-10 05:17:37 +0000894 attribute on loaded modules. If the attribute is already set the decorator
895 does nothing. It is assumed that the first positional argument to the
Brett Cannon75321e82012-03-02 11:58:25 -0500896 wrapped method (i.e. ``self``) is what :attr:`__loader__` should be set to.
Brett Cannon2cf03a82009-03-10 05:17:37 +0000897
Brett Cannonefad00d2012-04-27 17:27:14 -0400898 .. note::
899
900 It is recommended that :func:`module_for_loader` be used over this
901 decorator as it subsumes this functionality.
902
903
Georg Brandl8a1caa22010-07-29 16:01:11 +0000904.. decorator:: set_package
Brett Cannon57b46f52009-03-02 14:38:26 +0000905
906 A :term:`decorator` for a :term:`loader` to set the :attr:`__package__`
907 attribute on the module returned by the loader. If :attr:`__package__` is
Georg Brandl375aec22011-01-15 17:03:02 +0000908 set and has a value other than ``None`` it will not be changed.
Brett Cannon57b46f52009-03-02 14:38:26 +0000909 Note that the module returned by the loader is what has the attribute
910 set on and not the module found in :data:`sys.modules`.
Guido van Rossum09613542009-03-30 20:34:57 +0000911
Brett Cannon16248a42009-04-01 20:47:14 +0000912 Reliance on this decorator is discouraged when it is possible to set
Brett Cannon75321e82012-03-02 11:58:25 -0500913 :attr:`__package__` before importing. By
914 setting it beforehand the code for the module is executed with the
915 attribute set and thus can be used by global level code during
Brett Cannon16248a42009-04-01 20:47:14 +0000916 initialization.
917
Brett Cannonefad00d2012-04-27 17:27:14 -0400918 .. note::
919
920 It is recommended that :func:`module_for_loader` be used over this
921 decorator as it subsumes this functionality.