summaryrefslogtreecommitdiffstats
path: root/Doc/library/py_compile.rst
blob: d720e01050577df465bd6522bee19436b0232e45 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
:mod:`py_compile` --- Compile Python source files
=================================================

.. module:: py_compile
   :synopsis: Generate byte-code files from Python source files.

.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. documentation based on module docstrings

**Source code:** :source:`Lib/py_compile.py`

.. index:: pair: file; byte-code

--------------

The :mod:`py_compile` module provides a function to generate a byte-code file
from a source file, and another function used when the module source file is
invoked as a script.

Though not often needed, this function can be useful when installing modules for
shared use, especially if some of the users may not have permission to write the
byte-code cache files in the directory containing the source code.


.. exception:: PyCompileError

   Exception raised when an error occurs while attempting to compile the file.


.. function:: compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP)

   Compile a source file to byte-code and write out the byte-code cache file.
   The source code is loaded from the file named *file*.  The byte-code is
   written to *cfile*, which defaults to the :pep:`3147`/:pep:`488` path, ending
   in ``.pyc``.
   For example, if *file* is ``/foo/bar/baz.py`` *cfile* will default to
   ``/foo/bar/__pycache__/baz.cpython-32.pyc`` for Python 3.2.  If *dfile* is
   specified, it is used as the name of the source file in error messages when
   instead of *file*.  If *doraise* is true, a :exc:`PyCompileError` is raised
   when an error is encountered while compiling *file*. If *doraise* is false
   (the default), an error string is written to ``sys.stderr``, but no exception
   is raised.  This function returns the path to byte-compiled file, i.e.
   whatever *cfile* value was used.

   If the path that *cfile* becomes (either explicitly specified or computed)
   is a symlink or non-regular file, :exc:`FileExistsError` will be raised.
   This is to act as a warning that import will turn those paths into regular
   files if it is allowed to write byte-compiled files to those paths. This is
   a side-effect of import using file renaming to place the final byte-compiled
   file into place to prevent concurrent file writing issues.

   *optimize* controls the optimization level and is passed to the built-in
   :func:`compile` function.  The default of ``-1`` selects the optimization
   level of the current interpreter.

   *invalidation_mode* should be a member of the :class:`PycInvalidationMode`
   enum and controls how the generated ``.pyc`` files are invalidated at
   runtime. If the :envvar:`SOURCE_DATE_EPOCH` environment variable is set,
   *invalidation_mode* will be forced to
   :attr:`PycInvalidationMode.CHECKED_HASH`.

   .. versionchanged:: 3.2
      Changed default value of *cfile* to be :PEP:`3147`-compliant.  Previous
      default was *file* + ``'c'`` (``'o'`` if optimization was enabled).
      Also added the *optimize* parameter.

   .. versionchanged:: 3.4
      Changed code to use :mod:`importlib` for the byte-code cache file writing.
      This means file creation/writing semantics now match what :mod:`importlib`
      does, e.g. permissions, write-and-move semantics, etc. Also added the
      caveat that :exc:`FileExistsError` is raised if *cfile* is a symlink or
      non-regular file.

   .. versionchanged:: 3.7
      The *invalidation_mode* parameter was added as specified in :pep:`552`.
      If the :envvar:`SOURCE_DATE_EPOCH` environment variable is set,
      *invalidation_mode* will be forced to
      :attr:`PycInvalidationMode.CHECKED_HASH`.


.. class:: PycInvalidationMode

   A enumeration of possible methods the interpreter can use to determine
   whether a bytecode file is up to date with a source file. The ``.pyc`` file
   indicates the desired invalidation mode in its header. See
   :ref:`pyc-invalidation` for more information on how Python invalidates
   ``.pyc`` files at runtime.

   .. versionadded:: 3.7

   .. attribute:: TIMESTAMP

      The ``.pyc`` file includes the timestamp and size of the source file,
      which Python will compare against the metadata of the source file at
      runtime to determine if the ``.pyc`` file needs to be regenerated.

   .. attribute:: CHECKED_HASH

      The ``.pyc`` file includes a hash of the source file content, which Python
      will compare against the source at runtime to determine if the ``.pyc``
      file needs to be regenerated.

   .. attribute:: UNCHECKED_HASH

      Like :attr:`CHECKED_HASH`, the ``.pyc`` file includes a hash of the source
      file content. However, Python will at runtime assume the ``.pyc`` file is
      up to date and not validate the ``.pyc`` against the source file at all.

      This option is useful when the ``.pycs`` are kept up to date by some
      system external to Python like a build system.


.. function:: main(args=None)

   Compile several source files.  The files named in *args* (or on the command
   line, if *args* is ``None``) are compiled and the resulting byte-code is
   cached in the normal manner.  This function does not search a directory
   structure to locate source files; it only compiles files named explicitly.
   If ``'-'`` is the only parameter in args, the list of files is taken from
   standard input.

   .. versionchanged:: 3.2
      Added support for ``'-'``.

When this module is run as a script, the :func:`main` is used to compile all the
files named on the command line.  The exit status is nonzero if one of the files
could not be compiled.


.. seealso::

   Module :mod:`compileall`
      Utilities to compile all Python source files in a directory tree.