klarkxy/hustoj
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
hustoj/web/python-docs/library/py_compile.html
klarkxy 723430cade 增加python文档
2025-03-09 17:10:56 +08:00

334 lines
25 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_CN">
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>py_compile --- 编译 Python 源文件 &#8212; Python 3.8.20 文档</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script src="../_static/translations.js"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="在 Python 3.8.20 文档 中搜索"
href="../_static/opensearch.xml"/>
<link rel="author" title="关于这些文档" href="../about.html" />
<link rel="index" title="索引" href="../genindex.html" />
<link rel="search" title="搜索" href="../search.html" />
<link rel="copyright" title="版权所有" href="../copyright.html" />
<link rel="next" title="compileall --- 字节编译 Python 库" href="compileall.html" />
<link rel="prev" title="pyclbr --- Python 模块浏览器支持" href="pyclbr.html" />
<link rel="canonical" href="https://docs.python.org/3/library/py_compile.html" />
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<nav class="nav-content" role="navigation">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Logo"/>
</a>
<div class="version_switcher_placeholder"></div>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero"
d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z" fill="#444"></path>
</svg>
<input type="text" name="q" aria-label="快速搜索"/>
<input type="submit" value="转向"/>
</form>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<h4>上一个主题</h4>
<p class="topless"><a href="pyclbr.html"
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pyclbr</span></code> --- Python 模块浏览器支持</a></p>
<h4>下一个主题</h4>
<p class="topless"><a href="compileall.html"
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">compileall</span></code> --- 字节编译 Python 库</a></p>
<div role="note" aria-label="source link">
<h3>本页</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">报告 Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/py_compile.rst"
rel="nofollow">显示源代码
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
这个文档所针对的是一个已不再受支持的 Python 旧版本。
你应当升级版本，并阅读
<a href="/3/library/py_compile.html"> Python 当前稳定版本的文档</a>.
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>导航</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="总目录"
accesskey="I">索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模块索引"
>模块</a> |</li>
<li class="right" >
<a href="compileall.html" title="compileall --- 字节编译 Python 库"
accesskey="N">下一页</a> |</li>
<li class="right" >
<a href="pyclbr.html" title="pyclbr --- Python 模块浏览器支持"
accesskey="P">上一页</a> |</li>
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.8.20 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="language.html" accesskey="U">Python 语言服务</a> &#187;</li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
<input type="submit" value="转向" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
|
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-py_compile">
<span id="py-compile-compile-python-source-files"></span><h1><a class="reference internal" href="#module-py_compile" title="py_compile: Generate byte-code files from Python source files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">py_compile</span></code></a> --- 编译 Python 源文件<a class="headerlink" href="#module-py_compile" title="永久链接至标题"></a></h1>
<p><strong>源代码:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.8/Lib/py_compile.py">Lib/py_compile.py</a></p>
<hr class="docutils" id="index-0" />
<p><a class="reference internal" href="#module-py_compile" title="py_compile: Generate byte-code files from Python source files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">py_compile</span></code></a> 模块提供了用来从源文件生成字节码的函数和另一个用于当模块源文件作为脚本被调用时的函数。</p>
<p>虽然不太常用，但这个函数在安装共享模块时还是很有用的，特别是当一些用户可能没有权限在包含源代码的目录中写字节码缓存文件时。</p>
<dl class="exception">
<dt id="py_compile.PyCompileError">
<em class="property">exception </em><code class="sig-prename descclassname">py_compile.</code><code class="sig-name descname">PyCompileError</code><a class="headerlink" href="#py_compile.PyCompileError" title="永久链接至目标"></a></dt>
<dd><p>当编译文件过程中发生错误时，抛出的异常。</p>
</dd></dl>
<dl class="function">
<dt id="py_compile.compile">
<code class="sig-prename descclassname">py_compile.</code><code class="sig-name descname">compile</code><span class="sig-paren">(</span><em class="sig-param">file</em>, <em class="sig-param">cfile=None</em>, <em class="sig-param">dfile=None</em>, <em class="sig-param">doraise=False</em>, <em class="sig-param">optimize=-1</em>, <em class="sig-param">invalidation_mode=PycInvalidationMode.TIMESTAMP</em>, <em class="sig-param">quiet=0</em><span class="sig-paren">)</span><a class="headerlink" href="#py_compile.compile" title="永久链接至目标"></a></dt>
<dd><p>将源文件编译成字节码并写出字节码缓存文件。 源代码从名为 <em>file</em> 的文件中加载。 字节码会写入到 <em>cfile</em>，默认为 <span class="target" id="index-15"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-3147"><strong>PEP 3147</strong></a>/<span class="target" id="index-16"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0488"><strong>PEP 488</strong></a> 路径，以 <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> 结尾。 例如，如果 <em>file</em> 是 <code class="docutils literal notranslate"><span class="pre">/foo/bar/baz.py</span></code> 则对于 Python 3.2 <em>cfile</em> 将默认为 <code class="docutils literal notranslate"><span class="pre">/foo/bar/__pycache__/baz.cpython-32.pyc</span></code>。 如果指定了 <em>dfile</em>，则在错误信息中它将代替 <em>file</em> 作为源文件的名称。 如果 <em>doraise</em> 为真值，则当编译 <em>file</em> 遇到错误时将会引发 <a class="reference internal" href="#py_compile.PyCompileError" title="py_compile.PyCompileError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">PyCompileError</span></code></a>。 如果 <em>doraise</em> 为假值（默认），则将错误信息写入到 <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code>，但不会引发异常。 此函数返回编译后字节码文件的路径，即 <em>cfile</em> 所使用的值。</p>
<p><em>doraise</em> 和 <em>quiet</em> 参数确定在编译文件时如何处理错误。 如果 <em>quiet</em> 为 0 或 1，并且 <em>doraise</em> 为假值，则会启用默认行为：写入错误信息到 <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code>，并且函数将返回 <code class="docutils literal notranslate"><span class="pre">None</span></code> 而非一个路径。 如果 <em>doraise</em> 为真值，则将改为引发 <a class="reference internal" href="#py_compile.PyCompileError" title="py_compile.PyCompileError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">PyCompileError</span></code></a>。 但是如果 <em>quiet</em> 为 2，则不会写入消息，并且 <em>doraise</em> 也不会有效果。</p>
<p>如果 <em>cfile</em> 所表示（显式指定或计算得出）的路径为符号链接或非常规文件，则将引发 <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a>。 此行为是用来警告如果允许写入编译后字节码文件到这些路径则导入操作将会把它们转为常规文件。 这是使用文件重命名来将最终编译后字节码文件放置到位以防止并发文件写入问题的导入操作的附带效果。</p>
<p><em>optimize</em> 控制优化级别并会被传给内置的 <a class="reference internal" href="functions.html#compile" title="compile"><code class="xref py py-func docutils literal notranslate"><span class="pre">compile()</span></code></a> 函数。 默认值 <code class="docutils literal notranslate"><span class="pre">-1</span></code> 表示选择当前解释器的优化级别。</p>
<p><em>invalidation_mode</em> 应当是 <a class="reference internal" href="#py_compile.PycInvalidationMode" title="py_compile.PycInvalidationMode"><code class="xref py py-class docutils literal notranslate"><span class="pre">PycInvalidationMode</span></code></a> 枚举的成员，它控制在运行时如何让已生成的字节码缓存失效。 如果设置了 <span class="target" id="index-17"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">SOURCE_DATE_EPOCH</span></code> 环境变量则默认值为 <a class="reference internal" href="#py_compile.PycInvalidationMode.CHECKED_HASH" title="py_compile.PycInvalidationMode.CHECKED_HASH"><code class="xref py py-attr docutils literal notranslate"><span class="pre">PycInvalidationMode.CHECKED_HASH</span></code></a>，否则默认值为 <a class="reference internal" href="#py_compile.PycInvalidationMode.TIMESTAMP" title="py_compile.PycInvalidationMode.TIMESTAMP"><code class="xref py py-attr docutils literal notranslate"><span class="pre">PycInvalidationMode.TIMESTAMP</span></code></a>。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.2 版更改: </span>将 <em>cfile</em> 的默认值改成与 <span class="target" id="index-18"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-3147"><strong>PEP 3147</strong></a> 兼容。 之前的默认值是 <em>file</em> + <code class="docutils literal notranslate"><span class="pre">'c'</span></code> (如果启用优化则为 <code class="docutils literal notranslate"><span class="pre">'o'</span></code>)。 同时也添加了 <em>optimize</em> 形参。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.4 版更改: </span>将代码更改为使用 <a class="reference internal" href="importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib</span></code></a> 执行字节码缓存文件写入。 这意味着文件创建/写入的语义现在与 <a class="reference internal" href="importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib</span></code></a> 所做的相匹配，例如权限、写入和移动语义等等。 同时也添加了当 <em>cfile</em> 为符号链接或非常规文件时引发 <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> 的预警设置。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.7 版更改: </span><em>invalidation_mode</em> 形参是根据 <span class="target" id="index-19"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0552"><strong>PEP 552</strong></a> 的描述添加的。 如果设置了 <span class="target" id="index-20"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">SOURCE_DATE_EPOCH</span></code> 环境变量，<em>invalidation_mode</em> 将被强制设为 <a class="reference internal" href="#py_compile.PycInvalidationMode.CHECKED_HASH" title="py_compile.PycInvalidationMode.CHECKED_HASH"><code class="xref py py-attr docutils literal notranslate"><span class="pre">PycInvalidationMode.CHECKED_HASH</span></code></a>。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.7.2 版更改: </span><span class="target" id="index-21"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">SOURCE_DATE_EPOCH</span></code> 环境变量不会再覆盖 <em>invalidation_mode</em> 参数的值，而改为确定其默认值。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.8 版更改: </span>增加了 <em>quiet</em> 形参。</p>
</div>
</dd></dl>
<dl class="class">
<dt id="py_compile.PycInvalidationMode">
<em class="property">class </em><code class="sig-prename descclassname">py_compile.</code><code class="sig-name descname">PycInvalidationMode</code><a class="headerlink" href="#py_compile.PycInvalidationMode" title="永久链接至目标"></a></dt>
<dd><p>一个由可用方法组成的枚举，解释器可以用来确定字节码文件是否与源文件保持一致。 <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> 文件在其标头中指明了所需的失效模式。 请参阅 <a class="reference internal" href="../reference/import.html#pyc-invalidation"><span class="std std-ref">已缓存字节码的失效</span></a> 了解有关 Python 在运行时如何让 <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> 文件失效的更多信息。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.7 新版功能.</span></p>
</div>
<dl class="attribute">
<dt id="py_compile.PycInvalidationMode.TIMESTAMP">
<code class="sig-name descname">TIMESTAMP</code><a class="headerlink" href="#py_compile.PycInvalidationMode.TIMESTAMP" title="永久链接至目标"></a></dt>
<dd><p><code class="docutils literal notranslate"><span class="pre">.pyc</span></code> 文件包括时间戳和源文件的大小，Python 将在运行时将其与源文件的元数据进行比较以确定 <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> 文件是否需要重新生成。</p>
</dd></dl>
<dl class="attribute">
<dt id="py_compile.PycInvalidationMode.CHECKED_HASH">
<code class="sig-name descname">CHECKED_HASH</code><a class="headerlink" href="#py_compile.PycInvalidationMode.CHECKED_HASH" title="永久链接至目标"></a></dt>
<dd><p><code class="docutils literal notranslate"><span class="pre">.pyc</span></code> 文件包括源文件内容的哈希值，Python 将在运行时将其与源文件内容进行比较以确定 <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> 文件是否需要重新生成。</p>
</dd></dl>
<dl class="attribute">
<dt id="py_compile.PycInvalidationMode.UNCHECKED_HASH">
<code class="sig-name descname">UNCHECKED_HASH</code><a class="headerlink" href="#py_compile.PycInvalidationMode.UNCHECKED_HASH" title="永久链接至目标"></a></dt>
<dd><p>类似于 <a class="reference internal" href="#py_compile.PycInvalidationMode.CHECKED_HASH" title="py_compile.PycInvalidationMode.CHECKED_HASH"><code class="xref py py-attr docutils literal notranslate"><span class="pre">CHECKED_HASH</span></code></a>，<code class="docutils literal notranslate"><span class="pre">.pyc</span></code> 文件包括源文件内容的哈希值。 但是，Python 将在运行时假定 <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> 文件是最新的而完全不会将 <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> 与源文件进行验证。</p>
<p>此选项适用于 <code class="docutils literal notranslate"><span class="pre">.pycs</span></code> 由 Python 以外的某个系统例如构建系统来确保最新的情况。</p>
</dd></dl>
</dd></dl>
<dl class="function">
<dt id="py_compile.main">
<code class="sig-prename descclassname">py_compile.</code><code class="sig-name descname">main</code><span class="sig-paren">(</span><em class="sig-param">args=None</em><span class="sig-paren">)</span><a class="headerlink" href="#py_compile.main" title="永久链接至目标"></a></dt>
<dd><p>编译多个源文件。 在 <em>args</em> 中（或者当 <em>args</em> 为 <code class="docutils literal notranslate"><span class="pre">None</span></code> 时则是在命令行中）指定的文件会被编译并将结果字节码以正常方式来缓存。 此函数不会搜索目录结构来定位源文件；它只编译显式指定的文件。 如果 <code class="docutils literal notranslate"><span class="pre">'-'</span></code> 是 args 中唯一的值，则会从标准输入获取文件列表。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.2 版更改: </span>添加了对 <code class="docutils literal notranslate"><span class="pre">'-'</span></code> 的支持。</p>
</div>
</dd></dl>
<p>当此模块作为脚本运行时，会使用 <a class="reference internal" href="#py_compile.main" title="py_compile.main"><code class="xref py py-func docutils literal notranslate"><span class="pre">main()</span></code></a> 来编译命令行中指定的所有文件。 如果某个文件无法被编译则退出状态将为非零值。</p>
<div class="admonition seealso">
<p class="admonition-title">参见</p>
<dl class="simple">
<dt>模块 <a class="reference internal" href="compileall.html#module-compileall" title="compileall: Tools for byte-compiling all Python source files in a directory tree."><code class="xref py py-mod docutils literal notranslate"><span class="pre">compileall</span></code></a></dt><dd><p>编译一个目录树中所有 Python 源文件的工具。</p>
</dd>
</dl>
</div>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>上一个主题</h4>
<p class="topless"><a href="pyclbr.html"
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pyclbr</span></code> --- Python 模块浏览器支持</a></p>
<h4>下一个主题</h4>
<p class="topless"><a href="compileall.html"
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">compileall</span></code> --- 字节编译 Python 库</a></p>
<div role="note" aria-label="source link">
<h3>本页</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">报告 Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/py_compile.rst"
rel="nofollow">显示源代码
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>导航</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="总目录"
>索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模块索引"
>模块</a> |</li>
<li class="right" >
<a href="compileall.html" title="compileall --- 字节编译 Python 库"
>下一页</a> |</li>
<li class="right" >
<a href="pyclbr.html" title="pyclbr --- Python 模块浏览器支持"
>上一页</a> |</li>
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.8.20 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="language.html" >Python 语言服务</a> &#187;</li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
<input type="submit" value="转向" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
|
</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">版权所有</a> 2001-2024, Python Software Foundation.
<br />
This page is licensed under the Python Software Foundation License Version 2.
<br />
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br />
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
<br />
最后更新于 12月 09, 2024.
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 2.4.4.
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink