PEP 3147
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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).