Add missing docs and directives related to PEP 3147 and byte-compilation
diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst
index 29041cd..53c3f0a 100644
--- a/Doc/library/compileall.rst
+++ b/Doc/library/compileall.rst
@@ -54,8 +54,8 @@
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 @@
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 @@
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 058e6b6..398698f 100644
--- a/Doc/library/imp.rst
+++ b/Doc/library/imp.rst
@@ -190,8 +190,8 @@
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 b5b9010..d2e3208 100644
--- a/Doc/library/py_compile.rst
+++ b/Doc/library/py_compile.rst
@@ -24,25 +24,27 @@
.. 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 @@
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 896b65d..10e5ebc 100644
--- a/Doc/library/runpy.rst
+++ b/Doc/library/runpy.rst
@@ -70,6 +70,9 @@
.. 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)