Add missing docs and directives related to PEP 3147 and byte-compilation
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