譯者 | 布加迪

審校 | 重樓

是否曾經(jīng)將您的Python代碼與經(jīng)驗豐富的開發(fā)人員的代碼進行比較，感到明顯的差異？盡管可以從在線資源學(xué)習(xí)Python，但初學(xué)者代碼和專家代碼之間通常存在差距。這是由于經(jīng)驗豐富的開發(fā)人員堅持奉行社區(qū)確保的最佳實踐。這些實踐在在線教程中經(jīng)常被忽視，但對于大規(guī)模應(yīng)用程序而言至關(guān)重要。我在本文中將介紹生產(chǎn)級代碼中使用的7個技巧，確保代碼更清晰、更有條理。

1. 類型提示和注釋

Python是一種動態(tài)類型的編程語言，在運行時推斷變量類型。雖然它提高了靈活性，但在協(xié)作環(huán)境中大大降低了代碼的可讀性和可理解性。

Python支持函數(shù)聲明中的類型提示，充當(dāng)函數(shù)參數(shù)類型和返回類型的注釋。盡管Python在運行時不強制執(zhí)行這些類型，但它仍然很有幫助，因為它使您的代碼更容易被其他人和您自己理解。

從一個基本的例子開始，這是一個帶類型提示的簡單函數(shù)聲明：

Def sum(a: int, b: int) -> int:
Return a + b

在這里，盡管函數(shù)不言自明，但我們看到函數(shù)參數(shù)和返回值都表示為int類型。函數(shù)體可以是一行，也可以是幾百行。然而，我們只需查看函數(shù)聲明就能理解前置條件和返回類型。

其中，這些注釋只是為了清晰和指引，它們并不在執(zhí)行期間強制執(zhí)行類型。所以，即使您傳入不同類型的值，比如字符串而不是整數(shù)，函數(shù)仍然會運行。但是要小心：如果您不提供預(yù)期的類型，它可能會在運行時導(dǎo)致意外的行為或錯誤。比如在提供的示例中，函數(shù)sum()需要兩個整數(shù)作為參數(shù)。但是如果您嘗試添加一個字符串和一個整數(shù)，Python會拋出運行時錯誤。為什么？因為它不知道如何將字符串和整數(shù)相加！這就好比試圖把蘋果和橘子加在一起，那毫無意義。然而，如果兩個參數(shù)都是字符串，它將毫無問題地將它們連接起來。

下面是帶有測試用例的澄清版本：

print(sum(2,5)) # 7
# print(sum('hello', 2)) # TypeError: can only concatenate str (not "int") to str
# print(sum(3,'world')) # TypeError: unsupported operand type(s) for +: 'int' and 'str'
print(sum('hello', 'world')) # helloworld

用于高級類型提示的typing庫

針對高級注釋，Python包含typing標準庫。不妨以一種更有趣的方式來看其用法。

from typing import Union, Tuple, List
import numpy as np
def sum(variable: Union[np.ndarray, List]) -> float:
	total = 0
	# function body to calculate the sum of values in iterable
	return total

這里，我們修改了同一個求和函數(shù)，它現(xiàn)在接受numpy數(shù)組或列表iterable。它計算并以浮點值的形式返回它們的和。我們利用typing庫中的Union注釋來指定變量參數(shù)可以接受的可能類型。

不妨進一步更改函數(shù)聲明，以顯示列表成員還應(yīng)該是類型float。

def sum(variable: Union[np.ndarray, List[float]]) -> float:
	total = 0
	# function body to calculate the sum of values in iterable
	return total

這些只是幫助理解Python中的類型提示的一些入門示例。隨著項目規(guī)模擴大，代碼庫變得更模塊化，類型注釋顯著地增強了可讀性和可維護性。typing庫提供了一組豐富的特性，包括可選的各種iterable、泛型以有力支持自定義類型的功能，使開發(fā)人員能夠精確而清晰地表達復(fù)雜的數(shù)據(jù)結(jié)構(gòu)和關(guān)系。

2. 編寫防御函數(shù)和輸入驗證

盡管類型提示似乎很有幫助，但它仍然容易出錯，因為未強制執(zhí)行注釋。這些只是開發(fā)人員的額外文檔，但如果使用不同的參數(shù)類型，函數(shù)仍然會執(zhí)行。因此，需要以一種防御性的方式為函數(shù)和代碼強制執(zhí)行前置條件。因此，我們手動檢查這些類型，違反條件時拋出適當(dāng)?shù)腻e誤。

下面的函數(shù)顯示了如何使用輸入?yún)?shù)計算利息。

