Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`py_compile` --- Compile Python source files |
| 2 | ================================================= |
| 3 | |
| 4 | .. module:: py_compile |
| 5 | :synopsis: Generate byte-code files from Python source files. |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 6 | .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
| 7 | .. documentation based on module docstrings |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | |
| 9 | .. index:: pair: file; byte-code |
| 10 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 11 | **Source code:** :source:`Lib/py_compile.py` |
| 12 | |
| 13 | -------------- |
| 14 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 15 | The :mod:`py_compile` module provides a function to generate a byte-code file |
| 16 | from a source file, and another function used when the module source file is |
| 17 | invoked as a script. |
| 18 | |
| 19 | Though not often needed, this function can be useful when installing modules for |
| 20 | shared use, especially if some of the users may not have permission to write the |
| 21 | byte-code cache files in the directory containing the source code. |
| 22 | |
| 23 | |
| 24 | .. exception:: PyCompileError |
| 25 | |
| 26 | Exception raised when an error occurs while attempting to compile the file. |
| 27 | |
| 28 | |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 29 | .. function:: compile(file, cfile=None, dfile=None, doraise=False, optimize=-1) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 30 | |
Brett Cannon | aa73a1c | 2013-03-13 09:37:42 -0700 | [diff] [blame] | 31 | Compile a source file to byte-code and write out the byte-code cache file. |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 32 | The source code is loaded from the file name *file*. The byte-code is |
| 33 | written to *cfile*, which defaults to the :PEP:`3147` path, ending in |
| 34 | ``.pyc`` (``.pyo`` if optimization is enabled in the current interpreter). |
| 35 | For example, if *file* is ``/foo/bar/baz.py`` *cfile* will default to |
| 36 | ``/foo/bar/__pycache__/baz.cpython-32.pyc`` for Python 3.2. If *dfile* is |
| 37 | specified, it is used as the name of the source file in error messages when |
| 38 | instead of *file*. If *doraise* is true, a :exc:`PyCompileError` is raised |
| 39 | when an error is encountered while compiling *file*. If *doraise* is false |
| 40 | (the default), an error string is written to ``sys.stderr``, but no exception |
| 41 | is raised. This function returns the path to byte-compiled file, i.e. |
| 42 | whatever *cfile* value was used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | |
Brett Cannon | 33915eb | 2013-06-14 18:33:00 -0400 | [diff] [blame] | 44 | If the path that *cfile* becomes (either explicitly specified or computed) |
| 45 | is a symlink or non-regular file, :exc:`FileExistsError` will be raised. |
| 46 | This is to act as a warning that import will turn those paths into regular |
| 47 | files if it is allowed to write byte-compiled files to those paths. This is |
| 48 | a side-effect of import using file renaming to place the final byte-compiled |
| 49 | file into place to prevent concurrent file writing issues. |
| 50 | |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 51 | *optimize* controls the optimization level and is passed to the built-in |
| 52 | :func:`compile` function. The default of ``-1`` selects the optimization |
| 53 | level of the current interpreter. |
| 54 | |
| 55 | .. versionchanged:: 3.2 |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 56 | Changed default value of *cfile* to be :PEP:`3147`-compliant. Previous |
| 57 | default was *file* + ``'c'`` (``'o'`` if optimization was enabled). |
| 58 | Also added the *optimize* parameter. |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 59 | |
Brett Cannon | aa73a1c | 2013-03-13 09:37:42 -0700 | [diff] [blame] | 60 | .. versionchanged:: 3.4 |
| 61 | Changed code to use :mod:`importlib` for the byte-code cache file writing. |
| 62 | This means file creation/writing semantics now match what :mod:`importlib` |
Brett Cannon | 33915eb | 2013-06-14 18:33:00 -0400 | [diff] [blame] | 63 | does, e.g. permissions, write-and-move semantics, etc. Also added the |
| 64 | caveat that :exc:`FileExistsError` is raised if *cfile* is a symlink or |
| 65 | non-regular file. |
Brett Cannon | aa73a1c | 2013-03-13 09:37:42 -0700 | [diff] [blame] | 66 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 67 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 68 | .. function:: main(args=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
| 70 | Compile several source files. The files named in *args* (or on the command |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 71 | line, if *args* is ``None``) are compiled and the resulting bytecode is |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | cached in the normal manner. This function does not search a directory |
| 73 | structure to locate source files; it only compiles files named explicitly. |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 74 | If ``'-'`` is the only parameter in args, the list of files is taken from |
| 75 | standard input. |
| 76 | |
| 77 | .. versionchanged:: 3.2 |
| 78 | Added support for ``'-'``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | |
| 80 | When this module is run as a script, the :func:`main` is used to compile all the |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 81 | files named on the command line. The exit status is nonzero if one of the files |
| 82 | could not be compiled. |
| 83 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
| 85 | .. seealso:: |
| 86 | |
| 87 | Module :mod:`compileall` |
| 88 | Utilities to compile all Python source files in a directory tree. |
| 89 | |