#10454: clarify the compileall docs and help messages.
diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst
index 53c3f0a..d515d4d 100644
--- a/Doc/library/compileall.rst
+++ b/Doc/library/compileall.rst
@@ -6,9 +6,10 @@
This module provides some utility functions to support installing Python
-libraries. These functions compile Python source files in a directory tree,
-allowing users without permission to write to the libraries to take advantage of
-cached byte-code files.
+libraries. These functions compile Python source files in a directory tree.
+This module can be used to create the cached byte-code files at library
+installation time, which makes them available for use even by users who don't
+have write permission to the library directories.
Command-line use
@@ -27,7 +28,8 @@
.. cmdoption:: -l
- Do not recurse.
+ Do not recurse into subdirectories, only compile source code files directly
+ contained in the named or implied directories.
.. cmdoption:: -f
@@ -35,24 +37,33 @@
.. cmdoption:: -q
- Do not print the list of files compiled.
+ Do not print the list of files compiled, print only error messages.
.. cmdoption:: -d destdir
- Purported directory name for error messages.
+ Directory prepended to the path to each file being compiled. This will
+ appear in compilation time tracebacks, and is also compiled in to the
+ byte-code file, where it will be used in tracebacks and other messages in
+ cases where the source file does not exist at the time the byte-code file is
+ executed.
.. cmdoption:: -x regex
- Skip files with a full path that matches given regular expression.
+ regex is used to search the full path to each file considered for
+ compilation, and if the regex produces a match, the file is skipped.
.. cmdoption:: -i list
- Expand list with its content (file and directory names).
+ Read the file ``list`` and add each line that it contains to the list of
+ files and directories to compile. If ``list`` is ``-``, read lines from
+ ``stdin``.
.. cmdoption:: -b
- Write legacy ``.pyc`` file path names. Default is to write :pep:`3147`-style
- byte-compiled path names.
+ Write the byte-code files to their legacy locations and names, which may
+ overwrite byte-code files created by another version of Python. The default
+ is to write files to their :pep:`3147` locations and names, which allows
+ byte-code files from multiple versions of Python to coexist.
.. versionchanged:: 3.2
Added the ``-i``, ``-b`` and ``-h`` options.
@@ -64,20 +75,32 @@
.. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=False, legacy=False, optimize=-1)
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
- the recursion; it defaults to ``10``. If *ddir* is given, it is used as the
- base path from which the filenames used in error messages will be generated.
+ files along the way.
+
+ The *maxlevels* parameter is used to limit the depth of the recursion; it
+ defaults to ``10``.
+
+ If *ddir* is given, it is prepended to the path to each file being compiled
+ for use in compilation time tracebacks, and is also compiled in to the
+ byte-code file, where it will be used in tracebacks and other messages in
+ cases where the source file does not exist at the time the byte-code file is
+ executed.
+
If *force* is true, modules are re-compiled even if the timestamps are up to
date.
- If *rx* is given, it specifies a regular expression of file names to exclude
- from the search; that expression is searched for in the full path.
+ If *rx* is given, its search method is called on the complete path to each
+ file considered for compilation, and if it returns a true value, the file
+ is skipped.
- If *quiet* is true, nothing is printed to the standard output in normal
- operation.
+ If *quiet* is true, nothing is printed to the standard output unless errors
+ occur.
- If *legacy* is true, old-style ``.pyc`` file path names are written,
- otherwise (the default), :pep:`3147`-style path names are written.
+ If *legacy* is true, byte-code files are written to their legacy locations
+ and names, which may overwrite byte-code files created by another version of
+ Python. The default is to write files to their :pep:`3147` locations and
+ names, which allows byte-code files from multiple versions of Python to
+ coexist.
*optimize* specifies the optimization level for the compiler. It is passed to
the built-in :func:`compile` function.
@@ -88,19 +111,26 @@
.. 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.
+ Compile the file with path *fullname*.
- 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 *ddir* is given, it is prepended to the path to the file being compiled
+ for use in compilation time tracebacks, and is also compiled in to the
+ byte-code file, where it will be used in tracebacks and other messages in
+ cases where the source file does not exist at the time the byte-code file is
+ executed.
- If *quiet* is true, nothing is printed to the standard output in normal
- operation.
+ If *ra* is given, its search method is passed the full path name to the
+ file being compiled, and if it returns a true value, the file is not
+ compiled and ``True`` is returned.
- If *legacy* is true, old-style ``.pyc`` file path names are written,
- otherwise (the default), :pep:`3147`-style path names are written.
+ If *quiet* is true, nothing is printed to the standard output unless errors
+ occur.
+
+ If *legacy* is true, byte-code files are written to their legacy locations
+ and names, which may overwrite byte-code files created by another version of
+ Python. The default is to write files to their :pep:`3147` locations and
+ names, which allows byte-code files from multiple versions of Python to
+ coexist.
*optimize* specifies the optimization level for the compiler. It is passed to
the built-in :func:`compile` function.
@@ -111,9 +141,10 @@
.. function:: compile_path(skip_curdir=True, maxlevels=0, force=False, legacy=False, optimize=-1)
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. All other parameters are passed to the :func:`compile_dir`
- function.
+ *skip_curdir* is true (the default), the current directory is not included
+ in the search. All other parameters are passed to the :func:`compile_dir`
+ function. Note that unlike the other compile functions, ``maxlevels``
+ defaults to ``0``.
.. versionchanged:: 3.2
Added the *legacy* and *optimize* parameter.