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 .. cmdoption:: --invalidation-mode [timestamp|checked-hash|unchecked-hash] 87 88 Control how the generated byte-code files are invalidated at runtime. 89 The ``timestamp`` value, means that ``.pyc`` files with the source timestamp 90 and size embedded will be generated. The ``checked-hash`` and 91 ``unchecked-hash`` values cause hash-based pycs to be generated. Hash-based 92 pycs embed a hash of the source file contents rather than a timestamp. See 93 :ref:`pyc-invalidation` for more information on how Python validates 94 bytecode cache files at runtime. 95 The default is ``timestamp`` if the :envvar:`SOURCE_DATE_EPOCH` environment 96 variable is not set, and ``checked-hash`` if the ``SOURCE_DATE_EPOCH`` 97 environment variable is set. 98 99 .. versionchanged:: 3.2 100 Added the ``-i``, ``-b`` and ``-h`` options. 101 102 .. versionchanged:: 3.5 103 Added the ``-j``, ``-r``, and ``-qq`` options. ``-q`` option 104 was changed to a multilevel value. ``-b`` will always produce a 105 byte-code file ending in ``.pyc``, never ``.pyo``. 106 107 .. versionchanged:: 3.7 108 Added the ``--invalidation-mode`` option. 109 110 111 There is no command-line option to control the optimization level used by the 112 :func:`compile` function, because the Python interpreter itself already 113 provides the option: :program:`python -O -m compileall`. 114 115 Public functions 116 ---------------- 117 118 .. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=py_compile.PycInvalidationMode.TIMESTAMP) 119 120 Recursively descend the directory tree named by *dir*, compiling all :file:`.py` 121 files along the way. Return a true value if all the files compiled successfully, 122 and a false value otherwise. 123 124 The *maxlevels* parameter is used to limit the depth of the recursion; it 125 defaults to ``10``. 126 127 If *ddir* is given, it is prepended to the path to each file being compiled 128 for use in compilation time tracebacks, and is also compiled in to the 129 byte-code file, where it will be used in tracebacks and other messages in 130 cases where the source file does not exist at the time the byte-code file is 131 executed. 132 133 If *force* is true, modules are re-compiled even if the timestamps are up to 134 date. 135 136 If *rx* is given, its search method is called on the complete path to each 137 file considered for compilation, and if it returns a true value, the file 138 is skipped. 139 140 If *quiet* is ``False`` or ``0`` (the default), the filenames and other 141 information are printed to standard out. Set to ``1``, only errors are 142 printed. Set to ``2``, all output is suppressed. 143 144 If *legacy* is true, byte-code files are written to their legacy locations 145 and names, which may overwrite byte-code files created by another version of 146 Python. The default is to write files to their :pep:`3147` locations and 147 names, which allows byte-code files from multiple versions of Python to 148 coexist. 149 150 *optimize* specifies the optimization level for the compiler. It is passed to 151 the built-in :func:`compile` function. 152 153 The argument *workers* specifies how many workers are used to 154 compile files in parallel. The default is to not use multiple workers. 155 If the platform can't use multiple workers and *workers* argument is given, 156 then sequential compilation will be used as a fallback. If *workers* is 157 lower than ``0``, a :exc:`ValueError` will be raised. 158 159 *invalidation_mode* should be a member of the 160 :class:`py_compile.PycInvalidationMode` enum and controls how the generated 161 pycs are invalidated at runtime. 162 163 .. versionchanged:: 3.2 164 Added the *legacy* and *optimize* parameter. 165 166 .. versionchanged:: 3.5 167 Added the *workers* parameter. 168 169 .. versionchanged:: 3.5 170 *quiet* parameter was changed to a multilevel value. 171 172 .. versionchanged:: 3.5 173 The *legacy* parameter only writes out ``.pyc`` files, not ``.pyo`` files 174 no matter what the value of *optimize* is. 175 176 .. versionchanged:: 3.6 177 Accepts a :term:`path-like object`. 178 179 .. versionchanged:: 3.7 180 The *invalidation_mode* parameter was added. 181 182 .. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=py_compile.PycInvalidationMode.TIMESTAMP) 183 184 Compile the file with path *fullname*. Return a true value if the file 185 compiled successfully, and a false value otherwise. 186 187 If *ddir* is given, it is prepended to the path to the file being compiled 188 for use in compilation time tracebacks, and is also compiled in to the 189 byte-code file, where it will be used in tracebacks and other messages in 190 cases where the source file does not exist at the time the byte-code file is 191 executed. 192 193 If *rx* is given, its search method is passed the full path name to the 194 file being compiled, and if it returns a true value, the file is not 195 compiled and ``True`` is returned. 196 197 If *quiet* is ``False`` or ``0`` (the default), the filenames and other 198 information are printed to standard out. Set to ``1``, only errors are 199 printed. Set to ``2``, all output is suppressed. 200 201 If *legacy* is true, byte-code files are written to their legacy locations 202 and names, which may overwrite byte-code files created by another version of 203 Python. The default is to write files to their :pep:`3147` locations and 204 names, which allows byte-code files from multiple versions of Python to 205 coexist. 206 207 *optimize* specifies the optimization level for the compiler. It is passed to 208 the built-in :func:`compile` function. 209 210 *invalidation_mode* should be a member of the 211 :class:`py_compile.PycInvalidationMode` enum and controls how the generated 212 pycs are invalidated at runtime. 213 214 .. versionadded:: 3.2 215 216 .. versionchanged:: 3.5 217 *quiet* parameter was changed to a multilevel value. 218 219 .. versionchanged:: 3.5 220 The *legacy* parameter only writes out ``.pyc`` files, not ``.pyo`` files 221 no matter what the value of *optimize* is. 222 223 .. versionchanged:: 3.7 224 The *invalidation_mode* parameter was added. 225 226 .. function:: compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=py_compile.PycInvalidationMode.TIMESTAMP) 227 228 Byte-compile all the :file:`.py` files found along ``sys.path``. Return a 229 true value if all the files compiled successfully, and a false value otherwise. 230 231 If *skip_curdir* is true (the default), the current directory is not included 232 in the search. All other parameters are passed to the :func:`compile_dir` 233 function. Note that unlike the other compile functions, ``maxlevels`` 234 defaults to ``0``. 235 236 .. versionchanged:: 3.2 237 Added the *legacy* and *optimize* parameter. 238 239 .. versionchanged:: 3.5 240 *quiet* parameter was changed to a multilevel value. 241 242 .. versionchanged:: 3.5 243 The *legacy* parameter only writes out ``.pyc`` files, not ``.pyo`` files 244 no matter what the value of *optimize* is. 245 246 .. versionchanged:: 3.7 247 The *invalidation_mode* parameter was added. 248 249 To force a recompile of all the :file:`.py` files in the :file:`Lib/` 250 subdirectory and all its subdirectories:: 251 252 import compileall 253 254 compileall.compile_dir('Lib/', force=True) 255 256 # Perform same compilation, excluding files in .svn directories. 257 import re 258 compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True) 259 260 # pathlib.Path objects can also be used. 261 import pathlib 262 compileall.compile_dir(pathlib.Path('Lib/'), force=True) 263 264 .. seealso:: 265 266 Module :mod:`py_compile` 267 Byte-compile a single source file. 268
