[Python-checkins] peps: PEP 489 updates from Petr Viktorin.

[berker.peksag]

https://hg.python.org/peps/rev/342a331682e5
changeset:   5868:342a331682e5
user:        Berker Peksag <berker.peksag at gmail.com>
date:        Thu May 21 15:48:38 2015 +0300
summary:
  PEP 489 updates from Petr Viktorin.

- Don't allow execution slots for non-module subclasses
- Remove misleading reason for PyModuleDef_Init
- Clarify that sys.modules is not checked between execution steps
- Add a Backwards Compatibility summary
- Heading level fix, Typo fix

files:
  pep-0489.txt |  52 +++++++++++++++++++++++++++++----------
  1 files changed, 38 insertions(+), 14 deletions(-)


diff --git a/pep-0489.txt b/pep-0489.txt
--- a/pep-0489.txt
+++ b/pep-0489.txt
@@ -164,11 +164,10 @@
 When using multi-phase initialization, the *m_name* field of PyModuleDef will
 not be used during importing; the module name will be taken from the ModuleSpec.
 
-To prevent crashes when the module is loaded in older versions of Python,
-the PyModuleDef object must be initialized using the newly added
-PyModuleDef_Init function. This sets the object type (which cannot be done
-statically on certain compilers), refcount, and internal bookkeeping data
-(m_index).
+Before it is returned from PyInit_*, the PyModuleDef object must be initialized
+using the newly added PyModuleDef_Init function. This sets the object type
+(which cannot be done statically on certain compilers), refcount, and internal
+bookkeeping data (m_index).
 For example, an extension module "example" would be exported as::
 
     static PyModuleDef example_def = {...}
@@ -353,7 +352,9 @@
 types.ModuleType. Any type can be used, as long as it supports setting and
 getting attributes, including at least the import-related attributes.
 However, only ModuleType instances support module-specific functionality
-such as per-module state.
+such as per-module state and processing of execution slots.
+If something other than a ModuleType subclass is returned, no execution slots
+may be defined; if any are, a SystemError is raised.
 
 Note that when this function is called, the module's entry in sys.modules
 is not populated yet. Attempting to import the same module again
@@ -398,7 +399,7 @@
 
 The execution phase is done on the PyModuleDef associated with the module
 object. For objects that are not a subclass of PyModule_Type (for which
-PyModule_GetDef whoud fail), the execution phase is skipped.
+PyModule_GetDef would fail), the execution phase is skipped.
 
 Execution slots may be specified multiple times, and are processed in the order
 they appear in the slots array.
@@ -409,7 +410,7 @@
 
 
 Pre-Execution steps
--------------------
+...................
 
 Before processing the execution slots, per-module state is allocated for the
 module. From this point on, per-module state is accessible through
@@ -427,14 +428,17 @@
 setting the module's initial attributes.
 The "module" argument receives the module object to initialize.
 
-If PyModuleExec replaces the module's entry in sys.modules,
-the new object will be used and returned by importlib machinery.
-(This mirrors the behavior of Python modules. Note that implementing
-Py_mod_create is usually a better solution for the use cases this serves.)
-
 The function must return ``0`` on success, or, on error, set an exception and
 return ``-1``.
 
+If PyModuleExec replaces the module's entry in sys.modules, the new object
+will be used and returned by importlib machinery after all execution slots
+are processed. This is a feature of the import machinery itself.
+The slots themselves are all processed using the module returned from the
+creation phase; sys.modules is not consulted during the execution phase.
+(Note that for extension modules, implementing Py_mod_create is usually
+a better solution for using custom module objects.)
+
 
 Legacy Init
 -----------
@@ -694,7 +698,7 @@
 
 
 Summary of API Changes and Additions
-------------------------------------
+====================================
 
 New functions:
 
@@ -728,6 +732,26 @@
 be replaced by backwards-compatible shims.
 
 
+Backwards Compatibility
+-----------------------
+
+Existing modules will continue to be source- and binary-compatible with new
+versions of Python.
+Modules that use multi-phase initialization will not be compatible with
+versions of Python that do not implement this PEP.
+
+The functions ``init_builtin`` and ``load_dynamic`` will be removed from
+the ``_imp`` module (but not from the ``imp`` module).
+
+All changed loaders (``BuiltinImporter`` and ``ExtensionFileLoader``) will
+remain backwards-compatible; the ``load_module`` method will be replaced by
+a shim.
+
+Internal functions of Python/import.c and Python/importdl.c will be removed.
+(Specifically, these are ``_PyImport_GetDynLoadFunc``,
+``_PyImport_GetDynLoadWindows``, and ``_PyImport_LoadDynamicModule``.)
+
+
 Possible Future Extensions
 ==========================
 

-- 
Repository URL: https://hg.python.org/peps