
``compileall`` --- Byte-compile Python libraries
************************************************

This module provides some utility functions to support installing
Python 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
================

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

[directory|file]...

   Positional arguments are files to compile or directories that
   contain source files, traversed recursively.  If no argument is
   given, behave as if the command line was ``-l <directories from
   sys.path>``.

-l

   Do not recurse into subdirectories, only compile source code files
   directly contained 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, print only error messages.

-d destdir

   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.

-x regex

   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.

-i list

   Read the file ``list`` and add each line that it contains to the
   list of files and directories to compile.  If ``list`` is ``-``,
   read lines from ``stdin``.

-b

   Write the byte-code files to their legacy locations and names,
   which may overwrite byte-code files created by another version of
   Python.  The default is to write files to their **PEP 3147**
   locations and names, which allows byte-code files from multiple
   versions of Python to coexist.

Changed in version 3.2: Added the ``-i``, ``-b`` and ``-h`` options.

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


Public functions
================

compileall.compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=False, legacy=False, optimize=-1)

   Recursively descend the directory tree named by *dir*, compiling
   all ``.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 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, 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
   unless errors occur.

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

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

   Changed in version 3.2: Added the *legacy* and *optimize*
   parameter.

compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=False, legacy=False, optimize=-1)

   Compile the file with path *fullname*.

   If *ddir* is given, it is prepended to the path to the 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 *rx* is given, its search method is passed the full path name to
   the file being compiled, and if it returns a true value, the file
   is not compiled and ``True`` is returned.

   If *quiet* is true, nothing is printed to the standard output
   unless errors occur.

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

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

   New in version 3.2.

compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, legacy=False, optimize=-1)

   Byte-compile all the ``.py`` files found along ``sys.path``. If
   *skip_curdir* is true (the default), the current directory is not
   included in the search.  All other parameters are passed to the
   ``compile_dir()`` function.  Note that unlike the other compile
   functions, ``maxlevels`` defaults to ``0``.

   Changed in version 3.2: Added the *legacy* and *optimize*
   parameter.

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

   import compileall

   compileall.compile_dir('Lib/', force=True)

   # Perform same compilation, excluding files in .svn directories.
   import re
   compileall.compile_dir('Lib/', rx=re.compile('/[.]svn'), force=True)

See also:

   Module ``py_compile``
      Byte-compile a single source file.
