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