示例

在实践中，这将是什么样子？

假设我们有一个名为 alpha 的 Python 包，其中包含一个名为 beta 的子包。字节编译之前的源目录布局可能如下所示：

alpha/
    __init__.py
    one.py
    two.py
    beta/
        __init__.py
        three.py
        four.py

使用 Python 3.2 字节编译此包后，您将看到以下布局：

alpha/
    __pycache__/
        __init__.cpython-32.pyc
        one.cpython-32.pyc
        two.cpython-32.pyc
    __init__.py
    one.py
    two.py
    beta/
        __pycache__/
            __init__.cpython-32.pyc
            three.cpython-32.pyc
            four.cpython-32.pyc
        __init__.py
        three.py
        four.py

注意：列表顺序可能因平台而异。

假设安装了两个新的 Python 版本，一个是 Python 3.3，另一个是 Unladen Swallow。字节编译后，文件系统将如下所示：

alpha/
    __pycache__/
        __init__.cpython-32.pyc
        __init__.cpython-33.pyc
        __init__.unladen-10.pyc
        one.cpython-32.pyc
        one.cpython-33.pyc
        one.unladen-10.pyc
        two.cpython-32.pyc
        two.cpython-33.pyc
        two.unladen-10.pyc
    __init__.py
    one.py
    two.py
    beta/
        __pycache__/
            __init__.cpython-32.pyc
            __init__.cpython-33.pyc
            __init__.unladen-10.pyc
            three.cpython-32.pyc
            three.cpython-33.pyc
            three.unladen-10.pyc
            four.cpython-32.pyc
            four.cpython-33.pyc
            four.unladen-10.pyc
        __init__.py
        three.py
        four.py

如您所见，只要 Python 版本标识符字符串是唯一的，就可以共存任意数量的 pyc 文件。这些标识符字符串将在下面详细介绍。

此布局的一个很好的特性是，通常可以忽略 __pycache__ 目录，这样正常的目录列表将显示如下内容：

alpha/
    __pycache__/
    __init__.py
    one.py
    two.py
    beta/
        __pycache__/
        __init__.py
        three.py
        four.py

这比今天的 Python 更加整洁。

情况 0：稳定状态

当 Python 被要求导入模块 foo 时，它会在其 sys.path 中搜索 foo.py 文件（或 foo 包，但这对于本次讨论并不重要）。如果找到，Python 将查看是否存在匹配的 __pycache__/foo.<magic>.pyc 文件，如果存在，则加载该 pyc 文件。

情况 1：第一次导入

当 Python 找到 foo.py 文件时，如果 __pycache__/foo.<magic>.pyc 文件不存在，Python 会创建它，并在必要时创建 __pycache__ 目录。Python 会解析并编译 foo.py 文件，并将字节码保存到 __pycache__/foo.<magic>.pyc 文件中。

情况 2：第二次导入

当 Python 第二次被要求导入模块 foo 时（当然是在不同的进程中），它会再次沿着 sys.path 搜索 foo.py 文件。当 Python 找到 foo.py 文件时，它会寻找匹配的 __pycache__/foo.<magic>.pyc 文件，如果找到，则读取字节码并照常继续。

情况 3：__pycache__/foo.<magic>.pyc 没有源代码

有可能 foo.py 文件被删除了，但缓存的 pyc 文件仍然保留在文件系统中。如果 __pycache__/foo.<magic>.pyc 文件存在，但用于创建它的 foo.py 文件不存在，当 Python 被要求导入 foo 时，它会引发 ImportError 错误。换句话说，除非源文件存在，否则 Python 不会从缓存目录导入 pyc 文件。

情况 4：旧的 pyc 文件和无源代码的导入

当源文件存在于 pyc 文件旁边时，Python 会忽略所有旧版本的 pyc 文件。换句话说，如果 foo.pyc 文件存在于 foo.py 文件旁边，则在所有情况下都会忽略 pyc 文件。

为了继续支持无源代码分发，如果源文件丢失，Python 会导入独立的 pyc 文件，前提是该文件位于源文件应该存在的位置。

情况 5：只读文件系统

当源文件位于只读文件系统上，或者无法写入 __pycache__ 目录或 pyc 文件时，所有相同的规则都适用。当 __pycache__ 的权限不允许写入包含 pyc 文件时，情况也是如此。

检测 PEP 3147 的可用性

检测您的 Python 版本是否提供 PEP 3147 功能的最简单方法是执行以下检查。

>>> import imp
>>> has3147 = hasattr(imp, 'get_tag')

__file__

在 Python 3 中，当您导入模块时，其 __file__ 属性指向其源 py 文件（在 Python 2 中，它指向 pyc 文件）。包的 __file__ 指向其 __init__.py 的 py 文件。例如：

>>> import foo
>>> foo.__file__
'foo.py'
# baz is a package
>>> import baz
>>> baz.__file__
'baz/__init__.py'

此 PEP 中没有任何内容会更改 __file__ 的语义。

此 PEP 建议向模块添加一个 __cached__ 属性，该属性始终指向读取或写入的实际 pyc 文件。当设置环境变量 $PYTHONDONTWRITEBYTECODE 或给出 -B 选项，或者源文件位于只读文件系统上时，__cached__ 属性将指向如果 pyc 文件不存在则将写入该文件的位置。当然，此位置在其路径中包含 __pycache__ 子目录。

