Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(44693)

Side by Side Diff: Doc/reference/import.rst

Issue 23014: Don't have importlib.abc.Loader.create_module() be optional
Patch Set: Created 4 years, 9 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
OLDNEW
1 1
2 .. _importsystem: 2 .. _importsystem:
3 3
4 ***************** 4 *****************
5 The import system 5 The import system
6 ***************** 6 *****************
7 7
8 .. index:: single: import machinery 8 .. index:: single: import machinery
9 9
10 Python code in one :term:`module` gains access to the code in another module 10 Python code in one :term:`module` gains access to the code in another module
(...skipping 321 matching lines...) Expand 10 before | Expand all | Expand 10 after
332 332
333 Loading 333 Loading
334 ======= 334 =======
335 335
336 If and when a module spec is found, the import machinery will use it (and 336 If and when a module spec is found, the import machinery will use it (and
337 the loader it contains) when loading the module. Here is an approximation 337 the loader it contains) when loading the module. Here is an approximation
338 of what happens during the loading portion of import:: 338 of what happens during the loading portion of import::
339 339
340 module = None 340 module = None
341 if spec.loader is not None and hasattr(spec.loader, 'create_module'): 341 if spec.loader is not None and hasattr(spec.loader, 'create_module'):
342 # It is assumed 'exec_module' will also be defined on the loader.
342 module = spec.loader.create_module(spec) 343 module = spec.loader.create_module(spec)
343 if module is None: 344 if module is None:
344 module = ModuleType(spec.name) 345 module = ModuleType(spec.name)
345 # The import-related module attributes get set here: 346 # The import-related module attributes get set here:
346 _init_module_attrs(spec, module) 347 _init_module_attrs(spec, module)
347 348
348 if spec.loader is None: 349 if spec.loader is None:
349 if spec.submodule_search_locations is not None: 350 if spec.submodule_search_locations is not None:
350 # namespace package 351 # namespace package
351 sys.modules[spec.name] = module 352 sys.modules[spec.name] = module
(...skipping 68 matching lines...) Expand 10 before | Expand all | Expand 10 after
420 :meth:`~importlib.abc.Loader.exec_module` will be propagated. 421 :meth:`~importlib.abc.Loader.exec_module` will be propagated.
421 422
422 In many cases, the finder and loader can be the same object; in such cases the 423 In many cases, the finder and loader can be the same object; in such cases the
423 :meth:`~importlib.abc.MetaPathFinder.find_spec` method would just return a 424 :meth:`~importlib.abc.MetaPathFinder.find_spec` method would just return a
424 spec with the loader set to ``self``. 425 spec with the loader set to ``self``.
425 426
426 Module loaders may opt in to creating the module object during loading 427 Module loaders may opt in to creating the module object during loading
427 by implementing a :meth:`~importlib.abc.Loader.create_module` method. 428 by implementing a :meth:`~importlib.abc.Loader.create_module` method.
428 It takes one argument, the module spec, and returns the new module object 429 It takes one argument, the module spec, and returns the new module object
429 to use during loading. ``create_module()`` does not need to set any attributes 430 to use during loading. ``create_module()`` does not need to set any attributes
430 on the module object. If the loader does not define ``create_module()``, the 431 on the module object. If the method returns ``None``, the
431 import machinery will create the new module itself. 432 import machinery will create the new module itself.
432 433
433 .. versionadded:: 3.4 434 .. versionadded:: 3.4
434 The create_module() method of loaders. 435 The create_module() method of loaders.
435 436
436 .. versionchanged:: 3.4 437 .. versionchanged:: 3.4
437 The :meth:`~importlib.abc.Loader.load_module` method was replaced by 438 The :meth:`~importlib.abc.Loader.load_module` method was replaced by
438 :meth:`~importlib.abc.Loader.exec_module` and the import 439 :meth:`~importlib.abc.Loader.exec_module` and the import
439 machinery assumed all the boilerplate responsibilities of loading. 440 machinery assumed all the boilerplate responsibilities of loading.
440 441
(...skipping 13 matching lines...) Expand all
454 must create a new module object and add it to :data:`sys.modules`. 455 must create a new module object and add it to :data:`sys.modules`.
455 456
456 * The module *must* exist in :data:`sys.modules` before the loader 457 * The module *must* exist in :data:`sys.modules` before the loader
457 executes the module code, to prevent unbounded recursion or multiple 458 executes the module code, to prevent unbounded recursion or multiple
458 loading. 459 loading.
459 460
460 * If loading fails, the loader must remove any modules it has inserted 461 * If loading fails, the loader must remove any modules it has inserted
461 into :data:`sys.modules`, but it must remove **only** the failing 462 into :data:`sys.modules`, but it must remove **only** the failing
462 module(s), and only if the loader itself has loaded the module(s) 463 module(s), and only if the loader itself has loaded the module(s)
463 explicitly. 464 explicitly.
465
466 .. versionchanged:: 3.5
467 A :class:`DeprecationWarning` is raised when ``exec_module()`` is defined but
berkerpeksag 2014/12/12 20:07:45 Identation should be 3 space.
berkerpeksag 2014/12/12 20:07:45 :exc:`DeprecationWarning`
brett.cannon 2015/01/09 17:28:56 Done.
brett.cannon 2015/01/09 17:28:56 Done.
468 ``create_module()`` is not. Starting in Python 3.6 it will be an error to not
469 define ``create_module()`` on a loader attached to a ModuleSpec.
464 470
465 Module spec 471 Module spec
466 ----------- 472 -----------
467 473
468 The import machinery uses a variety of information about each module 474 The import machinery uses a variety of information about each module
469 during import, especially before loading. Most of the information is 475 during import, especially before loading. Most of the information is
470 common to all modules. The purpose of a module's spec is to encapsulate 476 common to all modules. The purpose of a module's spec is to encapsulate
471 this import-related information on a per-module basis. 477 this import-related information on a per-module basis.
472 478
473 Using a spec during import allows state to be transferred between import 479 Using a spec during import allows state to be transferred between import
(...skipping 470 matching lines...) Expand 10 before | Expand all | Expand 10 after
944 directly. Instead, it gets the module object by looking the module name up 950 directly. Instead, it gets the module object by looking the module name up
945 in :data:`sys.modules`. The indirect effect of this is that an imported 951 in :data:`sys.modules`. The indirect effect of this is that an imported
946 module may replace itself in :data:`sys.modules`. This is 952 module may replace itself in :data:`sys.modules`. This is
947 implementation-specific behavior that is not guaranteed to work in other 953 implementation-specific behavior that is not guaranteed to work in other
948 Python implementations. 954 Python implementations.
949 955
950 .. [#fnpic] In legacy code, it is possible to find instances of 956 .. [#fnpic] In legacy code, it is possible to find instances of
951 :class:`imp.NullImporter` in the :data:`sys.path_importer_cache`. It 957 :class:`imp.NullImporter` in the :data:`sys.path_importer_cache`. It
952 is recommended that code be changed to use ``None`` instead. See 958 is recommended that code be changed to use ``None`` instead. See
953 :ref:`portingpythoncode` for more details. 959 :ref:`portingpythoncode` for more details.
OLDNEW

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+