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

Side by Side Diff: Doc/library/importlib.rst

Issue 23014: Don't have importlib.abc.Loader.create_module() be optional
Patch Set: Created 4 years, 5 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
« no previous file with comments | « no previous file | Doc/reference/import.rst » ('j') | Doc/reference/import.rst » ('J')
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :mod:`importlib` -- The implementation of :keyword:`import` 1 :mod:`importlib` -- The implementation of :keyword:`import`
2 =========================================================== 2 ===========================================================
3 3
4 .. module:: importlib 4 .. module:: importlib
5 :synopsis: The implementation of the import machinery. 5 :synopsis: The implementation of the import machinery.
6 6
7 .. moduleauthor:: Brett Cannon <brett@python.org> 7 .. moduleauthor:: Brett Cannon <brett@python.org>
8 .. sectionauthor:: Brett Cannon <brett@python.org> 8 .. sectionauthor:: Brett Cannon <brett@python.org>
9 9
10 .. versionadded:: 3.1 10 .. versionadded:: 3.1
(...skipping 329 matching lines...) Expand 10 before | Expand all | Expand 10 after
340 when invalidating the caches of all cached finders. 340 when invalidating the caches of all cached finders.
341 341
342 342
343 .. class:: Loader 343 .. class:: Loader
344 344
345 An abstract base class for a :term:`loader`. 345 An abstract base class for a :term:`loader`.
346 See :pep:`302` for the exact definition for a loader. 346 See :pep:`302` for the exact definition for a loader.
347 347
348 .. method:: create_module(spec) 348 .. method:: create_module(spec)
349 349
350 An optional method that returns the module object to use when 350 A method that returns the module object to use when
351 importing a module. create_module() may also return ``None``, 351 importing a module. This method may return ``None``,
352 indicating that the default module creation should take place 352 indicating that default module creation semantics should take place.
353 instead.
354 353
355 .. versionadded:: 3.4 354 .. versionadded:: 3.4
355
356 .. versionchanged:: 3.5
357 Starting in Python 3.6, this method wil not optional when
berkerpeksag 2014/12/12 20:07:45 wil -> will
eric.snow 2014/12/16 03:42:16 s/wil not/will not be/
brett.cannon 2015/01/09 17:28:56 Done.
brett.cannon 2015/01/09 17:28:56 Done.
358 :meth:`exec_module` is defined.
356 359
357 .. method:: exec_module(module) 360 .. method:: exec_module(module)
358 361
359 An abstract method that executes the module in its own namespace 362 An abstract method that executes the module in its own namespace
360 when a module is imported or reloaded. The module should already 363 when a module is imported or reloaded. The module should already
361 be initialized when exec_module() is called. 364 be initialized when exec_module() is called.
362 365
363 .. versionadded:: 3.4 366 .. versionadded:: 3.4
364 367
365 .. method:: load_module(fullname) 368 .. method:: load_module(fullname)
(...skipping 44 matching lines...) Expand 10 before | Expand all | Expand 10 after
410 When :meth:`exec_module` is available then backwards-compatible 413 When :meth:`exec_module` is available then backwards-compatible
411 functionality is provided. 414 functionality is provided.
412 415
413 .. versionchanged:: 3.4 416 .. versionchanged:: 3.4
414 Raise :exc:`ImportError` when called instead of 417 Raise :exc:`ImportError` when called instead of
415 :exc:`NotImplementedError`. Functionality provided when 418 :exc:`NotImplementedError`. Functionality provided when
416 :meth:`exec_module` is available. 419 :meth:`exec_module` is available.
417 420
418 .. deprecated:: 3.4 421 .. deprecated:: 3.4
419 The recommended API for loading a module is :meth:`exec_module` 422 The recommended API for loading a module is :meth:`exec_module`
420 (and optionally :meth:`create_module`). Loaders should implement 423 (and :meth:`create_module`). Loaders should implement
421 it instead of load_module(). The import machinery takes care of 424 it instead of load_module(). The import machinery takes care of
422 all the other responsibilities of load_module() when exec_module() 425 all the other responsibilities of load_module() when exec_module()
423 is implemented. 426 is implemented.
424 427
425 .. method:: module_repr(module) 428 .. method:: module_repr(module)
426 429
427 A legacy method which when implemented calculates and returns the 430 A legacy method which when implemented calculates and returns the
428 given module's repr, as a string. The module type's default repr() will 431 given module's repr, as a string. The module type's default repr() will
429 use the result of this method as appropriate. 432 use the result of this method as appropriate.
430 433
(...skipping 698 matching lines...) Expand 10 before | Expand all | Expand 10 after
1129 1132
1130 If **name** is for a submodule (contains a dot), the parent module is 1133 If **name** is for a submodule (contains a dot), the parent module is
1131 automatically imported. 1134 automatically imported.
1132 1135
1133 **name** and **package** work the same as for :func:`import_module`. 1136 **name** and **package** work the same as for :func:`import_module`.
1134 1137
1135 .. versionadded:: 3.4 1138 .. versionadded:: 3.4
1136 1139
1137 .. function:: module_from_spec(spec) 1140 .. function:: module_from_spec(spec)
1138 1141
1139 Create a new module based on **spec**. 1142 Create a new module based on **spec** and ``spec.loader.create_module()``.
1140 1143
1141 If the module object is from ``spec.loader.create_module()``, then any 1144 If ``spec.loader.create_module()`` does not return None, then any
berkerpeksag 2014/12/12 20:07:45 None -> ``None``
brett.cannon 2015/01/09 17:28:56 Done.
1142 pre-existing attributes will not be reset. Also, no :exc:`AttributeError` 1145 pre-existing attributes will not be reset. Also, no :exc:`AttributeError`
1143 will be raised if triggered while accessing **spec** or setting an attribute 1146 will be raised if triggered while accessing **spec** or setting an attribute
1144 on the module. 1147 on the module.
1145 1148
1146 This function is preferred over using :class:`types.ModuleType` to create a 1149 This function is preferred over using :class:`types.ModuleType` to create a
1147 new module as **spec** is used to set as many import-controlled attributes on 1150 new module as **spec** is used to set as many import-controlled attributes on
1148 the module as possible. 1151 the module as possible.
1149 1152
1150 .. versionadded:: 3.5 1153 .. versionadded:: 3.5
1151 1154
(...skipping 75 matching lines...) Expand 10 before | Expand all | Expand 10 after
1227 module will be file-based. 1230 module will be file-based.
1228 1231
1229 .. versionadded:: 3.4 1232 .. versionadded:: 3.4
1230 1233
1231 .. class:: LazyLoader(loader) 1234 .. class:: LazyLoader(loader)
1232 1235
1233 A class which postpones the execution of the loader of a module until the 1236 A class which postpones the execution of the loader of a module until the
1234 module has an attribute accessed. 1237 module has an attribute accessed.
1235 1238
1236 This class **only** works with loaders that define 1239 This class **only** works with loaders that define
1237 :meth:`importlib.abc.Loader.exec_module` as control over what module type 1240 :meth:`~importlib.abc.Loader.exec_module` as control over what module type
1238 is used for the module is required. For the same reasons, the loader 1241 is used for the module is required. For those same reasons, the loader's
1239 **cannot** define :meth:`importlib.abc.Loader.create_module`. Finally, 1242 :meth:`~importlib.abc.Loader.create_module` method will be ignored (i.e., the
1243 loader's method should only return ``None``). Finally,
1240 modules which substitute the object placed into :attr:`sys.modules` will 1244 modules which substitute the object placed into :attr:`sys.modules` will
1241 not work as there is no way to properly replace the module references 1245 not work as there is no way to properly replace the module references
1242 throughout the interpreter safely; :exc:`ValueError` is raised if such a 1246 throughout the interpreter safely; :exc:`ValueError` is raised if such a
1243 substitution is detected. 1247 substitution is detected.
1244 1248
1245 .. note:: 1249 .. note::
1246 For projects where startup time is critical, this class allows for 1250 For projects where startup time is critical, this class allows for
1247 potentially minimizing the cost of loading a module if it is never used. 1251 potentially minimizing the cost of loading a module if it is never used.
1248 For projects where startup time is not essential then use of this class is 1252 For projects where startup time is not essential then use of this class is
1249 **heavily** discouraged due to error messages created during loading being 1253 **heavily** discouraged due to error messages created during loading being
1250 postponed and thus occurring out of context. 1254 postponed and thus occurring out of context.
1251 1255
1252 .. versionadded:: 3.5 1256 .. versionadded:: 3.5
1253 1257
1254 .. classmethod:: factory(loader) 1258 .. classmethod:: factory(loader)
1255 1259
1256 A static method which returns a callable that creates a lazy loader. This 1260 A static method which returns a callable that creates a lazy loader. This
1257 is meant to be used in situations where the loader is passed by class 1261 is meant to be used in situations where the loader is passed by class
1258 instead of by instance. 1262 instead of by instance.
1259 :: 1263 ::
1260 1264
1261 suffixes = importlib.machinery.SOURCE_SUFFIXES 1265 suffixes = importlib.machinery.SOURCE_SUFFIXES
1262 loader = importlib.machinery.SourceFileLoader 1266 loader = importlib.machinery.SourceFileLoader
1263 lazy_loader = importlib.util.LazyLoader.factory(loader) 1267 lazy_loader = importlib.util.LazyLoader.factory(loader)
1264 finder = importlib.machinery.FileFinder(path, [(lazy_loader, suffixes)]) 1268 finder = importlib.machinery.FileFinder(path, [(lazy_loader, suffixes)])
OLDNEW
« no previous file with comments | « no previous file | Doc/reference/import.rst » ('j') | Doc/reference/import.rst » ('J')

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