Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | c0a8f8c | 2014-10-02 08:38:39 +0200 | [diff] [blame] | 7 | **Source code:** :source:`Lib/compileall.py` |
| 8 | |
| 9 | -------------- |
| 10 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 11 | |
| 12 | This module provides some utility functions to support installing Python |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 13 | libraries. These functions compile Python source files in a directory tree. |
| 14 | This module can be used to create the cached byte-code files at library |
| 15 | installation time, which makes them available for use even by users who don't |
| 16 | have write permission to the library directories. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 17 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 18 | |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 19 | Command-line use |
| 20 | ---------------- |
| 21 | |
| 22 | This module can work as a script (using :program:`python -m compileall`) to |
| 23 | compile Python sources. |
| 24 | |
| 25 | .. program:: compileall |
| 26 | |
Georg Brandl | f5c801f | 2014-03-18 07:44:07 +0100 | [diff] [blame] | 27 | .. cmdoption:: directory ... |
| 28 | file ... |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 29 | |
| 30 | Positional arguments are files to compile or directories that contain |
| 31 | source files, traversed recursively. If no argument is given, behave as if |
| 32 | the command line was ``-l <directories from sys.path>``. |
| 33 | |
| 34 | .. cmdoption:: -l |
| 35 | |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 36 | Do not recurse into subdirectories, only compile source code files directly |
| 37 | contained in the named or implied directories. |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 38 | |
| 39 | .. cmdoption:: -f |
| 40 | |
| 41 | Force rebuild even if timestamps are up-to-date. |
| 42 | |
| 43 | .. cmdoption:: -q |
| 44 | |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 45 | Do not print the list of files compiled, print only error messages. |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 46 | |
| 47 | .. cmdoption:: -d destdir |
| 48 | |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 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. |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 54 | |
| 55 | .. cmdoption:: -x regex |
| 56 | |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 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. |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 59 | |
| 60 | .. cmdoption:: -i list |
| 61 | |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 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``. |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 65 | |
| 66 | .. cmdoption:: -b |
| 67 | |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 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. |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 72 | |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 73 | .. versionchanged:: 3.2 |
| 74 | Added the ``-i``, ``-b`` and ``-h`` options. |
Éric Araujo | f68fa05 | 2010-12-16 02:10:11 +0000 | [diff] [blame] | 75 | |
Éric Araujo | 01606de | 2011-03-26 03:22:55 +0100 | [diff] [blame] | 76 | There is no command-line option to control the optimization level used by the |
| 77 | :func:`compile` function, because the Python interpreter itself already |
| 78 | provides the option: :program:`python -O -m compileall`. |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 79 | |
| 80 | Public functions |
| 81 | ---------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 82 | |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 83 | .. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=False, legacy=False, optimize=-1) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
| 85 | Recursively descend the directory tree named by *dir*, compiling all :file:`.py` |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 86 | files along the way. |
| 87 | |
| 88 | The *maxlevels* parameter is used to limit the depth of the recursion; it |
| 89 | defaults to ``10``. |
| 90 | |
| 91 | If *ddir* is given, it is prepended to the path to each file being compiled |
| 92 | for use in compilation time tracebacks, and is also compiled in to the |
| 93 | byte-code file, where it will be used in tracebacks and other messages in |
| 94 | cases where the source file does not exist at the time the byte-code file is |
| 95 | executed. |
| 96 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 97 | If *force* is true, modules are re-compiled even if the timestamps are up to |
| 98 | date. |
| 99 | |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 100 | If *rx* is given, its search method is called on the complete path to each |
| 101 | file considered for compilation, and if it returns a true value, the file |
| 102 | is skipped. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 103 | |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 104 | If *quiet* is true, nothing is printed to the standard output unless errors |
| 105 | occur. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 106 | |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 107 | If *legacy* is true, byte-code files are written to their legacy locations |
| 108 | and names, which may overwrite byte-code files created by another version of |
| 109 | Python. The default is to write files to their :pep:`3147` locations and |
| 110 | names, which allows byte-code files from multiple versions of Python to |
| 111 | coexist. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 112 | |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 113 | *optimize* specifies the optimization level for the compiler. It is passed to |
| 114 | the built-in :func:`compile` function. |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 115 | |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 116 | .. versionchanged:: 3.2 |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 117 | Added the *legacy* and *optimize* parameter. |
| 118 | |
| 119 | |
| 120 | .. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=False, legacy=False, optimize=-1) |
| 121 | |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 122 | Compile the file with path *fullname*. |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 123 | |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 124 | If *ddir* is given, it is prepended to the path to the file being compiled |
| 125 | for use in compilation time tracebacks, and is also compiled in to the |
| 126 | byte-code file, where it will be used in tracebacks and other messages in |
| 127 | cases where the source file does not exist at the time the byte-code file is |
| 128 | executed. |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 129 | |
R. David Murray | 8b24aac | 2011-02-11 22:37:16 +0000 | [diff] [blame] | 130 | If *rx* is given, its search method is passed the full path name to the |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 131 | file being compiled, and if it returns a true value, the file is not |
| 132 | compiled and ``True`` is returned. |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 133 | |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 134 | If *quiet* is true, nothing is printed to the standard output unless errors |
| 135 | occur. |
| 136 | |
| 137 | If *legacy* is true, byte-code files are written to their legacy locations |
| 138 | and names, which may overwrite byte-code files created by another version of |
| 139 | Python. The default is to write files to their :pep:`3147` locations and |
| 140 | names, which allows byte-code files from multiple versions of Python to |
| 141 | coexist. |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 142 | |
| 143 | *optimize* specifies the optimization level for the compiler. It is passed to |
| 144 | the built-in :func:`compile` function. |
| 145 | |
| 146 | .. versionadded:: 3.2 |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 147 | |
| 148 | |
| 149 | .. function:: compile_path(skip_curdir=True, maxlevels=0, force=False, legacy=False, optimize=-1) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 150 | |
| 151 | Byte-compile all the :file:`.py` files found along ``sys.path``. If |
R. David Murray | 94f58c3 | 2010-12-17 16:29:07 +0000 | [diff] [blame] | 152 | *skip_curdir* is true (the default), the current directory is not included |
| 153 | in the search. All other parameters are passed to the :func:`compile_dir` |
| 154 | function. Note that unlike the other compile functions, ``maxlevels`` |
| 155 | defaults to ``0``. |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 156 | |
| 157 | .. versionchanged:: 3.2 |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 158 | Added the *legacy* and *optimize* parameter. |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 159 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 160 | |
| 161 | To force a recompile of all the :file:`.py` files in the :file:`Lib/` |
| 162 | subdirectory and all its subdirectories:: |
| 163 | |
| 164 | import compileall |
| 165 | |
| 166 | compileall.compile_dir('Lib/', force=True) |
| 167 | |
| 168 | # Perform same compilation, excluding files in .svn directories. |
| 169 | import re |
Georg Brandl | 1aca953 | 2013-04-14 12:02:43 +0200 | [diff] [blame] | 170 | compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 171 | |
| 172 | |
| 173 | .. seealso:: |
| 174 | |
| 175 | Module :mod:`py_compile` |
| 176 | Byte-compile a single source file. |