def calculate_interest(principal, rate, years):
	return principal * rate * years

這是簡單的操作，但這個函數(shù)是否適用于所有可能的解決方案？不，不適用于無效值作為輸入傳遞的個別情況。我們需要確保輸入值在一個有效的范圍內(nèi)，那樣函數(shù)才能正確執(zhí)行。實際上，必須滿足一些預(yù)設(shè)值條件，函數(shù)實現(xiàn)才能正確。

我們做這一步，如下所示：

from typing import Union
def calculate_interest(
	principal: Union[int, float],
	rate: float,
	years: int
) -> Union[int, float]:
	if not isinstance(principal, (int, float)):
    	    raise TypeError("Principal must be an integer or float")
	if not isinstance(rate, float):
    	    raise TypeError("Rate must be a float")
	if not isinstance(years, int):
    	    raise TypeError("Years must be an integer")
	if principal <= 0:
    	    raise ValueError("Principal must be positive")
	if rate <= 0:
    	    raise ValueError("Rate must be positive")
	if years <= 0:
    	    raise ValueError("Years must be positive")
	interest = principal * rate * years
	return interest

注意，我們使用條件語句進行輸入驗證。Python有時也用于此目的的斷言語句。然而，用于輸入驗證的斷言并不是最佳實踐，因為它們很容易被禁用，會導(dǎo)致生產(chǎn)環(huán)境中的意外行為。對于輸入驗證和強制執(zhí)行前置條件、后置條件以及代碼不變量，最好使用顯式Python條件表達式。

3. 使用生成器和Yield語句進行延遲加載

考慮這樣一個場景：您擁有一個大型文檔數(shù)據(jù)集。您需要處理文檔，并對每個文檔執(zhí)行某些操作。然而由于文件太大，您無法同時將所有文檔加載到內(nèi)存中并對它們進行預(yù)處理。

一種可行的解決方案是只在需要時將文檔加載到內(nèi)存中，并且一次只處理一個文檔，這也稱為延遲加載。即使我們知道需要什么文檔，也不會加載資源，除非有需要。當(dāng)我們的代碼中沒有使用大量文檔時，不需要在內(nèi)存中保留它們。這正是生成器和yield語句解決這個問題的方法。

生成器允許延遲加載，從而提高Python代碼執(zhí)行的內(nèi)存效率。值可以根據(jù)需要動態(tài)生成，減少了內(nèi)存占用資源，并提高了執(zhí)行速度。

import os
def load_documents(directory):
	for document_path in os.listdir(directory):
    	    with open(document_path) as _file:
        	        yield _file
def preprocess_document(document):
		filtered_document = None
		# preprocessing code for the document stored in filtered_document
		return filtered_document
directory = "docs/"
for doc in load_documents(directory):
		   preprocess_document(doc)

在上面的函數(shù)中，load_documents函數(shù)使用yield關(guān)鍵字。該方法返回類型<class generator>的對象。當(dāng)我們迭代處理這個對象時，它從最后一個yield語句所在的位置繼續(xù)執(zhí)行。因此，加載和處理單個文檔，提高了Python代碼的效率。

4. 使用上下文管理器防止內(nèi)存泄漏

對任何語言來說，有效地利用資源最重要。我們只在需要時才通過使用生成器在內(nèi)存中加載一些內(nèi)容，如上所述。然而，當(dāng)我們的程序不再需要某個資源時，關(guān)閉該資源同樣重要。我們需要防止內(nèi)存泄漏，并執(zhí)行適當(dāng)?shù)馁Y源拆卸以節(jié)省內(nèi)存。

上下文管理器簡化了資源設(shè)置和拆卸的常見用例。資源不再需要時，釋放它們很重要，即使在出現(xiàn)異常和失敗的情況下也是如此。上下文管理器使用自動清理，同時保持代碼簡潔易讀，降低內(nèi)存泄漏的風(fēng)險。

資源可以有多種變體，比如數(shù)據(jù)庫連接、鎖、線程、網(wǎng)絡(luò)連接、內(nèi)存訪問和文件句柄。不妨關(guān)注最簡單的情況：文件句柄。這里的挑戰(zhàn)是確保每個打開的文件只關(guān)閉一次。關(guān)閉文件失敗可能導(dǎo)致內(nèi)存泄漏，而試圖關(guān)閉文件句柄兩次會導(dǎo)致運行時錯誤。為了解決這個問題，應(yīng)該將文件句柄封裝在try-except-finally塊中。這確保了文件被正確關(guān)閉，不管執(zhí)行過程中是否發(fā)生了錯誤。下面是具體實現(xiàn)的樣子：

