範例

這在實踐中會是什麼樣子？

假設我們有一個名為 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 檔案與無原始碼匯入

當原始碼檔案存在於其旁邊時，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 特別對位元組編譯有深入了解，因此這些模組將被更新以理解新的版面配置。`compileall` 增加了 -b 旗標，用於寫入舊版 .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 來啟用此功能，以支援 PEP 3147。

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] 拒絕此方案的原因有很多，其中包括點檔案僅在某些平台上特殊，而且我們實際上 *不* 希望完全對使用者隱藏這些檔案。