75 lines
3.0 KiB
TeX
75 lines
3.0 KiB
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}
|