file_path = "example.txt"
file = None
try:
	file = open(file_path, 'r')
	contents = file.read()
	print("File contents:", contents)
finally:
	if file is not None:
    	file.close()

然而，Python提供了一個使用上下文管理器的更優(yōu)雅的解決方案，它自動處理資源管理。下面介紹我們?nèi)绾问褂梦募舷挛墓芾砥骱喕鲜龃a：

file_path = "example.txt"
with open(file_path, 'r') as file:
	contents = file.read()
	print("File contents:", contents)

在這個版本中，我們不需要顯式關(guān)閉文件。上下文管理器負責(zé)處理它，防止?jié)撛诘膬?nèi)存泄漏。

雖然Python為文件處理提供了內(nèi)置的上下文管理器，但我們也可以為自定義類和函數(shù)創(chuàng)建自己的上下文管理器。針對基于類的實現(xiàn)，我們定義了__enter__和__exit__dunder方法。這里有一個基本的例子：

class CustomContextManger:
	def __enter__(self):
    	    # Code to create instance of resource
    	    return self
	def __exit__(self, exc_type, exc_value, traceback):
    	    # Teardown code to close resource
     	    return None

現(xiàn)在，我們可以在“with ”塊中使用這個自定義的上下文管理器：

with CustomContextManger() as _cm:
	print("Custom Context Manager Resource can be accessed here")

這種方法保持了上下文管理器簡潔明了的語法，同時允許我們根據(jù)需要處理資源。

5. 用裝飾器分離關(guān)注點

我們經(jīng)常看到顯式地實現(xiàn)具有相同邏輯的多個函數(shù)。這是普遍存在的代碼風(fēng)格，過多的代碼重復(fù)會使代碼難以維護和不可擴展。裝飾器用于將類似的功能封裝在一個地方。當(dāng)一個相似的功能被多個其他函數(shù)使用時，我們可以通過在裝飾器中實現(xiàn)通用功能來減少代碼重復(fù)。它遵循面向方面的編程（AOP）和單一職責(zé)原則。

裝飾器在Django、Flask和FastAPI等Python Web框架中被大量使用。不妨通過在Python中將解釋器用作日志記錄的中間件來解釋裝飾器的效果。在生產(chǎn)環(huán)境中，我們需要知道服務(wù)一個請求需要多長時間。這是一個常見的用例，將在所有端點之間共享。因此，不妨實現(xiàn)一個簡單的基于裝飾器的中間件，它將記錄服務(wù)請求所花費的時間。

下面的虛擬函數(shù)用于服務(wù)用戶請求。

def service_request():
	# Function body representing complex computation
	return True

現(xiàn)在，我們需要記錄這個函數(shù)執(zhí)行所花費的時間。一種方法是在這個函數(shù)中添加日志記錄，如下所示：

import time
def service_request():
	start_time = time.time()
	# Function body representing complex computation
	print(f"Time Taken: {time.time() - start_time}s")
	return True

雖然這種方法有效，但它會導(dǎo)致代碼重復(fù)。如果我們添加更多的路由，將不得不在每個函數(shù)中重復(fù)日志代碼。這增加了代碼重復(fù)，因為這種共享日志功能需要添加到每個實現(xiàn)中。我們使用裝飾器進行移除。

日志中間件將按以下方式來實現(xiàn)：

def request_logger(func):
	def wrapper(*args, **kwargs):
    	    start_time = time.time()
    	    res = func()
    	    print(f"Time Taken: {time.time() - start_time}s")
    	    return res
	return wrapper

在這個實現(xiàn)中，外部函數(shù)是裝飾器，它接受函數(shù)作為輸入。內(nèi)部函數(shù)實現(xiàn)日志功能，而輸入函數(shù)在包裝器中被調(diào)用。

現(xiàn)在，我們只需用request_logger裝飾器裝飾原來的service_request函數(shù)：

@request_logger
def service_request():
	# Function body representing complex computation
	return True

使用@符號將service_request函數(shù)傳遞給request_logger裝飾器。它記錄所花費的時間，并在不修改代碼的情況下調(diào)用原始函數(shù)。這種關(guān)注點分離讓我們得以以類似的方式輕松地將日志記錄添加到其他服務(wù)方法中，如下所示：

@request_logger
def service_request():
	# Function body representing complex computation
	return True
@request_logger
def service_another_request():
	# Function body
	return True

6. 匹配Case語句

