API 演進的正確方式
負責任的庫作者與其使用者的十個約定。
想象一下你是一個造物主，為一個生物設計一個身體。出於仁慈，你希望它能隨著時間進化：首先，因為它必須對環境的變化作出反應；其次，因為你的智慧在增長，你對這個小東西想到了更好的設計，它不應該永遠保持一個樣子。
然而，這個生物可能有賴於其目前解剖學的特徵。你不能無所顧忌地新增翅膀或改變它的身材比例。它需要一個有序的過程來適應新的身體。作為一個負責任的設計者，你如何才能溫柔地引導這種生物走向更大的進步呢？
對於負責任的庫維護者也是如此。我們向依賴我們程式碼的人保證我們的承諾：我們會發布 bug 修復和有用的新特性。如果對庫的未來有利，我們有時會刪除某些特性。我們會不斷創新，但我們不會破壞使用我們庫的人的程式碼。我們怎樣才能一次實現所有這些目標呢？
新增有用的特性
你的庫不應該永遠保持不變：你應該新增一些特性，使你的庫更適合使用者。例如，如果你有一個爬行動物類，並且如果有個可以飛行的翅膀是有用的，那就去新增吧。
class Reptile: @property def teeth(self): return 'sharp fangs' # 如果 wings 是有用的，那就新增它! @property def wings(self): return 'majestic wings'但要注意，特性是有風險的。考慮 Python 標準庫中以下功能，看看它出了什麼問題。
bool(datetime.time(9, 30)) == Truebool(datetime.time(0, 0)) == False這很奇怪：將任何時間物件轉換為布林值都會得到 True，但午夜時間除外。（更糟糕的是，時區感知時間的規則更加奇怪。）
我已經寫了十多年的 Python 了，但直到上週才發現這條規則。這種奇怪的行為會在使用者程式碼中引起什麼樣的 bug？
比如說一個日曆應用程式，它帶有一個建立事件的函數。如果一個事件有一個結束時間，那麼函數也應該要求它有一個開始時間。
def create_event(day, start_time=None, end_time=None): if end_time and not start_time: raise ValueError("Can't pass end_time without start_time") # 女巫集會從午夜一直開到凌晨 4 點create_event(datetime.date.today(), datetime.time(0, 0), datetime.time(4, 0))不幸的是，對於女巫來說，從午夜開始的事件無法通過校驗。當然，一個了解午夜怪癖的細心程式設計師可以正確地編寫這個函數。
def create_event(day, start_time=None, end_time=None): if end_time is not None and start_time is None: raise ValueError("Can't pass end_time without start_time")但這種微妙之處令人擔憂。如果一個庫作者想要建立一個傷害使用者的 API，那麼像午夜的布林轉換這樣的“特性”很有效。
但是，負責任的建立者的目標是使你的庫易於正確使用。
這個功能是由 Tim Peters 在 2002 年首次編寫 datetime 模組時造成的。即時是像 Tim 這樣的奠基 Python 的高手也會犯錯誤。這個怪異之處後來被消除了，現在所有時間的布林值都是 True。
# Python 3.5 以後bool(datetime.time(9, 30)) == Truebool(datetime.time(0, 0)) == True不知道午夜怪癖的古怪之處的程式設計師現在可以從這種晦澀的 bug 中解脫出來，但是一想到任何依賴於古怪的舊行為的程式碼現在沒有注意變化，我就會感到緊張。如果從來沒有實現這個糟糕的特性，情況會更好。這就引出了庫維護者的第一個承諾：
第一個約定：避免糟糕的特性
最痛苦的變化是你必須刪除一個特性。一般來說，避免糟糕特性的一種方法是少新增特性！沒有充分的理由，不要使用公共方法、類、功能或屬性。因此：
第二個約定：最小化特性
特性就像孩子：在充滿激情的瞬間孕育，但是它們必須要支援多年（LCTT 譯註：我懷疑作者在開車，可是我沒有證據）。不要因為你能做傻事就去做傻事。不要畫蛇添足！
但是，當然，在很多情況下，使用者需要你的庫中尚未提供的東西，你如何選擇合適的功能給他們？以下另一個警示故事。
一個來自 asyncio 的警示故事
你可能知道，當你呼叫一個協程函數，它會返回一個協程物件：
async def my_coroutine(): passprint(my_coroutine())<coroutine object my_coroutine at 0x10bfcbac8>你的程式碼必須 “等待” 這個物件以此來執行協程。人們很容易忘記這一點，所以 asyncio 的開發人員想要一個“偵錯模式”來捕捉這個錯誤。當協程在沒有等待的情況下被銷毀時，偵錯模式將列印一個警告，並在其建立的行上進行回溯。
當 Yury Selivanov 實現偵錯模式時，他新增了一個“協程裝飾器”的基礎特性。裝飾器是一個函數，它接收一個協程並返回任何內容。Yury 使用它在每個協程上接入警告邏輯，但是其他人可以使用它將協程轉換為字串 “hi!”。
import sysdef my_wrapper(coro): return 'hi!'sys.set_coroutine_wrapper(my_wrapper)async def my_coroutine(): passprint(my_coroutine())hi!這是一個地獄般的客製化。它改變了 “非同步“ 的含義。呼叫一次 set_coroutine_wrapper 將在全域性永久改變所有的協程函數。正如 Nathaniel Smith 所說：“一個有問題的 API” 很容易被誤用，必須被刪除。如果 asyncio 開發人員能夠更好地按照其目標來設計該特性，他們就可以避免刪除該特性的痛苦。負責任的建立者必須牢記這一點：
第三個約定：保持特性單一
幸運的是，Yury 有良好的判斷力，他將該特性標記為臨時，所以 asyncio 使用者知道不能依賴它。Nathaniel 可以用更單一的功能替換 set_coroutine_wrapper，該特性只客製化回溯深度。
import syssys.set_coroutine_origin_tracking_depth(2)async def my_coroutine(): passprint(my_coroutine())<coroutine object my_coroutine at 0x10bfcbac8>RuntimeWarning:'my_coroutine' was never awaitedCoroutine created at (most recent call last) File "script.py", line 8, in <module> print(my_coroutine())這樣好多了。沒有可以更改協程的型別的其他全域性設定，因此 asyncio 使用者無需編寫防禦程式碼。造物主應該像 Yury 一樣有遠見。
第四個約定：標記實驗特徵“臨時”
如果你只是預感你的生物需要犄角和四叉舌，那就引入這些特性，但將它們標記為“臨時”。
你可能會發現犄角是無關緊要的，但是四叉舌是有用的。在庫的下一個版本中，你可以刪除前者並標記後者為正式的。
刪除特性
無論我們如何明智地指導我們的生物進化，總會有一天想要刪除一個正式特徵。例如，你可能已經建立了一隻蜥蜴，現在你選擇刪除它的腿。也許你想把這個笨拙的傢伙變成一條時尚而現代的蟒蛇。
刪除特性主要有兩個原因。首先，通過使用者反饋或者你自己不斷增長的智慧，你可能會發現某個特性是個壞主意。午夜怪癖的古怪行為就是這種情況。或者，最初該特性可能已經很好地適應了你的庫環境，但現在生態環境發生了變化，也許另一個神發明了哺乳動物，你的生物想要擠進哺乳動物的小洞穴裡，吃掉裡面美味的哺乳動物，所以它不得不失去雙腿。
同樣，Python 標準庫會根據語言本身的變化刪除特性。考慮 asyncio 的 Lock 功能，在把 await 作為一個關鍵字新增進來之前，它一直在等待：
lock = asyncio.Lock()async def critical_section(): await lock try: print('holding lock') finally: lock.release()但是現在，我們可以做“非同步鎖”：
lock = asyncio.Lock()async def critical_section(): async with lock: print('holding lock')新方法好多了！很短，並且在一個大函數中使用其他 try-except 塊時不容易出錯。因為“盡量找一種，最好是唯一一種明顯的解決方案”，舊語法在 Python 3.7 中被棄用，並且很快就會被禁止。
不可避免的是，生態變化會對你的程式碼產生影響，因此要學會溫柔地刪除特性。在此之前，請考慮刪除它的成本或好處。負責任的維護者不會願意讓使用者更改大量程式碼或邏輯。（還記得 Python 3 在重新新增會 u 字串字首之前刪除它是多麼痛苦嗎？）如果程式碼刪除是機械性的動作，就像一個簡單的搜尋和替換，或者如果該特性是危險的，那麼它可能值得刪除。
是否刪除特性
| 反對 | 支援 |
|---|---|
| 程式碼必須改變 | 改變是機械性的 |
| 邏輯必須改變 | 特性是危險的 |
就我們飢餓的蜥蜴而言，我們決定刪除它的腿，這樣它就可以滑進老鼠洞裡吃掉它。我們該怎麼做呢？我們可以刪除 walk 方法，像下面一樣修改程式碼：
class Reptile: def walk(self): print('step step step')變成這樣：
class Reptile: def slither(self): print('slide slide slide')這不是一個好主意，這個生物習慣於走路！或者，就庫而言，你的使用者擁有依賴於現有方法的程式碼。當他們升級到最新庫版本時，他們的程式碼將會崩潰。
# 使用者的程式碼，哦，不!Reptile.walk()因此，負責任的建立者承諾：
第五條預定：溫柔地刪除
溫柔地刪除一個特性需要幾個步驟。從用腿走路的蜥蜴開始，首先新增新方法 slither。接下來，棄用舊方法。
import warningsclass Reptile: def walk(self): warnings.warn( "walk is deprecated, use slither", DeprecationWarning, stacklevel=2) print('step step step') def slither(self): print('slide slide slide')Python 的 warnings 模組非常強大。預設情況下，它會將警告輸出到 stderr，每個程式碼位置只顯示一次，但你可以禁用警告或將其轉換為異常，以及其它選項。
一旦將這個警告新增到庫中，PyCharm 和其他 IDE 就會使用刪除線呈現這個被棄用的方法。使用者馬上就知道該刪除這個方法。
Reptile().
walk()
當他們使用升級後的庫執行程式碼時會發生什麼？
$ python3 script.pyDeprecationWarning: walk is deprecated, use slither script.py:14: Reptile().walk()step step step預設情況下，他們會在 stderr 上看到警告，但指令碼會成功並列印 “step step step”。警告的回溯顯示必須修復使用者程式碼的哪一行。（這就是 stacklevel 引數的作用：它顯示了使用者需要更改的呼叫，而不是庫中生成警告的行。）請注意，錯誤訊息有指導意義，它描述了庫使用者遷移到新版本必須做的事情。
你的使用者可能會希望測試他們的程式碼，並證明他們沒有呼叫棄用的庫方法。僅警告不會使單元測試失敗，但異常會失敗。Python 有一個命令列選項，可以將棄用警告轉換為異常。
> python3 -Werror::DeprecationWarning script.pyTraceback (most recent call last): File "script.py", line 14, in <module> Reptile().walk() File "script.py", line 8, in walk DeprecationWarning, stacklevel=2)DeprecationWarning: walk is deprecated, use slither現在，“step step step” 沒有輸出出來，因為指令碼以一個錯誤終止。
因此，一旦你發布了庫的一個版本，該版本會警告已啟用的 walk 方法，你就可以在下一個版本中安全地刪除它。對吧？
考慮一下你的庫使用者在他們專案的 requirements 中可能有什麼。
# 使用者的 requirements.txt 顯示 reptile 包的依賴關係reptile下次他們部署程式碼時，他們將安裝最新版本的庫。如果他們尚未處理所有的棄用，那麼他們的程式碼將會崩潰，因為程式碼仍然依賴 walk。你需要溫柔一點，你必須向使用者做出三個承諾：維護更改紀錄檔，選擇版本化方案和編寫升級指南。
第六個約定：維護變更紀錄檔
你的庫必須有更改紀錄檔，其主要目的是宣布使用者所依賴的功能何時被棄用或刪除。
版本 1.1 中的更改
新特性
- 新功能 Reptile.slither()
棄用
- Reptile.walk() 已棄用，將在 2.0 版本中刪除，請使用 slither()
負責任的建立者會使用版本號來表示庫發生了怎樣的變化，以便使用者能夠對升級做出明智的決定。“版本化方案”是一種用於交流變化速度的語言。
第七個約定：選擇一個版本化方案
有兩種廣泛使用的方案，語意版本控制和基於時間的版本控制。我推薦任何庫都進行語意版本控制。Python 的風格在 PEP 440 中定義，像 pip 這樣的工具可以理解語意版本號。
如果你為庫選擇語意版本控制，你可以使用版本號溫柔地刪除腿，例如：
1.0: 第一個“穩定”版，帶有
walk()1.1: 新增slither()，廢棄walk()2.0: 刪除walk()
你的使用者依賴於你的庫的版本應該有一個範圍，例如：
# 使用者的 requirements.txtreptile>=1,<2這允許他們在主要版本中自動升級，接收錯誤修正並可能引發一些棄用警告，但不會升級到下個主要版本並冒著更改破壞其程式碼的風險。
如果你遵循基於時間的版本控制，則你的版本可能會編號：
2017.06.0: 2017 年 6 月的版本 2018.11.0: 新增
slither()，廢棄walk()2019.04.0: 刪除walk()
使用者可以這樣依賴於你的庫：
# 使用者的 requirements.txt，基於時間控制的版本reptile==2018.11.*這非常棒，但你的使用者如何知道你的版本方案，以及如何測試程式碼來進行棄用呢？你必須告訴他們如何升級。
第八個約定：寫一個升級指南
下面是一個負責任的庫建立者如何指導使用者：
升級到 2.0
從棄用的 API 遷移
請參閱更改紀錄檔以了解已棄用的特性。
啟用棄用警告
升級到 1.1 並使用以下程式碼測試程式碼：
python -Werror::DeprecationWarning?????? 現在可以安全地升級了。
你必須通過向使用者顯示命令列選項來教會使用者如何處理棄用警告。並非所有 Python 程式設計師都知道這一點 —— 我自己就每次都得查詢這個語法。注意，你必須發布一個版本，它輸出來自每個棄用的 API 的警告，以便使用者可以在再次升級之前使用該版本進行測試。在本例中，1.1 版本是小版本。它允許你的使用者逐步重寫程式碼，分別修復每個棄用警告，直到他們完全遷移到最新的 API。他們可以彼此獨立地測試程式碼和庫的更改，並隔離 bug 的原因。
如果你選擇語意版本控制，則此過渡期將持續到下一個主要版本，從 1.x 到 2.0，或從 2.x 到 3.0 以此類推。刪除生物腿部的溫柔方法是至少給它一個版本來調整其生活方式。不要一次性把腿刪掉！
版本號、棄用警告、更改紀錄檔和升級指南可以協同工作，在不違背與使用者約定的情況下溫柔地改進你的庫。Twisted 專案的相容性政策 解釋的很漂亮：
“先行者總是自由的”
執行的應用程式在沒有任何警告的情況下都可以升級為 Twisted 的一個次要版本。
換句話說，任何執行其測試而不觸發 Twisted 警告的應用程式應該能夠將其 Twisted 版本升級至少一次，除了可能產生新警告之外沒有任何不良影響。
現在，我們的造物主已經獲得了智慧和力量，可以通過新增方法來新增特性，並溫柔地刪除它們。我們還可以通過新增引數來新增特性，但這帶來了新的難度。你準備好了嗎？
新增引數
想象一下，你只是給了你的蛇形生物一對翅膀。現在你必須允許它選擇是滑行還是飛行。目前它的 move 功能只接受一個引數。
# 你的庫程式碼def move(direction): print(f'slither {direction}')# 使用者的應用move('north')你想要新增一個 mode 引數，但如果使用者升級庫，這會破壞他們的程式碼，因為他們只傳遞了一個引數。
# 你的庫程式碼def move(direction, mode): assert mode in ('slither', 'fly') print(f'{mode} {direction}')# 一個使用者的程式碼，出現錯誤!move('north')一個真正聰明的建立者者會承諾不會以這種方式破壞使用者的程式碼。
第九條約定：相容地新增引數
要保持這個約定，請使用保留原始行為的預設值新增每個新引數。
# 你的庫程式碼def move(direction, mode='slither'): assert mode in ('slither', 'fly') print(f'{mode} {direction}')# 使用者的應用move('north')隨著時間推移，引數是函數演化的自然歷史。它們首先列出最老的引數，每個都有預設值。庫使用者可以傳遞關鍵字引數以選擇特定的新行為，並接受所有其他行為的預設值。
# 你的庫程式碼def move(direction, mode='slither', turbo=False, extra_sinuous=False, hail_lyft=False): # ...# 使用者應用move('north', extra_sinuous=True)但是有一個危險，使用者可能會編寫如下程式碼：
# 使用者應用，簡寫move('north', 'slither', False, True)如果在你在庫的下一個主要版本中去掉其中一個引數，例如 turbo，會發生什麼？
# 你的庫程式碼，下一個主要版本中 "turbo" 被刪除def move(direction, mode='slither', extra_sinuous=False, hail_lyft=False): # ...# 使用者應用，簡寫move('north', 'slither', False, True)使用者的程式碼仍然能編譯，這是一件壞事。程式碼停止了曲折的移動並開始招呼 Lyft，這不是它的本意。我相信你可以預測我接下來要說的內容：刪除引數需要幾個步驟。當然，首先棄用 trubo 引數。我喜歡這種技術，它可以檢測任何使用者的程式碼是否依賴於這個引數。
# 你的庫程式碼_turbo_default = object()def move(direction, mode='slither', turbo=_turbo_default, extra_sinuous=False, hail_lyft=False): if turbo is not _turbo_default: warnings.warn( "'turbo' is deprecated", DeprecationWarning, stacklevel=2) else: # The old default. turbo = False但是你的使用者可能不會注意到警告。警告聲音不是很大：它們可以在紀錄檔檔案中被抑制或丟失。使用者可能會漫不經心地升級到庫的下一個主要版本——那個刪除 turbo 的版本。他們的程式碼執行時將沒有錯誤、默默做錯誤的事情！正如 Python 之禪所說：“錯誤絕不應該被默默 pass”。實際上，爬行動物的聽力很差，所有當它們犯錯誤時，你必須非常大聲地糾正它們。
保護使用者的最佳方法是使用 Python 3 的星型語法，它要求呼叫者傳遞關鍵字引數。
# 你的庫程式碼# 所有 “*” 後的引數必須以關鍵字方式傳輸。def move(direction, *, mode='slither', turbo=False, extra_sinuous=False, hail_lyft=False): # ...# 使用者程式碼，簡寫# 錯誤！不能使用位置引數，關鍵字引數是必須的move('north', 'slither', False, True)有了這個星，以下是唯一允許的語法：
# 使用者程式碼move('north', extra_sinuous=True)現在，當你刪除 turbo 時，你可以確定任何依賴於它的使用者程式碼都會明顯地提示失敗。如果你的庫也支援 Python2，這沒有什麼大不了。你可以模擬星型語法（歸功於 Brett Slatkin）：
# 你的庫程式碼，相容 Python 2def move(direction, **kwargs): mode = kwargs.pop('mode', 'slither') turbo = kwargs.pop('turbo', False) sinuous = kwargs.pop('extra_sinuous', False) lyft = kwargs.pop('hail_lyft', False) if kwargs: raise TypeError('Unexpected kwargs: %r' % kwargs)# ...要求關鍵字引數是一個明智的選擇，但它需要遠見。如果允許按位元置傳遞引數，則不能僅在以後的版本中將其轉換為僅關鍵字。所以，現在加上星號。你可以在 asyncio API 中觀察到，它在建構函式、方法和函數中普遍使用星號。儘管到目前為止，Lock 只接受一個可選引數，但 asyncio 開發人員立即新增了星號。這是幸運的。
# In asyncio.class Lock: def __init__(self, *, loop=None): # ...現在，我們已經獲得了改變方法和引數的智慧，同時保持與使用者的約定。現在是時候嘗試最具挑戰性的進化了：在不改變方法或引數的情況下改變行為。
改變行為
假設你創造的生物是一條響尾蛇，你想教它一種新行為。
橫向移動！這個生物的身體看起來是一樣的，但它的行為會發生變化。我們如何為這一進化步驟做好準備？
Image by HCA [CC BY-SA 4.0], via Wikimedia Commons, 由 Opensource.com 修改
當行為在沒有新函數或新引數的情況下發生更改時，負責任的建立者可以從 Python 標準庫中學習。很久以前，os 模組引入了 stat 函數來獲取檔案統計資訊，比如建立時間。起初，這個時間總是整數。
>>> os.stat('file.txt').st_ctime1540817862有一天，核心開發人員決定在 os.stat 中使用浮點數來提供亞秒級精度。但他們擔心現有的使用者程式碼還沒有做好準備更改。於是他們在 Python 2.3 中建立了一個設定 stat_float_times，預設情況下是 False 。使用者可以將其設定為 True 來選擇浮點時間戳。
>>> # Python 2.3.>>> os.stat_float_times(True)>>> os.stat('file.txt').st_ctime1540817862.598021從 Python 2.5 開始，浮點時間成為預設值，因此 2.5 及之後版本編寫的任何新程式碼都可以忽略該設定並期望得到浮點數。當然，你可以將其設定為 False 以保持舊行為，或將其設定為 True 以確保所有 Python 版本都得到浮點數，並為刪除 stat_float_times 的那一天準備程式碼。
多年過去了，在 Python 3.1 中，該設定已被棄用，以便為人們為遙遠的未來做好準備，最後，經過數十年的旅程，這個設定被刪除。浮點時間現在是唯一的選擇。這是一個漫長的過程，但負責任的神靈是有耐心的，因為我們知道這個漸進的過程很有可能於意外的行為變化拯救使用者。
第十個約定：逐漸改變行為
以下是步驟：
- 新增一個標誌來選擇新行為，預設為
False，如果為False則發出警告 - 將預設值更改為
True，表示完全棄用標記 - 刪除該標誌
如果你遵循語意版本控制，版本可能如下：
| 庫版本 | 庫 API | 使用者程式碼 |
|---|---|---|
| 1.0 | 沒有標誌 | 預期的舊行為 |
| 1.1 | 新增標誌，預設為 False，如果是 False，則警告 | 設定標誌為 True，處理新行為 |
| 2.0 | 改變預設為 True，完全棄用標誌 | 處理新行為 |
| 3.0 | 移除標誌 | 處理新行為 |
你需要兩個主要版本來完成該操作。如果你直接從“新增標誌，預設為 False，如果是 False 則發出警告”變到“刪除標誌”，而沒有中間版本，那麼使用者的程式碼將無法升級。為 1.1 正確編寫的使用者程式碼必須能夠升級到下一個版本，除了新警告之外，沒有任何不良影響，但如果在下一個版本中刪除了該標誌，那麼該程式碼將崩潰。一個負責任的神明從不違反扭曲的政策：“先行者總是自由的”。
負責任的建立者
我們的 10 個約定大致可以分為三類：
謹慎發展
- 避免不良功能
- 最小化特性
- 保持功能單一
- 標記實驗特徵“臨時”
- 溫柔刪除功能
嚴格記錄歷史
- 維護更改紀錄檔
- 選擇版本方案
- 編寫升級指南
緩慢而明顯地改變
- 相容新增引數
- 逐漸改變行為
如果你對你所創造的物種保持這些約定，你將成為一個負責任的造物主。你的生物的身體可以隨著時間的推移而進化，一直在改善和適應環境的變化，而不是在生物沒有準備好就突然改變。如果你維護一個庫，請向使用者保留這些承諾，這樣你就可以在不破壞依賴該庫的程式碼的情況下對庫進行更新。
這篇文章最初是在 A. Jesse Jiryu Davis 的部落格上'出現的，經允許轉載。
插圖參考：
- 《世界進步》, Delphian Society, 1913
- 《走進蛇的歷史》, Charles Owen, 1742
- 關於哥斯達黎加的 batrachia 和爬行動物，關於尼加拉瓜和秘魯的爬行動物和魚類學的記錄, Edward Drinker Cope, 1875
- 《自然史》, Richard Lydekker et. al., 1897
- Mes Prisons, Silvio Pellico, 1843
- Tierfotoagentur / m.blue-shadow
- 洛杉磯公共圖書館, 1930