1:mod:`py_compile` --- Compile Python source files
2=================================================
3
4.. module:: py_compile
5   :synopsis: Generate byte-code files from Python source files.
6
7.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
8.. documentation based on module docstrings
9
10**Source code:** :source:`Lib/py_compile.py`
11
12.. index:: pair: file; byte-code
13
14--------------
15
16The :mod:`py_compile` module provides a function to generate a byte-code file
17from a source file, and another function used when the module source file is
18invoked as a script.
19
20Though not often needed, this function can be useful when installing modules for
21shared use, especially if some of the users may not have permission to write the
22byte-code cache files in the directory containing the source code.
23
24
25.. exception:: PyCompileError
26
27   Exception raised when an error occurs while attempting to compile the file.
28
29
30.. function:: compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)
31
32   Compile a source file to byte-code and write out the byte-code cache file.
33   The source code is loaded from the file named *file*.  The byte-code is
34   written to *cfile*, which defaults to the :pep:`3147`/:pep:`488` path, ending
35   in ``.pyc``.
36   For example, if *file* is ``/foo/bar/baz.py`` *cfile* will default to
37   ``/foo/bar/__pycache__/baz.cpython-32.pyc`` for Python 3.2.  If *dfile* is
38   specified, it is used as the name of the source file in error messages
39   instead of *file*.  If *doraise* is true, a :exc:`PyCompileError` is raised
40   when an error is encountered while compiling *file*. If *doraise* is false
41   (the default), an error string is written to ``sys.stderr``, but no exception
42   is raised.  This function returns the path to byte-compiled file, i.e.
43   whatever *cfile* value was used.
44
45   The *doraise* and *quiet* arguments determine how errors are handled while
46   compiling file. If *quiet* is 0 or 1, and *doraise* is false, the default
47   behaviour is enabled: an error string is written to ``sys.stderr``, and the
48   function returns ``None`` instead of a path. If *doraise* is true,
49   a :exc:`PyCompileError` is raised instead. However if *quiet* is 2,
50   no message is written, and *doraise* has no effect.
51
52   If the path that *cfile* becomes (either explicitly specified or computed)
53   is a symlink or non-regular file, :exc:`FileExistsError` will be raised.
54   This is to act as a warning that import will turn those paths into regular
55   files if it is allowed to write byte-compiled files to those paths. This is
56   a side-effect of import using file renaming to place the final byte-compiled
57   file into place to prevent concurrent file writing issues.
58
59   *optimize* controls the optimization level and is passed to the built-in
60   :func:`compile` function.  The default of ``-1`` selects the optimization
61   level of the current interpreter.
62
63   *invalidation_mode* should be a member of the :class:`PycInvalidationMode`
64   enum and controls how the generated bytecode cache is invalidated at
65   runtime.  The default is :attr:`PycInvalidationMode.CHECKED_HASH` if
66   the :envvar:`SOURCE_DATE_EPOCH` environment variable is set, otherwise
67   the default is :attr:`PycInvalidationMode.TIMESTAMP`.
68
69   .. versionchanged:: 3.2
70      Changed default value of *cfile* to be :PEP:`3147`-compliant.  Previous
71      default was *file* + ``'c'`` (``'o'`` if optimization was enabled).
72      Also added the *optimize* parameter.
73
74   .. versionchanged:: 3.4
75      Changed code to use :mod:`importlib` for the byte-code cache file writing.
76      This means file creation/writing semantics now match what :mod:`importlib`
77      does, e.g. permissions, write-and-move semantics, etc. Also added the
78      caveat that :exc:`FileExistsError` is raised if *cfile* is a symlink or
79      non-regular file.
80
81   .. versionchanged:: 3.7
82      The *invalidation_mode* parameter was added as specified in :pep:`552`.
83      If the :envvar:`SOURCE_DATE_EPOCH` environment variable is set,
84      *invalidation_mode* will be forced to
85      :attr:`PycInvalidationMode.CHECKED_HASH`.
86
87   .. versionchanged:: 3.7.2
88      The :envvar:`SOURCE_DATE_EPOCH` environment variable no longer
89      overrides the value of the *invalidation_mode* argument, and determines
90      its default value instead.
91
92   .. versionchanged:: 3.8
93      The *quiet* parameter was added.
94
95
96.. class:: PycInvalidationMode
97
98   A enumeration of possible methods the interpreter can use to determine
99   whether a bytecode file is up to date with a source file. The ``.pyc`` file
100   indicates the desired invalidation mode in its header. See
101   :ref:`pyc-invalidation` for more information on how Python invalidates
102   ``.pyc`` files at runtime.
103
104   .. versionadded:: 3.7
105
106   .. attribute:: TIMESTAMP
107
108      The ``.pyc`` file includes the timestamp and size of the source file,
109      which Python will compare against the metadata of the source file at
110      runtime to determine if the ``.pyc`` file needs to be regenerated.
111
112   .. attribute:: CHECKED_HASH
113
114      The ``.pyc`` file includes a hash of the source file content, which Python
115      will compare against the source at runtime to determine if the ``.pyc``
116      file needs to be regenerated.
117
118   .. attribute:: UNCHECKED_HASH
119
120      Like :attr:`CHECKED_HASH`, the ``.pyc`` file includes a hash of the source
121      file content. However, Python will at runtime assume the ``.pyc`` file is
122      up to date and not validate the ``.pyc`` against the source file at all.
123
124      This option is useful when the ``.pycs`` are kept up to date by some
125      system external to Python like a build system.
126
127
128.. function:: main(args=None)
129
130   Compile several source files.  The files named in *args* (or on the command
131   line, if *args* is ``None``) are compiled and the resulting byte-code is
132   cached in the normal manner.  This function does not search a directory
133   structure to locate source files; it only compiles files named explicitly.
134   If ``'-'`` is the only parameter in args, the list of files is taken from
135   standard input.
136
137   .. versionchanged:: 3.2
138      Added support for ``'-'``.
139
140When this module is run as a script, the :func:`main` is used to compile all the
141files named on the command line.  The exit status is nonzero if one of the files
142could not be compiled.
143
144
145.. seealso::
146
147   Module :mod:`compileall`
148      Utilities to compile all Python source files in a directory tree.
149