compileall —- Byte-compile Python libraries

Source code:Lib/compileall.py


This module provides some utility functions to support installing Pythonlibraries. These functions compile Python source files in a directory tree.This module can be used to create the cached byte-code files at libraryinstallation time, which makes them available for use even by users who don'thave write permission to the library directories.

Command-line use

This module can work as a script (using python -m compileall) tocompile Python sources.

  • directory
  • file
  • Positional arguments are files to compile or directories that containsource files, traversed recursively. If no argument is given, behave as ifthe command line was -l <directories from sys.path>.

  • -l

  • Do not recurse into subdirectories, only compile source code files directlycontained in the named or implied directories.

  • -f

  • Force rebuild even if timestamps are up-to-date.

  • -q

  • Do not print the list of files compiled. If passed once, error messages willstill be printed. If passed twice (-qq), all output is suppressed.

  • -d destdir

  • Directory prepended to the path to each file being compiled. This willappear in compilation time tracebacks, and is also compiled in to thebyte-code file, where it will be used in tracebacks and other messages incases where the source file does not exist at the time the byte-code file isexecuted.

  • -x regex

  • regex is used to search the full path to each file considered forcompilation, and if the regex produces a match, the file is skipped.

  • -i list

  • Read the file list and add each line that it contains to the list offiles and directories to compile. If list is -, read lines fromstdin.

  • -b

  • Write the byte-code files to their legacy locations and names, which mayoverwrite byte-code files created by another version of Python. The defaultis to write files to their PEP 3147 locations and names, which allowsbyte-code files from multiple versions of Python to coexist.

  • -r

  • Control the maximum recursion level for subdirectories.If this is given, then -l option will not be taken into account.python -m compileall -r 0 is equivalent topython -m compileall -l.
  • -j N
  • Use N workers to compile the files within the given directory.If 0 is used, then the result of os.cpu_count()will be used.

  • —invalidation-mode [timestamp|checked-hash|unchecked-hash]

  • Control how the generated byte-code files are invalidated at runtime.The timestamp value, means that .pyc files with the source timestampand size embedded will be generated. The checked-hash andunchecked-hash values cause hash-based pycs to be generated. Hash-basedpycs embed a hash of the source file contents rather than a timestamp. See已缓存字节码的失效 for more information on how Python validatesbytecode cache files at runtime.The default is timestamp if the SOURCE_DATE_EPOCH environmentvariable is not set, and checked-hash if the SOURCE_DATE_EPOCHenvironment variable is set.

在 3.2 版更改: Added the -i, -b and -h options.

在 3.5 版更改: Added the -j, -r, and -qq options. -q optionwas changed to a multilevel value. -b will always produce abyte-code file ending in .pyc, never .pyo.

在 3.7 版更改: Added the —invalidation-mode option.

There is no command-line option to control the optimization level used by thecompile() function, because the Python interpreter itself alreadyprovides the option: python -O -m compileall.

Similarly, the compile() function respects the sys.pycache_prefixsetting. The generated bytecode cache will only be useful if compile() isrun with the same sys.pycache_prefix (if any) that will be used atruntime.

Public functions

  • compileall.compiledir(_dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None)
  • Recursively descend the directory tree named by dir, compiling all .pyfiles along the way. Return a true value if all the files compiled successfully,and a false value otherwise.

The maxlevels parameter is used to limit the depth of the recursion; itdefaults to 10.

If ddir is given, it is prepended to the path to each file being compiledfor use in compilation time tracebacks, and is also compiled in to thebyte-code file, where it will be used in tracebacks and other messages incases where the source file does not exist at the time the byte-code file isexecuted.

If force is true, modules are re-compiled even if the timestamps are up todate.

If rx is given, its search method is called on the complete path to eachfile considered for compilation, and if it returns a true value, the fileis skipped.

If quiet is False or 0 (the default), the filenames and otherinformation are printed to standard out. Set to 1, only errors areprinted. Set to 2, all output is suppressed.

