From 94f58c3a650fa783ec85f3dbdfde98d4e2976f8d Mon Sep 17 00:00:00 2001 From: "R. David Murray" Date: Fri, 17 Dec 2010 16:29:07 +0000 Subject: [PATCH] #10454: clarify the compileall docs and help messages. --- Doc/library/compileall.rst | 95 +++++++++++++++++++++++++------------- Lib/compileall.py | 37 +++++++++------ 2 files changed, 85 insertions(+), 47 deletions(-) diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst index 53c3f0ab50c..d515d4d2fb1 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 *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 @@ 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 f9ec4863df2..94d1c9e66cc 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