匹配語句是在Python3.10中引入的，所以它是Python語法的一個相當(dāng)新的添加。它允許更簡單、更易讀的模式匹配，避免了典型if- if-else語句中過多的樣板文件和分支。

針對模式匹配，匹配case語句是更自然的編寫方式，因為它們不一定需要像條件語句中那樣返回布爾值。來自Python文檔中的以下示例展示了匹配case語句聲明如何比條件語句更具靈活性。

def make_point_3d(pt):
	match pt:
    	    case (x, y):
        		return Point3d(x, y, 0)
    	    case (x, y, z):
        		return Point3d(x, y, z)
    	    case Point2d(x, y):
        		return Point3d(x, y, 0)
    	    case Point3d(_, _, _):
        		return pt
    	    case _:
        		raise TypeError("not a point we support")

根據(jù)文檔，如果沒有模式匹配，這個函數(shù)的實現(xiàn)將需要幾次isinstance()檢查、一兩個len()調(diào)用以及一個更復(fù)雜的控制流。揭開底層，匹配示例和傳統(tǒng)Python版本轉(zhuǎn)換成相似的代碼。然而，熟悉模式匹配后，可能會首選匹配case方法，因為它提供了更清晰、更自然的語法。

總的來說，匹配case語句為模式匹配提供了一種經(jīng)過改進的替代方案，這可能會在較新的代碼庫中變得更加普遍。

7. 外部配置文件

在生產(chǎn)環(huán)境中，我們的大部分代碼依賴外部配置參數(shù)，比如API密鑰、密碼和各種設(shè)置。出于可擴展性和安全性的考慮，將這些值直接硬編碼到代碼中被認為是糟糕的做法。相反，將配置與代碼本身分開來至關(guān)重要。我們通常使用JSON或YAML等配置文件來存儲這些參數(shù)，確保它們易于訪問代碼，無需直接嵌入到其中。

一種日常的用例是實現(xiàn)多個連接參數(shù)的數(shù)據(jù)庫連接。

我們可以將這些參數(shù)保留在一個單獨的YAML文件中。

# config.yaml
database:
  host: localhost
  port: 5432
  username: myuser
  password: mypassword
  dbname: mydatabase

為了處理這個配置，我們定義了一個名為DatabaseConfig的類：

class DatabaseConfig:
	def __init__(self, host, port, username, password, dbname):
    	    self.host = host
    	    self.port = port
    	    self.username = username
    	    self.password = password
    	    self.dbname = dbname
	@classmethod
	def from_dict(cls, config_dict):
    	    return cls(**config_dict)

在這里，from_dict類方法充當(dāng)DatabaseConfig類的構(gòu)建器方法，允許我們從字典創(chuàng)建數(shù)據(jù)庫配置實例。

在我們的主代碼中，我們可以使用參數(shù)hydration和構(gòu)建器方法來創(chuàng)建數(shù)據(jù)庫配置。通過讀取外部YAML文件，我們提取數(shù)據(jù)庫字典，并使用它為配置類創(chuàng)建實例：

import yaml
def load_config(filename):
	with open(filename, "r") as file:
    	return yaml.safe_load(file)
config = load_config("config.yaml")
db_config = DatabaseConfig.from_dict(config["database"])

這種方法不需要將數(shù)據(jù)庫配置參數(shù)直接硬編碼到代碼中。它還比使用參數(shù)解析器有所改進，因為我們不再需要在每次運行代碼時傳遞多個參數(shù)。此外，通過參數(shù)解析器訪問配置文件路徑，我們可以確保代碼保持靈活性，而不依賴硬編碼路徑。這種方法便于更容易管理配置參數(shù)，可以隨時修改配置參數(shù)，不需要更改代碼庫。

結(jié)束語

我們在本文中討論了業(yè)界用于生產(chǎn)就緒代碼的一些最佳實踐。這些都是常見的行業(yè)實踐，可以緩解人們在實際情形中可能面臨的多個問題。

值得一提的是，盡管有所有這些最佳實踐，文檔、文檔字符串和測試驅(qū)動開發(fā)是迄今為止最重要的實踐。重要的是要考慮一個函數(shù)應(yīng)該做什么，然后將所有的設(shè)計決策和實現(xiàn)記入文檔，因為隨著時間的推移，人們不斷更改代碼庫。

原文標題： Mastering Python: 7 Strategies for Writing Clear, Organized, and Efficient Code，作者：Kanwal Mehreen

鏈接：https://www.kdnuggets.com/mastering-python-7-strategies-for-writing-clear-organized-and-efficient-code