#10454: clarify the compileall docs and help messages.

2 files changed, 85 insertions, 47 deletions

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 @@ compile Python sources.
 
 .. 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 @@ compile Python sources.
 
 .. 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 @@ Public functions
 .. 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 @@ Public functions
 
 .. 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 *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 *rx* is given, it specifies a regular expression which, if matched, will
-   prevent compilation; that expression is searched for in the full path.
+   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 *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.
@@ -111,9 +141,10 @@ Public functions
 .. 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.
diff --git a/Lib/compileall.py b/Lib/compileall.py
index f9ec486..94d1c9e 100644
--- a/Lib/compileall.py
+++ b/Lib/compileall.py
@@ -27,8 +27,8 @@ def compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None,
 
     dir:       the directory to byte-compile
     maxlevels: maximum recursion level (default 10)
-    ddir:      if given, purported directory name (this is the
-               directory name that will show up in error messages)
+    ddir:      the directory that will be prepended to the path to the
+               file as it is compiled into each byte-code file.
     force:     if True, force compilation, even if timestamps are up-to-date
     quiet:     if True, be quiet during compilation
     legacy:    if True, produce legacy pyc paths instead of PEP 3147 paths
@@ -66,8 +66,8 @@ def compile_file(fullname, ddir=None, force=0, rx=None, quiet=False,
                  legacy=False, optimize=-1):
     """Byte-compile file.
     fullname:  the file to byte-compile
-    ddir:      if given, purported directory name (this is the
-               directory name that will show up in error messages)
+    ddir:      if given, the directory name compiled in to the
+               byte-code file.
     force:     if True, force compilation, even if timestamps are up-to-date
     quiet:     if True, be quiet during compilation
     legacy:    if True, produce legacy pyc paths instead of PEP 3147 paths
@@ -163,25 +163,32 @@ def main():
 
     parser = argparse.ArgumentParser(
         description='Utilities to support installing Python libraries.')
-    parser.add_argument('-l', action='store_const', default=10, const=0,
-                        dest='maxlevels', help="don't recurse down")
+    parser.add_argument('-l', action='store_const', const=0,
+                        default=10, dest='maxlevels',
+                        help="don't recurse into subdirectories")
     parser.add_argument('-f', action='store_true', dest='force',
                         help='force rebuild even if timestamps are up to date')
     parser.add_argument('-q', action='store_true', dest='quiet',
-                        help='reduce output')
+                        help='output only error messages')
     parser.add_argument('-b', action='store_true', dest='legacy',
-                        help='produce legacy byte-compiled file paths')
+                        help='use legacy (pre-PEP3147) compiled file locations')
     parser.add_argument('-d', metavar='DESTDIR',  dest='ddir', default=None,
-                        help=('purported directory name for error messages; '
-                              'if no directory arguments, -l sys.path '
-                              'is assumed.'))
+                        help=('directory to prepend to file paths for use in '
+                              'compile time tracebacks and in runtime '
+                              'tracebacks in cases where the source file is '
+                              'unavailable'))
     parser.add_argument('-x', metavar='REGEXP', dest='rx', default=None,
-                        help=('skip files matching the regular expression.\n\t'
+                        help=('skip files matching the regular expression. '
                               'The regexp is searched for in the full path '
-                              'of the file'))
+                              'to each file considered for compilation.'))
     parser.add_argument('-i', metavar='FILE', dest='flist',
-                        help='expand the list with the content of FILE.')
-    parser.add_argument('compile_dest', metavar='FILE|DIR', nargs='*')
+                        help=('add all the files and directories listed in '
+                              'FILE to the list considered for compilation. '
+                              'If "-", names are read from stdin.'))
+    parser.add_argument('compile_dest', metavar='FILE|DIR', nargs='*',
+                        help=('zero or more file and directory names '
+                              'to compile; if no arguments given, defaults '
+                              'to the equivalent of -l sys.path'))
     args = parser.parse_args()
 
     compile_dests = args.compile_dest