[Python-checkins] python/dist/src/Doc/api utilities.tex,1.16,1.17

[tim_one at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/api
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv22280/doc/api

Modified Files:
	utilities.tex 
Log Message:
PyImport_ImportModule, PyImport_ImportModuleEx, PyImport_ExecCodeModule:
in failure cases, incompletely initalized module objects are no longer
left behind in sys.modules.


Index: utilities.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/utilities.tex,v
retrieving revision 1.16
retrieving revision 1.17
diff -C2 -d -r1.16 -r1.17
*** utilities.tex	10 Jul 2004 22:20:17 -0000	1.16
--- utilities.tex	2 Aug 2004 03:46:45 -0000	1.17
***************
*** 106,111 ****
    \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).
    \withsubitem{(in module sys)}{\ttindex{modules}}
  \end{cfuncdesc}
--- 106,114 ----
    \withsubitem{(package variable)}{\ttindex{__all__}}loaded.)  Return
    a new reference to the imported module, or \NULL{} with an exception
!   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}
***************
*** 119,127 ****
  
    The return value is a new reference to the imported module or
!   top-level package, or \NULL{} with an exception set on failure (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.
  \end{cfuncdesc}
  
--- 122,132 ----
  
    The return value is a new reference to the imported module or
!   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}
  
***************
*** 162,170 ****
    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
    form \code{package.module}, any package structures not already
    created will still not be created.
  \end{cfuncdesc}
  
--- 167,188 ----
    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.  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}
  
***************
*** 805,815 ****
  
      \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 
      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 
      is \NULL, the length is ignored and \code{None} is returned.
  
--- 823,833 ----
  
      \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
      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
      is \NULL, the length is ignored and \code{None} is returned.