利用 Python 的 package 機制簡化 utils 包設計

浮生若夢的程式設計發表於2019-03-04
PythonPackage

package 機制

對於 package 機制的說明，其實官方文件已經有非常詳盡的論述了，本文並不著眼於此。

簡單來說，一個目錄下如果包含 __init__.py ，則被 Python 視作一個 Python package。其中：

  1. __init__.py 中的東西，在初始化這個包時，會首先被載入
  2. package 中還可以定義 sub package

初衷

為了概念統一，我們把寫程式碼的人，大致分為兩種角色：

  1. Library Author
  2. Caller 即 API 使用者

有時候我們會是 1 或者 2, 有時候我們可能既是 1 又是 2 ( 比如負責一個較大的系統時)

很顯然，本文的角度是從 1 出發的（即我們只扮演庫作者，並且不知道我們的呼叫者是誰）。

最開始時，utils 可能僅僅是一個 utils.py 就可以了，然後呼叫者 from utils import XXUtils 就完事了，這自然沒有本文什麼事。

然而大部分情況不是這樣的，所有 Utils 都放到一個檔案裡面是 stupid 的（一個原始碼檔案最多 400~500行 ）。所以我們的目錄結構會是這樣的：

utils/
    __init__.py
    a_util.py
    b_util.py
    ......
複製程式碼

呼叫者怎麼使用呢？from utils.a_util import AUtils

這種方式有一個假定：呼叫者要很清楚他所需要的 Utils 位於哪個 py 檔案中。但是這種假定並不總是成立，大家對於同一概念的理解，極有可能是千差萬別的。比如 utils，你覺得叫做 utils 合適，別人還覺得叫做 tools 合適呢，其實都是同一個東西。

顯然，這加重了呼叫者的心智負擔。更加顯然的是，作為庫作者，我們有義務來優化呼叫者的使用體驗！（不然你的庫再牛逼，沒有人愛用也是空彈琴。）

HOW

合理利用 package 機制，就能馬上優化這一體驗。

我們只要在 __init__.py 中這麼寫即可：

__init__.py

from .a_util import AUtils
from .b_util import BUtils
複製程式碼

呼叫者則仍然是這麼使用：

from utils import AUtils, BUtils
複製程式碼

即：呼叫者根本不關心你的實現在哪裡，你只要給我一個 utils 的名稱空間即可，而且確保所有的 Utils 都在這個名稱空間裡面。

為了更加符合 PEP8 的規範，作為庫作者，我們的目錄結構可能會變成這樣：

utils/
    __init__.py
    _a_util.py               不對外界公開, 僅限本package的其他模組使用
    _b_util.py
複製程式碼

應用

不僅是對於 utils 包，對與 constants 包，exceptions 包也可以應用此方法。在許多開源庫中，大牛們經常使用這一手法來優化我們的體驗（太常見了，幾乎大部分開源庫的 __init__.py 中都會寫東西）

相關文章