blob: cb7a09c0fb03bc8405a88dd2158ca7a53ce03bb3 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001: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
8This module provides some utility functions to support installing Python
R. David Murray94f58c32010-12-17 16:29:07 +00009libraries. These functions compile Python source files in a directory tree.
10This module can be used to create the cached byte-code files at library
11installation time, which makes them available for use even by users who don't
12have write permission to the library directories.
Georg Brandl116aa622007-08-15 14:28:22 +000013
Georg Brandl116aa622007-08-15 14:28:22 +000014
Éric Araujo713d3032010-11-18 16:38:46 +000015Command-line use
16----------------
17
18This module can work as a script (using :program:`python -m compileall`) to
19compile Python sources.
20
21.. program:: compileall
22
23.. cmdoption:: [directory|file]...
24
25 Positional arguments are files to compile or directories that contain
26 source files, traversed recursively. If no argument is given, behave as if
27 the command line was ``-l <directories from sys.path>``.
28
29.. cmdoption:: -l
30
R. David Murray94f58c32010-12-17 16:29:07 +000031 Do not recurse into subdirectories, only compile source code files directly
32 contained in the named or implied directories.
Éric Araujo713d3032010-11-18 16:38:46 +000033
34.. cmdoption:: -f
35
36 Force rebuild even if timestamps are up-to-date.
37
38.. cmdoption:: -q
39
R. David Murray94f58c32010-12-17 16:29:07 +000040 Do not print the list of files compiled, print only error messages.
Éric Araujo713d3032010-11-18 16:38:46 +000041
42.. cmdoption:: -d destdir
43
R. David Murray94f58c32010-12-17 16:29:07 +000044 Directory prepended to the path to each file being compiled. This will
45 appear in compilation time tracebacks, and is also compiled in to the
46 byte-code file, where it will be used in tracebacks and other messages in
47 cases where the source file does not exist at the time the byte-code file is
48 executed.
Éric Araujo713d3032010-11-18 16:38:46 +000049
50.. cmdoption:: -x regex
51
R. David Murray94f58c32010-12-17 16:29:07 +000052 regex is used to search the full path to each file considered for
53 compilation, and if the regex produces a match, the file is skipped.
Éric Araujo713d3032010-11-18 16:38:46 +000054
55.. cmdoption:: -i list
56
R. David Murray94f58c32010-12-17 16:29:07 +000057 Read the file ``list`` and add each line that it contains to the list of
58 files and directories to compile. If ``list`` is ``-``, read lines from
59 ``stdin``.
Éric Araujo713d3032010-11-18 16:38:46 +000060
61.. cmdoption:: -b
62
R. David Murray94f58c32010-12-17 16:29:07 +000063 Write the byte-code files to their legacy locations and names, which may
64 overwrite byte-code files created by another version of Python. The default
65 is to write files to their :pep:`3147` locations and names, which allows
66 byte-code files from multiple versions of Python to coexist.
Éric Araujo713d3032010-11-18 16:38:46 +000067
Éric Araujo930df312010-12-16 06:28:48 +000068.. versionchanged:: 3.2
69 Added the ``-i``, ``-b`` and ``-h`` options.
Éric Araujof68fa052010-12-16 02:10:11 +000070
Éric Araujo01606de2011-03-26 03:22:55 +010071There is no command-line option to control the optimization level used by the
72:func:`compile` function, because the Python interpreter itself already
73provides the option: :program:`python -O -m compileall`.
Éric Araujo713d3032010-11-18 16:38:46 +000074
75Public functions
76----------------
Georg Brandl116aa622007-08-15 14:28:22 +000077
Georg Brandl8334fd92010-12-04 10:26:46 +000078.. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=False, legacy=False, optimize=-1)
Georg Brandl116aa622007-08-15 14:28:22 +000079
80 Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
R. David Murray94f58c32010-12-17 16:29:07 +000081 files along the way.
82
83 The *maxlevels* parameter is used to limit the depth of the recursion; it
84 defaults to ``10``.
85
86 If *ddir* is given, it is prepended to the path to each file being compiled
87 for use in compilation time tracebacks, and is also compiled in to the
88 byte-code file, where it will be used in tracebacks and other messages in
89 cases where the source file does not exist at the time the byte-code file is
90 executed.
91
Georg Brandl116aa622007-08-15 14:28:22 +000092 If *force* is true, modules are re-compiled even if the timestamps are up to
93 date.
94
R. David Murray94f58c32010-12-17 16:29:07 +000095 If *rx* is given, its search method is called on the complete path to each
96 file considered for compilation, and if it returns a true value, the file
97 is skipped.
Georg Brandl116aa622007-08-15 14:28:22 +000098
R. David Murray94f58c32010-12-17 16:29:07 +000099 If *quiet* is true, nothing is printed to the standard output unless errors
100 occur.
Georg Brandl116aa622007-08-15 14:28:22 +0000101
R. David Murray94f58c32010-12-17 16:29:07 +0000102 If *legacy* is true, byte-code files are written to their legacy locations
103 and names, which may overwrite byte-code files created by another version of
104 Python. The default is to write files to their :pep:`3147` locations and
105 names, which allows byte-code files from multiple versions of Python to
106 coexist.
Georg Brandl116aa622007-08-15 14:28:22 +0000107
Georg Brandl8334fd92010-12-04 10:26:46 +0000108 *optimize* specifies the optimization level for the compiler. It is passed to
109 the built-in :func:`compile` function.
Barry Warsaw28a691b2010-04-17 00:19:56 +0000110
Georg Brandl8334fd92010-12-04 10:26:46 +0000111 .. versionchanged:: 3.2
Éric Araujo930df312010-12-16 06:28:48 +0000112 Added the *legacy* and *optimize* parameter.
113
114
115.. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=False, legacy=False, optimize=-1)
116
R. David Murray94f58c32010-12-17 16:29:07 +0000117 Compile the file with path *fullname*.
Éric Araujo930df312010-12-16 06:28:48 +0000118
R. David Murray94f58c32010-12-17 16:29:07 +0000119 If *ddir* is given, it is prepended to the path to the file being compiled
120 for use in compilation time tracebacks, and is also compiled in to the
121 byte-code file, where it will be used in tracebacks and other messages in
122 cases where the source file does not exist at the time the byte-code file is
123 executed.
Éric Araujo930df312010-12-16 06:28:48 +0000124
R. David Murray8b24aac2011-02-11 22:37:16 +0000125 If *rx* is given, its search method is passed the full path name to the
R. David Murray94f58c32010-12-17 16:29:07 +0000126 file being compiled, and if it returns a true value, the file is not
127 compiled and ``True`` is returned.
Éric Araujo930df312010-12-16 06:28:48 +0000128
R. David Murray94f58c32010-12-17 16:29:07 +0000129 If *quiet* is true, nothing is printed to the standard output unless errors
130 occur.
131
132 If *legacy* is true, byte-code files are written to their legacy locations
133 and names, which may overwrite byte-code files created by another version of
134 Python. The default is to write files to their :pep:`3147` locations and
135 names, which allows byte-code files from multiple versions of Python to
136 coexist.
Éric Araujo930df312010-12-16 06:28:48 +0000137
138 *optimize* specifies the optimization level for the compiler. It is passed to
139 the built-in :func:`compile` function.
140
141 .. versionadded:: 3.2
Georg Brandl8334fd92010-12-04 10:26:46 +0000142
143
144.. function:: compile_path(skip_curdir=True, maxlevels=0, force=False, legacy=False, optimize=-1)
Georg Brandl116aa622007-08-15 14:28:22 +0000145
146 Byte-compile all the :file:`.py` files found along ``sys.path``. If
R. David Murray94f58c32010-12-17 16:29:07 +0000147 *skip_curdir* is true (the default), the current directory is not included
148 in the search. All other parameters are passed to the :func:`compile_dir`
149 function. Note that unlike the other compile functions, ``maxlevels``
150 defaults to ``0``.
Georg Brandl8334fd92010-12-04 10:26:46 +0000151
152 .. versionchanged:: 3.2
Éric Araujo930df312010-12-16 06:28:48 +0000153 Added the *legacy* and *optimize* parameter.
Georg Brandl8334fd92010-12-04 10:26:46 +0000154
Georg Brandl116aa622007-08-15 14:28:22 +0000155
156To force a recompile of all the :file:`.py` files in the :file:`Lib/`
157subdirectory and all its subdirectories::
158
159 import compileall
160
161 compileall.compile_dir('Lib/', force=True)
162
163 # Perform same compilation, excluding files in .svn directories.
164 import re
165 compileall.compile_dir('Lib/', rx=re.compile('/[.]svn'), force=True)
166
167
168.. seealso::
169
170 Module :mod:`py_compile`
171 Byte-compile a single source file.