Add missing docs and directives related to PEP 3147 and byte-compilation

5 files changed, 54 insertions, 19 deletions

diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst
index 15a11fd4be..cf48363e10 100644
--- a/Doc/c-api/import.rst
+++ b/Doc/c-api/import.rst
@@ -142,6 +142,7 @@ Importing Modules
    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.
 
+   .. versionadded:: 3.2
 
 .. c:function:: long PyImport_GetMagicNumber()
 
@@ -155,6 +156,8 @@ Importing Modules
    Return the magic tag string for :pep:`3147` format Python bytecode file
    names.
 
+   .. versionadded:: 3.2
+
 .. c:function:: 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 29041cdade..53c3f0ab50 100644
--- a/Doc/library/compileall.rst
+++ b/Doc/library/compileall.rst
@@ -54,8 +54,8 @@ compile Python sources.
    Write legacy ``.pyc`` file path names.  Default is to write :pep:`3147`-style
    byte-compiled path names.
 
-.. versionadded:: 3.2
-   The ``-i`` and ``-b`` options.
+.. versionchanged:: 3.2
+   Added the ``-i``, ``-b`` and ``-h`` options.
 
 
 Public functions
@@ -83,7 +83,29 @@ Public functions
    the built-in :func:`compile` function.
 
    .. versionchanged:: 3.2
-      Added the *optimize* parameter.
+      Added the *legacy* and *optimize* parameter.
+
+
+.. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=False, legacy=False, optimize=-1)
+
+   Compile the file with path *fullname*.  If *ddir* is given, it is used as the
+   base path from  which the filename used in error messages will be generated.
+   If *force* is true, modules are re-compiled even if the timestamp is up to
+   date.
+
+   If *rx* is given, it specifies a regular expression which, if matched, will
+   prevent compilation; that expression is searched for in the full path.
+
+   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.
+
+   *optimize* specifies the optimization level for the compiler.  It is passed to
+   the built-in :func:`compile` function.
+
+   .. versionadded:: 3.2
 
 
 .. function:: compile_path(skip_curdir=True, maxlevels=0, force=False, legacy=False, optimize=-1)
@@ -94,7 +116,7 @@ Public functions
    function.
 
    .. versionchanged:: 3.2
-      Added the *optimize* parameter.
+      Added the *legacy* and *optimize* parameter.
 
 
 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 058e6b6a10..398698f930 100644
--- a/Doc/library/imp.rst
+++ b/Doc/library/imp.rst
@@ -190,8 +190,8 @@ This module provides an interface to the mechanisms used to implement the
    continue to use the old class definition.  The same is true for derived classes.
 
 
-The following functions and data provide conveniences for handling :pep:`3147`
-byte-compiled file paths.
+The following functions are conveniences for handling :pep:`3147` byte-compiled
+file paths.
 
 .. versionadded:: 3.2
 
diff --git a/Doc/library/py_compile.rst b/Doc/library/py_compile.rst
index b5b90107ec..d2e3208a65 100644
--- a/Doc/library/py_compile.rst
+++ b/Doc/library/py_compile.rst
@@ -24,25 +24,27 @@ byte-code cache files in the directory containing the source code.
 
 .. function:: compile(file, cfile=None, dfile=None, doraise=False, optimize=-1)
 
-   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 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.  This function
-   returns the path to byte-compiled file, i.e. whatever *cfile* value was
-   used.
+   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 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 when
+   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.  This function returns the path to byte-compiled file, i.e.
+   whatever *cfile* value was used.
 
    *optimize* controls the optimization level and is passed to the built-in
    :func:`compile` function.  The default of ``-1`` selects the optimization
    level of the current interpreter.
 
    .. versionchanged:: 3.2
-      Added the *optimize* parameter.
+      Changed default value of *cfile* to be :PEP:`3147`-compliant.  Previous
+      default was *file* + ``'c'`` (``'o'`` if optimization was enabled).
+      Also added the *optimize* parameter.
 
 
 .. function:: main(args=None)
@@ -51,6 +53,11 @@ byte-code cache files in the directory containing the source code.
    line, if *args* is ``None``) are compiled and the resulting bytecode is
    cached in the normal manner.  This function does not search a directory
    structure to locate source files; it only compiles files named explicitly.
+   If ``'-'`` is the only parameter in args, the list of files is taken from
+   standard input.
+
+   .. versionchanged:: 3.2
+      Added support for ``'-'``.
 
 When this module is run as a script, the :func:`main` is used to compile all the
 files named on the command line.  The exit status is nonzero if one of the files
diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst
index 896b65d44b..10e5ebcec2 100644
--- a/Doc/library/runpy.rst
+++ b/Doc/library/runpy.rst
@@ -70,6 +70,9 @@ The :mod:`runpy` module provides two functions:
    .. versionchanged:: 3.1
       Added ability to execute packages by looking for a ``__main__`` submodule.
 
+   .. versionchanged:: 3.2
+      Added ``__cached__`` global variable (see :PEP:`3147`).
+
 
 .. function:: run_path(file_path, init_globals=None, run_name=None)