1 :mod:`compileall` --- Byte-compile Python libraries 2 =================================================== 3 4 .. module:: compileall 5 :synopsis: Tools for byte-compiling all Python source files in a directory tree. 6 7 **Source code:** :source:`Lib/compileall.py` 8 9 -------------- 10 11 12 This module provides some utility functions to support installing Python 13 libraries. These functions compile Python source files in a directory tree. 14 This module can be used to create the cached byte-code files at library 15 installation time, which makes them available for use even by users who don't 16 have write permission to the library directories. 17 18 19 Command-line use 20 ---------------- 21 22 This module can work as a script (using :program:`python -m compileall`) to 23 compile Python sources. 24 25 .. program:: compileall 26 27 .. cmdoption:: directory ... 28 file ... 29 30 Positional arguments are files to compile or directories that contain 31 source files, traversed recursively. If no argument is given, behave as if 32 the command line was ``-l <directories from sys.path>``. 33 34 .. cmdoption:: -l 35 36 Do not recurse into subdirectories, only compile source code files directly 37 contained in the named or implied directories. 38 39 .. cmdoption:: -f 40 41 Force rebuild even if timestamps are up-to-date. 42 43 .. cmdoption:: -q 44 45 Do not print the list of files compiled, print only error messages. 46 47 .. cmdoption:: -d destdir 48 49 Directory prepended to the path to each file being compiled. This will 50 appear in compilation time tracebacks, and is also compiled in to the 51 byte-code file, where it will be used in tracebacks and other messages in 52 cases where the source file does not exist at the time the byte-code file is 53 executed. 54 55 .. cmdoption:: -x regex 56 57 regex is used to search the full path to each file considered for 58 compilation, and if the regex produces a match, the file is skipped. 59 60 .. cmdoption:: -i list 61 62 Read the file ``list`` and add each line that it contains to the list of 63 files and directories to compile. If ``list`` is ``-``, read lines from 64 ``stdin``. 65 66 .. versionchanged:: 2.7 67 Added the ``-i`` option. 68 69 70 Public functions 71 ---------------- 72 73 .. function:: compile_dir(dir[, maxlevels[, ddir[, force[, rx[, quiet]]]]]) 74 75 Recursively descend the directory tree named by *dir*, compiling all :file:`.py` 76 files along the way. 77 78 The *maxlevels* parameter is used to limit the depth of the recursion; it 79 defaults to ``10``. 80 81 If *ddir* is given, it is prepended to the path to each file being compiled 82 for use in compilation time tracebacks, and is also compiled in to the 83 byte-code file, where it will be used in tracebacks and other messages in 84 cases where the source file does not exist at the time the byte-code file is 85 executed. 86 87 If *force* is true, modules are re-compiled even if the timestamps are up to 88 date. 89 90 If *rx* is given, its search method is called on the complete path to each 91 file considered for compilation, and if it returns a true value, the file 92 is skipped. 93 94 If *quiet* is true, nothing is printed to the standard output unless errors 95 occur. 96 97 98 .. function:: compile_file(fullname[, ddir[, force[, rx[, quiet]]]]) 99 100 Compile the file with path *fullname*. 101 102 If *ddir* is given, it is prepended to the path to the file being compiled 103 for use in compilation time tracebacks, and is also compiled in to the 104 byte-code file, where it will be used in tracebacks and other messages in 105 cases where the source file does not exist at the time the byte-code file is 106 executed. 107 108 If *rx* is given, its search method is passed the full path name to the 109 file being compiled, and if it returns a true value, the file is not 110 compiled and ``True`` is returned. 111 112 If *quiet* is true, nothing is printed to the standard output unless errors 113 occur. 114 115 .. versionadded:: 2.7 116 117 118 .. function:: compile_path([skip_curdir[, maxlevels[, force]]]) 119 120 Byte-compile all the :file:`.py` files found along ``sys.path``. If 121 *skip_curdir* is true (the default), the current directory is not included 122 in the search. All other parameters are passed to the :func:`compile_dir` 123 function. Note that unlike the other compile functions, ``maxlevels`` 124 defaults to ``0``. 125 126 To force a recompile of all the :file:`.py` files in the :file:`Lib/` 127 subdirectory and all its subdirectories:: 128 129 import compileall 130 131 compileall.compile_dir('Lib/', force=True) 132 133 # Perform same compilation, excluding files in .svn directories. 134 import re 135 compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True) 136 137 138 .. seealso:: 139 140 Module :mod:`py_compile` 141 Byte-compile a single source file. 142
