《Python高手之路》 2 6 管理API變化

在構造api時很難一蹴而就。api需要不斷演化、新增、刪除或者修改所提供的功能。

在後面的段落中women將討論如何管理公共api的變化。公共api是指將應用程式或庫暴露給終端使用者的api。內部api則有另外的考慮，並且由於它們在內部（也就是說使用者不需要直接操作這些api），因而可以任意處理它們：分解、調整或者根據需要任意使用。

這兩種api很容易區分。python的傳統是用下劃線作為私有api的字首，如foo是公共api，而_bar是私有的。

在構建api時，最糟糕的事情莫過於api被突然破壞。linus torvalds就因對linux核心公共api破壞的零容忍而聞名。考慮到如此多的人依賴linux，可以說他的選擇是非常明智的。

unix平台的庫管理系統很複雜，它依賴於soname（）和細粒度的版本識別符號。python中沒有這樣的系統，也沒有對應的轉換。因此完全取決於維護者如何選擇正確的版本號和策略。但是，關於如何定義自己的庫或應用程式的版本，你依然可以將unix系統作為你的靈感**。通常，版本號應該反映出api對使用者的影響，大部分開發人員通過主版本號的增加來表示此類變化，但這取決於你對版本號管理的方法，你也可以採用增加小版本號的方式。

不管如何決定，最重要的一步就是在修改api時要通過文件對修改進行詳細地記錄，包括：

舊介面不要立刻刪除。實際上，應該盡量長時間地保留舊介面。因為已經明確標識為作廢，所以新使用者不會去使用它。在維護實在太麻煩時再移除舊介面。api變化的記錄見示例2.2.

示例2.2api變化的記錄

class car(object):  
def turn_left(self): 
"""turn the car left. 
.. deprecated:: 1.1 
use :func:`turn` instead with the direction argument set to left 
""" 
self.turn(direction='left') 
def turn(self, direction): 
"""turn the car in some direction. 
:param direction: the direction to turn to. 
:type direction: str 
""" 
# write actual code here instead 
pass

使用sphinx標記強調修改是個好主意。在構建文件時，使用者應該能清楚地知道某個功能不應該再被使用，並且可以直接訪問到新功能，並隨之解釋如何公升級舊**。這個方法的缺點就是，你不能指望開發人員在公升級你的python包到新版本時會去讀你的修改日誌或者文件。

python提供了乙個很有意思的名為warnings的模組用來解決這一問題。這一模組允許**發出不同型別的警告資訊，如pendingdeprecationwarning和deprecationwarning。這些警告能夠用來通知開發人員某個正在呼叫的函式已經廢棄或即將廢棄。這樣，開發人員就能夠看到他們正在使用舊介面並且應該相應地進行處理5。

回到之前的例子，我們可以利用它向使用者發出警告，如示例2.3所示。

示例2.3 帶警告的api變化的記錄

import warnings  
class car(object): 
def turn_left(self): 
"""turn the car left. 
.. deprecated:: 1.1 
use :func:`turn` instead with the direction argument set to "left". 
""" 
warnings.warn("turn_left is deprecated, use turn instead", 
deprecationwarning) 
self.turn(direction='left') 
def turn(self, direction): 
"""turn the car in some direction. 
:param direction: the direction to turn to. 
:type direction: str 
""" 
# write actual code here instead 
pass

任何呼叫了廢棄的turn_left函式的**，都將引發乙個警告：

>>> car().turn_left()  
__main__:8: deprecationwarning: turn_left is deprecated, use turn instead

注意

從python 2.7開始，deprecationwarning預設將不顯示。可以通過在呼叫python時指定-w all選項來禁用這一過濾器。關於-w的可用值的更多資訊可以參考python手冊。

讓你的**告訴開發人員他們的程式正在使用某些最終將要停止工作的東西是明智的，因為這其實也可以自動化。當執行他們的測試集合時，開發人員可以在執行python時使用-w error選項，它會將警告轉換為異常。這意味著乙個廢棄的函式每次被呼叫時都會有乙個錯誤被丟擲，這樣使用你的庫的開發人員就可以很容易知道如何具體修改他們的**。

示例2.4 執行python -w error

>>> import warnings  
>>> warnings.warn("this is deprecated", deprecationwarning) 
traceback (most recent call last): 
file "", line 1, in deprecationwarning: this is deprecated

《Python高手之路》 2 6 管理API變化

好書推薦《Python高手之路》

《Python高手之路》 2 4 框架

PHP高手之路

《Python高手之路》 2 6 管理API變化

好書推薦《Python高手之路》

《Python高手之路》 2 4 框架

PHP高手之路

相關推薦