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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
: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, quiet=0)
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 instead of *file* as the name of the source file from
which source lines are obtained for display in exception tracebacks.
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.
The *doraise* and *quiet* arguments determine how errors are handled while
compiling file. If *quiet* is 0 or 1, and *doraise* is false, the default
behaviour is enabled: an error string is written to ``sys.stderr``, and the
function returns ``None`` instead of a path. If *doraise* is true,
a :exc:`PyCompileError` is raised instead. However if *quiet* is 2,
no message is written, and *doraise* has no effect.
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 bytecode cache is invalidated at
runtime. The default is :attr:`PycInvalidationMode.CHECKED_HASH` if
the :envvar:`SOURCE_DATE_EPOCH` environment variable is set, otherwise
the default is :attr:`PycInvalidationMode.TIMESTAMP`.
.. 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`.
.. versionchanged:: 3.7.2
The :envvar:`SOURCE_DATE_EPOCH` environment variable no longer
overrides the value of the *invalidation_mode* argument, and determines
its default value instead.
.. versionchanged:: 3.8
The *quiet* parameter was added.
.. class:: PycInvalidationMode
An 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.
.. _py_compile-cli:
Command-Line Interface
----------------------
This module can be invoked as a script to compile several source
files. The files named in *filenames* are compiled and the resulting
bytecode is cached in the normal manner. This program does not search
a directory structure to locate source files; it only compiles files
named explicitly. The exit status is nonzero if one of the files could
not be compiled.
.. program:: python -m py_compile
.. option:: <file> ... <fileN>
-
Positional arguments are files to compile. If ``-`` is the only
parameter, the list of files is taken from standard input.
.. option:: -q, --quiet
Suppress errors output.
.. versionchanged:: 3.2
Added support for ``-``.
.. versionchanged:: 3.10
Added support for :option:`-q`.
.. seealso::
Module :mod:`compileall`
Utilities to compile all Python source files in a directory tree.
|
