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 This module provides some utility functions to support installing Python 12 libraries. These functions compile Python source files in a directory tree. 13 This module can be used to create the cached byte-code files at library 14 installation time, which makes them available for use even by users who don't 15 have write permission to the library directories. 16 17 18 Command-line use 19 ---------------- 20 21 This module can work as a script (using :program:`python -m compileall`) to 22 compile Python sources. 23 24 .. program:: compileall 25 26 .. cmdoption:: directory ... 27 file ... 28 29 Positional arguments are files to compile or directories that contain 30 source files, traversed recursively. If no argument is given, behave as if 31 the command line was ``-l <directories from sys.path>``. 32 33 .. cmdoption:: -l 34 35 Do not recurse into subdirectories, only compile source code files directly 36 contained in the named or implied directories. 37 38 .. cmdoption:: -f 39 40 Force rebuild even if timestamps are up-to-date. 41 42 .. cmdoption:: -q 43 44 Do not print the list of files compiled. If passed once, error messages will 45 still be printed. If passed twice (``-qq``), all output is suppressed. 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 .. cmdoption:: -b 67 68 Write the byte-code files to their legacy locations and names, which may 69 overwrite byte-code files created by another version of Python. The default 70 is to write files to their :pep:`3147` locations and names, which allows 71 byte-code files from multiple versions of Python to coexist. 72 73 .. cmdoption:: -r 74 75 Control the maximum recursion level for subdirectories. 76 If this is given, then ``-l`` option will not be taken into account. 77 :program:`python -m compileall <directory> -r 0` is equivalent to 78 :program:`python -m compileall <directory> -l`. 79 80 .. cmdoption:: -j N 81 82 Use *N* workers to compile the files within the given directory. 83 If ``0`` is used, then the result of :func:`os.cpu_count()` 84 will be used. 85 86 .. versionchanged:: 3.2 87 Added the ``-i``, ``-b`` and ``-h`` options. 88 89 .. versionchanged:: 3.5 90 Added the ``-j``, ``-r``, and ``-qq`` options. ``-q`` option 91 was changed to a multilevel value. ``-b`` will always produce a 92 byte-code file ending in ``.pyc``, never ``.pyo``. 93 94 95 There is no command-line option to control the optimization level used by the 96 :func:`compile` function, because the Python interpreter itself already 97 provides the option: :program:`python -O -m compileall`. 98 99 Public functions 100 ---------------- 101 102 .. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1) 103 104 Recursively descend the directory tree named by *dir*, compiling all :file:`.py` 105 files along the way. Return a true value if all the files compiled successfully, 106 and a false value otherwise. 107 108 The *maxlevels* parameter is used to limit the depth of the recursion; it 109 defaults to ``10``. 110 111 If *ddir* is given, it is prepended to the path to each file being compiled 112 for use in compilation time tracebacks, and is also compiled in to the 113 byte-code file, where it will be used in tracebacks and other messages in 114 cases where the source file does not exist at the time the byte-code file is 115 executed. 116 117 If *force* is true, modules are re-compiled even if the timestamps are up to 118 date. 119 120 If *rx* is given, its search method is called on the complete path to each 121 file considered for compilation, and if it returns a true value, the file 122 is skipped. 123 124 If *quiet* is ``False`` or ``0`` (the default), the filenames and other 125 information are printed to standard out. Set to ``1``, only errors are 126 printed. Set to ``2``, all output is suppressed. 127 128 If *legacy* is true, byte-code files are written to their legacy locations 129 and names, which may overwrite byte-code files created by another version of 130 Python. The default is to write files to their :pep:`3147` locations and 131 names, which allows byte-code files from multiple versions of Python to 132 coexist. 133 134 *optimize* specifies the optimization level for the compiler. It is passed to 135 the built-in :func:`compile` function. 136 137 The argument *workers* specifies how many workers are used to 138 compile files in parallel. The default is to not use multiple workers. 139 If the platform can't use multiple workers and *workers* argument is given, 140 then sequential compilation will be used as a fallback. If *workers* is 141 lower than ``0``, a :exc:`ValueError` will be raised. 142 143 .. versionchanged:: 3.2 144 Added the *legacy* and *optimize* parameter. 145 146 .. versionchanged:: 3.5 147 Added the *workers* parameter. 148 149 .. versionchanged:: 3.5 150 *quiet* parameter was changed to a multilevel value. 151 152 .. versionchanged:: 3.5 153 The *legacy* parameter only writes out ``.pyc`` files, not ``.pyo`` files 154 no matter what the value of *optimize* is. 155 156 .. versionchanged:: 3.6 157 Accepts a :term:`path-like object`. 158 159 .. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1) 160 161 Compile the file with path *fullname*. Return a true value if the file 162 compiled successfully, and a false value otherwise. 163 164 If *ddir* is given, it is prepended to the path to the file being compiled 165 for use in compilation time tracebacks, and is also compiled in to the 166 byte-code file, where it will be used in tracebacks and other messages in 167 cases where the source file does not exist at the time the byte-code file is 168 executed. 169 170 If *rx* is given, its search method is passed the full path name to the 171 file being compiled, and if it returns a true value, the file is not 172 compiled and ``True`` is returned. 173 174 If *quiet* is ``False`` or ``0`` (the default), the filenames and other 175 information are printed to standard out. Set to ``1``, only errors are 176 printed. Set to ``2``, all output is suppressed. 177 178 If *legacy* is true, byte-code files are written to their legacy locations 179 and names, which may overwrite byte-code files created by another version of 180 Python. The default is to write files to their :pep:`3147` locations and 181 names, which allows byte-code files from multiple versions of Python to 182 coexist. 183 184 *optimize* specifies the optimization level for the compiler. It is passed to 185 the built-in :func:`compile` function. 186 187 .. versionadded:: 3.2 188 189 .. versionchanged:: 3.5 190 *quiet* parameter was changed to a multilevel value. 191 192 .. versionchanged:: 3.5 193 The *legacy* parameter only writes out ``.pyc`` files, not ``.pyo`` files 194 no matter what the value of *optimize* is. 195 196 .. function:: compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1) 197 198 Byte-compile all the :file:`.py` files found along ``sys.path``. Return a 199 true value if all the files compiled successfully, and a false value otherwise. 200 201 If *skip_curdir* is true (the default), the current directory is not included 202 in the search. All other parameters are passed to the :func:`compile_dir` 203 function. Note that unlike the other compile functions, ``maxlevels`` 204 defaults to ``0``. 205 206 .. versionchanged:: 3.2 207 Added the *legacy* and *optimize* parameter. 208 209 .. versionchanged:: 3.5 210 *quiet* parameter was changed to a multilevel value. 211 212 .. versionchanged:: 3.5 213 The *legacy* parameter only writes out ``.pyc`` files, not ``.pyo`` files 214 no matter what the value of *optimize* is. 215 216 To force a recompile of all the :file:`.py` files in the :file:`Lib/` 217 subdirectory and all its subdirectories:: 218 219 import compileall 220 221 compileall.compile_dir('Lib/', force=True) 222 223 # Perform same compilation, excluding files in .svn directories. 224 import re 225 compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True) 226 227 # pathlib.Path objects can also be used. 228 import pathlib 229 compileall.compile_dir(pathlib.Path('Lib/'), force=True) 230 231 .. seealso:: 232 233 Module :mod:`py_compile` 234 Byte-compile a single source file. 235