对于不支持 pyc 文件的其他 Python 实现，__cached__ 属性可能指向任何有意义的信息。例如，在 Jython 上，这可能是模块的 .class 文件：__pycache__/foo.jython-32.class。某些实现可能使用多个编译文件来创建模块，在这种情况下，__cached__ 可能是一个元组。__cached__ 的确切内容是 Python 实现特定的。

建议在无法计算任何有意义的信息时，实现应将 __cached__ 属性设置为 None。

py_compile 和 compileall

Python 带有两个模块，py_compile [15] 和 compileall [16]，它们支持在内置导入机制之外编译 Python 模块。py_compile 特别是具有字节编译的深入知识，因此这些将更新以了解新的布局。将 -b 标志添加到 compileall 中以写入旧版 .pyc 字节编译文件路径名。

bdist_wininst 和 Windows 安装程序

这些工具还在安装时显式编译模块。如果它们不使用 py_compile 和 compileall，则还需要修改它们以了解新的布局。

文件扩展名检查

存在一些代码会检查以 .pyc 结尾的文件，并简单地删除最后一个字符以找到匹配的 .py 文件。一旦实施此 PEP，此代码显然会失败。

为了支持此用例，我们将向 imp 包 [17] 添加两个新方法。

• imp.cache_from_source(py_path) -> pyc_path
• imp.source_from_cache(pyc_path) -> py_path

替代实现可以自由覆盖这些函数，以根据其对本 PEP 的支持返回合理的值。当实现（或生效的 PEP 302 加载程序）由于任何原因无法计算适当的文件名时，这些方法可以返回 None。它们不应该引发异常。

反向移植

对于早于 3.2（可能还有 2.7）版本的 Python，可以移植此 PEP。但是，在 Python 3.2（可能还有 2.7）中，此行为将默认启用，实际上，它将替换旧行为。移植需要默认支持旧布局。我们建议通过使用名为 $PYTHONENABLECACHEDIR 的环境变量或命令行开关 -Xenablecachedir 来启用此功能，从而支持 PEP 3147。

Makefile 和其他依赖项工具

计算 .pyc 文件依赖项（例如，如果 .pyc 丢失则编译源代码）的 Makefile 和其他工具将必须更新以检查新路径。

十六进制魔法标记

__pycache__ 目录中的 pyc 文件在其文件名中包含一个魔术标记。这些是导入程序使用的实际魔术数字的助记符标记。我们可以使用二进制魔术数字的十六进制表示 [10] 作为唯一标识符。例如，在 Python 3.2 中：

>>> from binascii import hexlify
>>> from imp import get_magic
>>> 'foo.{}.pyc'.format(hexlify(get_magic()).decode('ascii'))
'foo.580c0d0a.pyc'

但这并不特别人性化，因此在本 PEP 中提出了魔术标记。

PEP 304

此 PEP 的目标与已撤回的 PEP 304 之间存在一些重叠。但是，PEP 304 允许用户创建一个影子文件系统层次结构，以在其中存储 pyc 文件。此 pyc 文件的影子层次结构的概念可用于满足本 PEP 的目标。尽管 PEP 304 没有说明其撤回的原因，但影子目录存在一些问题。影子 pyc 文件的位置不容易发现，并且取决于系统和最终用户对 $PYTHONBYTECODE 环境变量的正确和一致使用。还存在全局影响，这意味着虽然系统可能希望隐藏 pyc 文件，但用户可能不希望这样做，但 PEP 仅定义了一种非此即彼的方法。

例如，一个常见的（尽管很脆弱）Python 习语用于查找数据文件，如下所示：

from os import dirname, join
import foo.bar
data_file = join(dirname(foo.bar.__file__), 'my.dat')

这将是一个问题，因为foo.bar.__file__将给出影子目录中pyc文件的位置，并且可能无法从那里找到相对于源目录的my.dat文件。

胖字节编译文件

PEP 的早期版本描述了“胖”Python 字节码文件。这些文件将在单个pyf文件中包含多个pyc文件的等效内容，并使用基于相应幻数的查找表。这是一种可扩展的文件格式，以便可以相当有效地支持前 5 个并行的 Python 实现，但可以使用扩展查找表来扩展pyf字节码对象，使其尽可能大。

胖字节编译文件相当复杂，并且固有地引入了难以处理的竞争条件，因此建议使用当前的目录简化方法。使用 zip 文件作为胖 pyc 文件格式也会出现同样的问题。

多个文件扩展名

PEP 作者还考虑了一种方法，其中多个瘦字节编译文件位于同一位置，但使用不同的文件扩展名来指定 Python 版本。例如 foo.pyc25、foo.pyc26、foo.pyc31 等。这被拒绝了，因为编写这么多不同的文件会造成混乱。多扩展名方法使得更新依赖于文件扩展名的任何工具变得更加困难（并且是一项持续的任务）。

.pyc

有人提议将__pycache__目录称为.pyc或其他一些点文件名。这将在 *nix 系统上具有隐藏目录的效果。BDFL [20]拒绝此提议的原因有很多，包括点文件仅在某些平台上具有特殊含义，并且我们实际上 *不*希望完全向用户隐藏这些文件。