diff options
Diffstat (limited to 'Doc/library/compileall.rst')
| -rw-r--r-- | Doc/library/compileall.rst | 51 |
1 files changed, 34 insertions, 17 deletions
diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst index c359676..8a93f9b 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,15 +37,20 @@ 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. Public functions @@ -52,24 +59,34 @@ Public functions .. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=False) 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. .. function:: compile_path(skip_curdir=True, maxlevels=0, force=False) 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. The *maxlevels* and *force* parameters default to ``0`` and 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``. To force a recompile of all the :file:`.py` files in the :file:`Lib/` subdirectory and all its subdirectories:: |