示例

这在实践中会是什么样子？

假设我们有一个名为 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 文件不存在，则当要求导入 foo 时，Python 将引发 ImportError。换句话说，除非源文件存在，否则 Python 不会从缓存目录导入 pyc 文件。

案例 4：遗留 pyc 文件和无源导入

当源文件存在于 legacy pyc 文件旁边时，Python 将忽略所有 legacy 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。它们不应引发异常。

向后移植

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

Makefiles 和其他依赖工具

Makefiles 和其他计算 .pyc 文件依赖关系的工具（例如，如果 .pyc 缺失则字节编译源文件）将不得不更新以检查新路径。

十六进制魔术标签

__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] 拒绝此提议的原因有很多，其中包括点文件仅在某些平台上特殊，并且我们实际上“不”希望将这些文件完全对用户隐藏。