path: root/devdocs/python~3.12/library%2Fpy_compile.html

 <span id="py-compile-compile-python-source-files"></span><h1>py_compile — Compile Python source files</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/py_compile.py">Lib/py_compile.py</a></p>  <p>The <a class="reference internal" href="#module-py_compile" title="py_compile: Generate byte-code files from Python source files."><code>py_compile</code></a> 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.</p> <p>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.</p> <dl class="py exception"> <dt class="sig sig-object py" id="py_compile.PyCompileError">
<code>exception py_compile.PyCompileError</code> </dt> <dd>
<p>Exception raised when an error occurs while attempting to compile the file.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="py_compile.compile">
<code>py_compile.compile(file, cfile=None, dfile=None, doraise=False, optimize=- 1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)</code> </dt> <dd>
<p>Compile a source file to byte-code and write out the byte-code cache file. The source code is loaded from the file named <em>file</em>. The byte-code is written to <em>cfile</em>, which defaults to the <span class="target" id="index-1"></span><a class="pep reference external" href="https://peps.python.org/pep-3147/"><strong>PEP 3147</strong></a>/<span class="target" id="index-2"></span><a class="pep reference external" href="https://peps.python.org/pep-0488/"><strong>PEP 488</strong></a> path, ending in <code>.pyc</code>. For example, if <em>file</em> is <code>/foo/bar/baz.py</code> <em>cfile</em> will default to <code>/foo/bar/__pycache__/baz.cpython-32.pyc</code> for Python 3.2. If <em>dfile</em> is specified, it is used instead of <em>file</em> as the name of the source file from which source lines are obtained for display in exception tracebacks. If <em>doraise</em> is true, a <a class="reference internal" href="#py_compile.PyCompileError" title="py_compile.PyCompileError"><code>PyCompileError</code></a> is raised when an error is encountered while compiling <em>file</em>. If <em>doraise</em> is false (the default), an error string is written to <code>sys.stderr</code>, but no exception is raised. This function returns the path to byte-compiled file, i.e. whatever <em>cfile</em> value was used.</p> <p>The <em>doraise</em> and <em>quiet</em> arguments determine how errors are handled while compiling file. If <em>quiet</em> is 0 or 1, and <em>doraise</em> is false, the default behaviour is enabled: an error string is written to <code>sys.stderr</code>, and the function returns <code>None</code> instead of a path. If <em>doraise</em> is true, a <a class="reference internal" href="#py_compile.PyCompileError" title="py_compile.PyCompileError"><code>PyCompileError</code></a> is raised instead. However if <em>quiet</em> is 2, no message is written, and <em>doraise</em> has no effect.</p> <p>If the path that <em>cfile</em> becomes (either explicitly specified or computed) is a symlink or non-regular file, <a class="reference internal" href="exceptions#FileExistsError" title="FileExistsError"><code>FileExistsError</code></a> 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.</p> <p><em>optimize</em> controls the optimization level and is passed to the built-in <a class="reference internal" href="functions#compile" title="compile"><code>compile()</code></a> function. The default of <code>-1</code> selects the optimization level of the current interpreter.</p> <p><em>invalidation_mode</em> should be a member of the <a class="reference internal" href="#py_compile.PycInvalidationMode" title="py_compile.PycInvalidationMode"><code>PycInvalidationMode</code></a> enum and controls how the generated bytecode cache is invalidated at runtime. The default is <a class="reference internal" href="#py_compile.PycInvalidationMode.CHECKED_HASH" title="py_compile.PycInvalidationMode.CHECKED_HASH"><code>PycInvalidationMode.CHECKED_HASH</code></a> if the <span class="target" id="index-3"></span><code>SOURCE_DATE_EPOCH</code> environment variable is set, otherwise the default is <a class="reference internal" href="#py_compile.PycInvalidationMode.TIMESTAMP" title="py_compile.PycInvalidationMode.TIMESTAMP"><code>PycInvalidationMode.TIMESTAMP</code></a>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>Changed default value of <em>cfile</em> to be <span class="target" id="index-4"></span><a class="pep reference external" href="https://peps.python.org/pep-3147/"><strong>PEP 3147</strong></a>-compliant. Previous default was <em>file</em> + <code>'c'</code> (<code>'o'</code> if optimization was enabled). Also added the <em>optimize</em> parameter.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>Changed code to use <a class="reference internal" href="importlib#module-importlib" title="importlib: The implementation of the import machinery."><code>importlib</code></a> for the byte-code cache file writing. This means file creation/writing semantics now match what <a class="reference internal" href="importlib#module-importlib" title="importlib: The implementation of the import machinery."><code>importlib</code></a> does, e.g. permissions, write-and-move semantics, etc. Also added the caveat that <a class="reference internal" href="exceptions#FileExistsError" title="FileExistsError"><code>FileExistsError</code></a> is raised if <em>cfile</em> is a symlink or non-regular file.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>invalidation_mode</em> parameter was added as specified in <span class="target" id="index-5"></span><a class="pep reference external" href="https://peps.python.org/pep-0552/"><strong>PEP 552</strong></a>. If the <span class="target" id="index-6"></span><code>SOURCE_DATE_EPOCH</code> environment variable is set, <em>invalidation_mode</em> will be forced to <a class="reference internal" href="#py_compile.PycInvalidationMode.CHECKED_HASH" title="py_compile.PycInvalidationMode.CHECKED_HASH"><code>PycInvalidationMode.CHECKED_HASH</code></a>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7.2: </span>The <span class="target" id="index-7"></span><code>SOURCE_DATE_EPOCH</code> environment variable no longer overrides the value of the <em>invalidation_mode</em> argument, and determines its default value instead.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>The <em>quiet</em> parameter was added.</p> </div> </dd>
</dl> <dl class="py class"> <dt class="sig sig-object py" id="py_compile.PycInvalidationMode">
<code>class py_compile.PycInvalidationMode</code> </dt> <dd>
<p>A enumeration of possible methods the interpreter can use to determine whether a bytecode file is up to date with a source file. The <code>.pyc</code> file indicates the desired invalidation mode in its header. See <a class="reference internal" href="../reference/import#pyc-invalidation"><span class="std std-ref">Cached bytecode invalidation</span></a> for more information on how Python invalidates <code>.pyc</code> files at runtime.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.7.</span></p> </div> <dl class="py attribute"> <dt class="sig sig-object py" id="py_compile.PycInvalidationMode.TIMESTAMP">
<code>TIMESTAMP</code> </dt> <dd>
<p>The <code>.pyc</code> 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 <code>.pyc</code> file needs to be regenerated.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="py_compile.PycInvalidationMode.CHECKED_HASH">
<code>CHECKED_HASH</code> </dt> <dd>
<p>The <code>.pyc</code> file includes a hash of the source file content, which Python will compare against the source at runtime to determine if the <code>.pyc</code> file needs to be regenerated.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="py_compile.PycInvalidationMode.UNCHECKED_HASH">
<code>UNCHECKED_HASH</code> </dt> <dd>
<p>Like <a class="reference internal" href="#py_compile.PycInvalidationMode.CHECKED_HASH" title="py_compile.PycInvalidationMode.CHECKED_HASH"><code>CHECKED_HASH</code></a>, the <code>.pyc</code> file includes a hash of the source file content. However, Python will at runtime assume the <code>.pyc</code> file is up to date and not validate the <code>.pyc</code> against the source file at all.</p> <p>This option is useful when the <code>.pycs</code> are kept up to date by some system external to Python like a build system.</p> </dd>
</dl> </dd>
</dl> <section id="command-line-interface"> <span id="py-compile-cli"></span><h2>Command-Line Interface</h2> <p>This module can be invoked as a script to compile several source files. The files named in <em>filenames</em> 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.</p> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-python-m-py_compile-arg-file">
<code>&lt;file&gt; ... &lt;fileN&gt;</code> </dt> <dt class="sig sig-object std" id="cmdoption-python-m-py_compile">
<code>-</code> </dt> <dd>
<p>Positional arguments are files to compile. If <code>-</code> is the only parameter, the list of files is taken from standard input.</p> </dd>
</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-python-m-py_compile-q">
<code>-q, --quiet</code> </dt> <dd>
<p>Suppress errors output.</p> </dd>
</dl> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>Added support for <code>-</code>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>Added support for <a class="reference internal" href="#cmdoption-python-m-py_compile-q"><code>-q</code></a>.</p> </div> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt>
<code>Module</code> <a class="reference internal" href="compileall#module-compileall" title="compileall: Tools for byte-compiling all Python source files in a directory tree."><code>compileall</code></a>
</dt>
<dd>
<p>Utilities to compile all Python source files in a directory tree.</p> </dd> </dl> </div> </section> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/library/py_compile.html" class="_attribution-link">https://docs.python.org/3.12/library/py_compile.html</a>
  </p>
</div>