If legacy is true, byte-code files are written to their legacy locationsand names, which may overwrite byte-code files created by another version ofPython. The default is to write files to their PEP 3147 locations andnames, which allows byte-code files from multiple versions of Python tocoexist.

optimize specifies the optimization level for the compiler. It is passed tothe built-in compile() function.

The argument workers specifies how many workers are used tocompile files in parallel. The default is to not use multiple workers.If the platform can't use multiple workers and workers argument is given,then sequential compilation will be used as a fallback. If workers_is 0, the number of cores in the system is used. If _workers islower than 0, a ValueError will be raised.

invalidation_mode should be a member of thepy_compile.PycInvalidationMode enum and controls how the generatedpycs are invalidated at runtime.

在 3.2 版更改: Added the legacy and optimize parameter.

在 3.5 版更改: Added the workers parameter.

在 3.5 版更改: quiet parameter was changed to a multilevel value.

在 3.5 版更改: The legacy parameter only writes out .pyc files, not .pyo filesno matter what the value of optimize is.

在 3.6 版更改: 接受一个 类路径对象

在 3.7 版更改: The invalidation_mode parameter was added.

在 3.7.2 版更改: The invalidation_mode parameter's default value is updated to None.

在 3.8 版更改: Setting workers to 0 now chooses the optimal number of cores.

  • compileall.compilefile(_fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)
  • Compile the file with path fullname. Return a true value if the filecompiled successfully, and a false value otherwise.

If ddir is given, it is prepended to the path to the file being compiledfor use in compilation time tracebacks, and is also compiled in to thebyte-code file, where it will be used in tracebacks and other messages incases where the source file does not exist at the time the byte-code file isexecuted.

If rx is given, its search method is passed the full path name to thefile being compiled, and if it returns a true value, the file is notcompiled and True is returned.

If quiet is False or 0 (the default), the filenames and otherinformation are printed to standard out. Set to 1, only errors areprinted. Set to 2, all output is suppressed.

If legacy is true, byte-code files are written to their legacy locationsand names, which may overwrite byte-code files created by another version ofPython. The default is to write files to their PEP 3147 locations andnames, which allows byte-code files from multiple versions of Python tocoexist.

optimize specifies the optimization level for the compiler. It is passed tothe built-in compile() function.

invalidation_mode should be a member of thepy_compile.PycInvalidationMode enum and controls how the generatedpycs are invalidated at runtime.

3.2 新版功能.

在 3.5 版更改: quiet parameter was changed to a multilevel value.

在 3.5 版更改: The legacy parameter only writes out .pyc files, not .pyo filesno matter what the value of optimize is.

在 3.7 版更改: The invalidation_mode parameter was added.

在 3.7.2 版更改: The invalidation_mode parameter's default value is updated to None.

  • compileall.compilepath(_skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)
  • Byte-compile all the .py files found along sys.path. Return atrue value if all the files compiled successfully, and a false value otherwise.

If skip_curdir is true (the default), the current directory is not includedin the search. All other parameters are passed to the compile_dir()function. Note that unlike the other compile functions, maxlevelsdefaults to 0.

在 3.2 版更改: Added the legacy and optimize parameter.

在 3.5 版更改: quiet parameter was changed to a multilevel value.

在 3.5 版更改: The legacy parameter only writes out .pyc files, not .pyo filesno matter what the value of optimize is.

在 3.7 版更改: The invalidation_mode parameter was added.

在 3.7.2 版更改: The invalidation_mode parameter's default value is updated to None.

To force a recompile of all the .py files in the Lib/subdirectory and all its subdirectories:

  1. import compileall
  2.  
  3. compileall.compile_dir('Lib/', force=True)
  4.  
  5. # Perform same compilation, excluding files in .svn directories.
  6. import re
  7. compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)
  8.  
  9. # pathlib.Path objects can also be used.
  10. import pathlib
  11. compileall.compile_dir(pathlib.Path('Lib/'), force=True)

参见

  • 模块 py_compile
  • Byte-compile a single source file.