From cfd575d39898d0b8331c8211f4501d49ac6a4f7f Mon Sep 17 00:00:00 2001
From: Tim Peters <tim.peters@gmail.com>
Date: Mon, 2 Aug 2004 03:46:45 +0000
Subject: [PATCH] PyImport_ImportModule, PyImport_ImportModuleEx,
 PyImport_ExecCodeModule: in failure cases, incompletely initalized module
 objects are no longer left behind in sys.modules.

---
 Doc/api/utilities.tex | 38 ++++++++++++++++++++++++++++----------
 1 file changed, 28 insertions(+), 10 deletions(-)

diff --git a/Doc/api/utilities.tex b/Doc/api/utilities.tex
index 0d71cd90073..09d2cb33d66 100644
--- a/Doc/api/utilities.tex
+++ b/Doc/api/utilities.tex
@@ -105,8 +105,11 @@ values from C values.
   are \index{package variable!\code{__all__}}
   \withsubitem{(package variable)}{\ttindex{__all__}}loaded.)  Return
   a new reference to the imported module, or \NULL{} with an exception
-  set on failure (the module may still be created in this case ---
-  examine \code{sys.modules} to find out).
+  set on failure.  Before Python 2.4, the module may still be created in
+  the failure case --- examine \code{sys.modules} to find out.  Starting
+  with Python 2.4, a failing import of a module no longer leaves the
+  module in \code{sys.modules}.
+  \versionchanged[failing imports remove incomplete module objects]{2.4}
   \withsubitem{(in module sys)}{\ttindex{modules}}
 \end{cfuncdesc}
 
@@ -118,11 +121,13 @@ values from C values.
   \function{__import__()} function calls this function directly.
 
   The return value is a new reference to the imported module or
-  top-level package, or \NULL{} with an exception set on failure (the
+  top-level package, or \NULL{} with an exception set on failure (before
+  Python 2.4, the
   module may still be created in this case).  Like for
   \function{__import__()}, the return value when a submodule of a
   package was requested is normally the top-level package, unless a
   non-empty \var{fromlist} was given.
+  \versionchanged[failing imports remove incomplete module objects]{2.4}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyImport_Import}{PyObject *name}
@@ -161,11 +166,24 @@ values from C values.
   a code object read from a Python bytecode file or obtained from the
   built-in function \function{compile()}\bifuncindex{compile}, load
   the module.  Return a new reference to the module object, or \NULL{}
-  with an exception set if an error occurred (the module may still be
-  created in this case).  This function would reload the module if it
-  was already imported.  If \var{name} points to a dotted name of the
+  with an exception set if an error occurred.  Before Python 2.4, the module
+  could still be created in error cases.  Starting with Python 2.4,
+  \var{name} is removed from \code{sys.modules} in error cases, and even
+  if \var{name} was already in \code{sys.modules} on entry to
+  \cfunction{PyImport_ExecCodeModule()}.  Leaving incompletely initialized
+  modules in \code{sys.modules} is dangerous, as imports of such modules
+  have no way to know that the module object is an unknown (and probably
+  damaged with respect to the module author's intents) state.
+
+  This function will reload the module if it was already imported.  See
+  \cfunction{PyImport_ReloadModule()}
+
+  If \var{name} points to a dotted name of the
   form \code{package.module}, any package structures not already
   created will still not be created.
+
+  \versionchanged[\var{name} is removed from \code{sys.modules} in error cases]{2.4}
+
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{}
@@ -804,13 +822,13 @@ PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
     Same as \samp{s\#}.
 
     \item[\samp{u} (Unicode string) {[Py_UNICODE *]}]
-    Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) 
-    data to a Python Unicode object.  If the Unicode buffer pointer 
+    Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4)
+    data to a Python Unicode object.  If the Unicode buffer pointer
     is \NULL, \code{None} is returned.
 
     \item[\samp{u\#} (Unicode string) {[Py_UNICODE *, int]}]
-    Convert a Unicode (UCS-2 or UCS-4) data buffer and its length 
-    to a Python Unicode object.   If the Unicode buffer pointer 
+    Convert a Unicode (UCS-2 or UCS-4) data buffer and its length
+    to a Python Unicode object.   If the Unicode buffer pointer
     is \NULL, the length is ignored and \code{None} is returned.
 
     \item[\samp{i} (integer) {[int]}]