Add documentation for PEP 338

Doc/Makefile.deps

@@ -126,6 +126,7 @@ LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
 	lib/libwarnings.tex \
 	lib/libimp.tex \
 	lib/libzipimport.tex \
+	lib/librunpy.tex \
 	lib/libpkgutil.tex \
 	lib/libparser.tex \
 	lib/libbltin.tex \

Doc/lib/lib.tex

@@ -394,6 +394,7 @@ and how to embed it in other applications.
 \input{libzipimport}
 \input{libpkgutil}
 \input{libmodulefinder}
+\input{librunpy}
 
 
 % =============

Doc/lib/librunpy.tex

+\section{\module{runpy} ---
+         Locating and executing Python modules.}
+
+\declaremodule{standard}{runpy}		% standard library, in Python
+
+\moduleauthor{Nick Coghlan}{ncoghlan@gmail.com}
+
+\modulesynopsis{Locate and execute Python modules as scripts}
+
+\versionadded{2.5}
+
+The \module{runpy} module is used to locate and run Python modules
+without importing them first. It's main use is to implement the
+\programopt{-m} command line switch that allows scripts to be located
+using the Python module namespace rather than the filesystem.
+
+When executed as a script, the module effectively operates as follows:
+\begin{verbatim}
+    del sys.argv[0]  # Remove the runpy module from the arguments
+    run_module(sys.argv[0], run_name="__main__", alter_sys=True)
+\end{verbatim}
+
+The \module{runpy} module provides a single function:
+
+\begin{funcdesc}{run_module}{mod_name\optional{, init_globals}
+\optional{, run_name}\optional{, alter_sys}}
+Execute the code of the specified module and return the resulting
+module globals dictionary. The module's code is first located using
+the standard import mechanism (refer to PEP 302 for details) and
+then executed in a fresh module namespace.
+
+The optional dictionary argument \var{init_globals} may be used to
+pre-populate the globals dictionary before the code is executed.
+The supplied dictionary will not be modified. If any of the special
+global variables below are defined in the supplied dictionary, those
+definitions are overridden by the \code{run_module} function.
+
+The special global variables \code{__name__}, \code{__file__},
+\code{__loader__} and \code{__builtins__} are set in the globals
+dictionary before the module code is executed.
+
+\code{__name__} is set to \var{run_name} if this optional argument is
+supplied, and the \var{mod_name} argument otherwise.
+
+\code{__loader__} is set to the PEP 302 module loader used to retrieve
+the code for the module (This loader may be a wrapper around the
+standard import mechanism).
+
+\code{__file__} is set to the name provided by the module loader. If
+the loader does not make filename information available, this
+variable is set to \code{None}.
+
+\code{__builtins__} is automatically initialised with a reference to
+the top level namespace of the \module{__builtin__} module.
+
+If the argument \var{alter_sys} is supplied and evaluates to
+\code{True}, then \code{sys.argv[0]} is updated with the value of
+\code{__file__} and \code{sys.modules[__name__]} is updated with a
+temporary module object for the module being executed. Both
+\code{sys.argv[0]} and \code{sys.modules[__name__]} are restored to
+their original values before the function returns.
+
+Note that this manipulation of \module{sys} is not thread-safe. Other
+threads may see the partially initialised module, as well as the
+altered list of arguments. It is recommended that the \module{sys}
+module be left alone when invoking this function from threaded code.
+\end{funcdesc}
+
+\begin{seealso}
+
+\seepep{338}{Executing modules as scripts}{PEP written and 
+implemented by Nick Coghlan.}
+
+\end{seealso}