Merged revisions 76286-76287,76289-76294,76296-76299,76301-76305,76307,76310-76311,76313-76322 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r76286 | nick.coghlan | 2009-11-15 17:30:34 +1000 (Sun, 15 Nov 2009) | 1 line

  Issue #6816: expose the zipfile and directory execution mechanism to Python code via the runpy module. Also consolidated some script execution functionality in the test harness into a helper module and removed some implementation details from the runpy module documentation.
........
  r76321 | nick.coghlan | 2009-11-16 13:55:51 +1000 (Mon, 16 Nov 2009) | 1 line

  Account for another cache when hunting ref leaks
........
  r76322 | nick.coghlan | 2009-11-16 13:57:32 +1000 (Mon, 16 Nov 2009) | 1 line

  Allow for backslashes in file paths passed to the regex engine
........

1 files changed, 96 insertions, 43 deletions

diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst
index a5bfb8d..55e845d 100644
--- a/Doc/library/runpy.rst
+++ b/Doc/library/runpy.rst
@@ -7,70 +7,122 @@
 
 
 The :mod:`runpy` module is used to locate and run Python modules without
-importing them first. Its main use is to implement the :option:`-m` command line
-switch that allows scripts to be located using the Python module namespace
-rather than the filesystem.
+importing them first. Its main use is to implement the :option:`-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::
-
-   del sys.argv[0]  # Remove the runpy module from the arguments
-   run_module(sys.argv[0], run_name="__main__", alter_sys=True)
-
-The :mod:`runpy` module provides a single function:
+The :mod:`runpy` module provides two functions:
 
 
 .. function:: run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)
 
-   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.
+   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.
 
-   If the supplied module name refers to a package rather than a normal module,
-   then that package is imported and the ``__main__`` submodule within that
-   package is then executed and the resulting module globals dictionary returned.
+   If the supplied module name refers to a package rather than a normal
+   module, then that package is imported and the ``__main__`` submodule within
+   that package is then executed and the resulting module globals dictionary
+   returned.
 
-   The optional dictionary argument *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 ``run_module``
-   function.
+   The optional dictionary argument *init_globals* may be used to pre-populate
+   the module's 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 :func:`run_module`.
 
-   The special global variables ``__name__``, ``__file__``, ``__loader__``,
-   ``__builtins__`` and ``__package__`` are set in the globals dictionary before
-   the module code is executed.
+   The special global variables ``__name__``, ``__file__``, ``__loader__``
+   and ``__package__`` are set in the globals dictionary before the module
+   code is executed (Note that this is a minimal set of variables - other
+   variables may be set implicitly as an interpreter implementation detail).
 
-   ``__name__`` is set to *run_name* if this optional argument is supplied, to
-   ``mod_name + '.__main__'`` if the named module is a package and to the
-   *mod_name* argument otherwise.
+   ``__name__`` is set to *run_name* if this optional argument is not
+   :const:`None`, to ``mod_name + '.__main__'`` if the named module is a
+   package and to the *mod_name* argument otherwise.
 
-   ``__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).
+   ``__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 `:const:`None`.
 
-   ``__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 ``None``.
+   ``__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).
 
-   ``__builtins__`` is automatically initialised with a reference to the top level
-   namespace of the :mod:`builtins` module.
+   ``__package__`` is set to *mod_name* if the named module is a package and
+   to ``mod_name.rpartition('.')[0]`` otherwise.
 
-   ``__package__`` is set to *mod_name* if the named module is a package and to
-   ``mod_name.rpartition('.')[0]`` otherwise.
-
-   If the argument *alter_sys* is supplied and evaluates to ``True``, then
-   ``sys.argv[0]`` is updated with the value of ``__file__`` and
+   If the argument *alter_sys* is supplied and evaluates to :const:`True`,
+   then ``sys.argv[0]`` is updated with the value of ``__file__`` and
    ``sys.modules[__name__]`` is updated with a temporary module object for the
    module being executed. Both ``sys.argv[0]`` and ``sys.modules[__name__]``
    are restored to their original values before the function returns.
 
-   Note that this manipulation of :mod:`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 :mod:`sys` module be left alone when invoking this
-   function from threaded code.
+   Note that this manipulation of :mod:`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 :mod:`sys` module be left alone when
+   invoking this function from threaded code.
 
 
    .. versionchanged:: 3.1
-         Added ability to execute packages by looking for a ``__main__`` submodule
+         Added ability to execute packages by looking for a ``__main__``
+         submodule
+
+
+.. function:: run_path(file_path, init_globals=None, run_name=None)
+
+   Execute the code at the named filesystem location and return the resulting
+   module globals dictionary. As with a script name supplied to the CPython
+   command line, the supplied path may refer to a Python source file, a
+   compiled bytecode file or a valid sys.path entry containing a ``__main__``
+   module (e.g. a zipfile containing a top-level ``__main__.py`` file).
+
+   For a simple script, the specified code is simply executed in a fresh
+   module namespace. For a valid sys.path entry (typically a zipfile or
+   directory), the entry is first added to the beginning of ``sys.path``. The
+   function then looks for and executes a :mod:`__main__` module using the
+   updated path. Note that there is no special protection against invoking
+   an existing :mod:`__main__` entry located elsewhere on ``sys.path`` if
+   there is no such module at the specified location.
+
+   The optional dictionary argument *init_globals* may be used to pre-populate
+   the module's 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 :func:`run_path`.
+
+   The special global variables ``__name__``, ``__file__``, ``__loader__``
+   and ``__package__`` are set in the globals dictionary before the module
+   code is executed (Note that this is a minimal set of variables - other
+   variables may be set implicitly as an interpreter implementation detail).
+
+   ``__name__`` is set to *run_name* if this optional argument is not
+   :const:`None` and to ``'<run_path>'`` otherwise.
+
+   ``__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 :const:`None`. For a simple script, this will be set to ``file_path``.
+
+   ``__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). For a simple script, this will be set to :const:`None`.
+
+   ``__package__`` is set to ``__name__.rpartition('.')[0]``.
+
+   A number of alterations are also made to the :mod:`sys` module. Firstly,
+   ``sys.path`` may be altered as described above. ``sys.argv[0]`` is updated
+   with the value of ``file_path`` and ``sys.modules[__name__]`` is updated
+   with a temporary module object for the module being executed. All
+   modifications to items in :mod:`sys` are reverted before the function
+   returns.
+
+   Note that, unlike :func:`run_module`, the alterations made to :mod:`sys`
+   are not optional in this function as these adjustments are essential to
+   allowing the execution of sys.path entries. As the thread safety
+   limitations still apply, use of this function in threaded code should be
+   either serialised with the import lock or delegated to a separate process.
 
+   .. versionadded:: 3.2
 
 .. seealso::
 
@@ -80,3 +132,4 @@ The :mod:`runpy` module provides a single function:
    :pep:`366` - Main module explicit relative imports
       PEP written and implemented by Nick Coghlan.
 
+   :ref:`using-on-general` - CPython command line details