PEP 3147

5 files changed, 72 insertions, 9 deletions

diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst
index 71c9d83..de03f6e 100644
--- a/Doc/c-api/import.rst
+++ b/Doc/c-api/import.rst
@@ -124,12 +124,24 @@ Importing Modules
    If *name* points to a dotted name of the form ``package.module``, any package
    structures not already created will still not be created.
 
+   See also :func:`PyImport_ExecCodeModuleEx` and
+   :func:`PyImport_ExecCodeModuleWithPathnames`.
+
 
 .. cfunction:: PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname)
 
    Like :cfunc:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of
    the module object is set to *pathname* if it is non-``NULL``.
 
+   See also :func:`PyImport_ExecCodeModuleWithPathnames`.
+
+
+.. cfunction:: PyObject* PyImport_ExecCodeModuleWithPathnames(char *name, PyObject *co, char *pathname, char *cpathname)
+
+   Like :cfunc:`PyImport_ExecCodeModuleEx`, but the :attr:`__cached__`
+   attribute of the module object is set to *cpathname* if it is
+   non-``NULL``.  Of the three functions, this is the preferred one to use.
+
 
 .. cfunction:: long PyImport_GetMagicNumber()
 
@@ -138,6 +150,11 @@ Importing Modules
    of the bytecode file, in little-endian byte order.
 
 
+.. cfunction:: const char * PyImport_GetMagicTag()
+
+   Return the magic tag string for :pep:`3147` format Python bytecode file
+   names.
+
 .. cfunction:: PyObject* PyImport_GetModuleDict()
 
    Return the dictionary used for the module administration (a.k.a.
diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst
index 83e418d..b0a2e34 100644
--- a/Doc/library/compileall.rst
+++ b/Doc/library/compileall.rst
@@ -17,9 +17,11 @@ line.  If no arguments are given, the invocation is equivalent to ``-l
 sys.path``.  Printing lists of the files compiled can be disabled with the
 :option:`-q` flag.  In addition, the :option:`-x` option takes a regular
 expression argument.  All files that match the expression will be skipped.
+The :option:`-b` flag may be given to write legacy ``.pyc`` file path names,
+otherwise :pep:`3147` style byte-compiled path names are written.
 
 
-.. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=False)
+.. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=False, legacy=False)
 
    Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
    files along the way.  The *maxlevels* parameter is used to limit the depth of
@@ -34,12 +36,16 @@ expression argument.  All files that match the expression will be skipped.
    If *quiet* is true, nothing is printed to the standard output in normal
    operation.
 
+   If *legacy* is true, old-style ``.pyc`` file path names are written,
+   otherwise (the default), :pep:`3147` style path names are written.
 
-.. function:: compile_path(skip_curdir=True, maxlevels=0, force=False)
+
+.. function:: compile_path(skip_curdir=True, maxlevels=0, force=False, legacy=False)
 
    Byte-compile all the :file:`.py` files found along ``sys.path``. If
    *skip_curdir* is true (the default), the current directory is not included in
-   the search.  The *maxlevels* and *force* parameters default to ``0`` and are
+   the search.  The *maxlevels* parameter defaults to ``0``, and the *force*
+   and *legacy* parameters default to ``False``. All are
    passed to the :func:`compile_dir` function.
 
 To force a recompile of all the :file:`.py` files in the :file:`Lib/`
diff --git a/Doc/library/imp.rst b/Doc/library/imp.rst
index 68cda84..6e70d08 100644
--- a/Doc/library/imp.rst
+++ b/Doc/library/imp.rst
@@ -204,8 +204,41 @@ This module provides an interface to the mechanisms used to implement the
    function does nothing.
 
 
-The following constants with integer values, defined in this module, are used to
-indicate the search result of :func:`find_module`.
+The following functions and data provide conveniences for handling :pep:`3147`
+byte-compiled file paths.
+
+.. versionadded:: 3.2
+
+.. function:: cache_from_source(path, debug_override=None)
+
+   Return the PEP 3147 path to the byte-compiled file associated with the
+   source *path*.  For example, if *path* is ``/foo/bar/baz.py`` the return
+   value would be ``/foo/bar/__pycache__/baz.cpython-32.pyc`` for Python 3.2.
+   The ``cpython-32`` string comes from the current magic tag (see
+   :func:`get_tag`).  The returned path will end in ``.pyc`` when
+   ``__debug__`` is True or ``.pyo`` for an optimized Python
+   (i.e. ``__debug__`` is False).  By passing in True or False for
+   *debug_override* you can override the system's value for ``__debug__`` for
+   extension selection.
+
+   *path* need not exist.
+
+.. function:: source_from_cache(path)
+
+   Given the *path* to a PEP 3147 file name, return the associated source code
+   file path.  For example, if *path* is
+   ``/foo/bar/__pycache__/baz.cpython-32.pyc`` the returned path would be
+   ``/foo/bar/baz.py``.  *path* need not exist, however if it does not conform
+   to PEP 3147 format, a ``ValueError`` is raised.
+
+.. function:: get_tag()
+
+   Return the PEP 3147 magic tag string matching this version of Python's
+   magic number, as returned by :func:`get_magic`.
+
+
+The following constants with integer values, defined in this module, are used
+to indicate the search result of :func:`find_module`.
 
 
 .. data:: PY_SOURCE
diff --git a/Doc/library/py_compile.rst b/Doc/library/py_compile.rst
index c4f7229..c6eea84 100644
--- a/Doc/library/py_compile.rst
+++ b/Doc/library/py_compile.rst
@@ -26,12 +26,16 @@ byte-code cache files in the directory containing the source code.
 
    Compile a source file to byte-code and write out the byte-code cache  file.  The
    source code is loaded from the file name *file*.  The  byte-code is written to
-   *cfile*, which defaults to *file* ``+`` ``'c'`` (``'o'`` if optimization is
-   enabled in the current interpreter).  If *dfile* is specified, it is used as the
+   *cfile*, which defaults to the :PEP:`3147` path, ending in ``.pyc``
+   (``'.pyo`` if optimization is enabled in the current interpreter).  For
+   example, if *file* is ``/foo/bar/baz.py`` *cfile* will default to
+   ``/foo/bar/__pycache__/baz.cpython-32.pyc`` for Python 3.2.  If *dfile* is specified, it is used as the
    name of the source file in error messages instead of *file*.  If *doraise* is
    true, a :exc:`PyCompileError` is raised when an error is encountered while
    compiling *file*. If *doraise* is false (the default), an error string is
-   written to ``sys.stderr``, but no exception is raised.
+   written to ``sys.stderr``, but no exception is raised.  This function
+   returns the path to byte-compiled file, i.e. whatever *cfile* value was
+   used.
 
 
 .. function:: main(args=None)
diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst
index 7278b7a..a96285c 100644
--- a/Doc/library/runpy.rst
+++ b/Doc/library/runpy.rst
@@ -32,7 +32,8 @@ The :mod:`runpy` module provides two functions:
    below are defined in the supplied dictionary, those definitions are
    overridden by :func:`run_module`.
 
-   The special global variables ``__name__``, ``__file__``, ``__loader__``
+   The special global variables ``__name__``, ``__file__``, ``__cached__``,
+   ``__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).
@@ -45,6 +46,8 @@ The :mod:`runpy` module provides two functions:
    loader does not make filename information available, this variable is set
    to :const:`None`.
 
+    ``__cached__`` will be 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).