在我們的 data_tools.py 中，我們創(chuàng)建一個(gè)函數(shù)來演示典型的數(shù)據(jù)工程邏輯，例如從 CSV 加載數(shù)據(jù)并清理它：

專業(yè)提示：在 Python 中堅(jiān)持使用 snake_case

對(duì)于較小的函數(shù)，PEP 257 通常就足夠了，但對(duì)于更復(fù)雜的項(xiàng)目，Google 或 NumPy 樣式提供了更多的清晰度和結(jié)構(gòu)。

Python 中的類型提示（如我們示例中的 file_path: str）顯示函數(shù)輸入和輸出的預(yù)期數(shù)據(jù)類型。它們提高了可讀性，幫助發(fā)現(xiàn)錯(cuò)誤，并通過設(shè)定明確的期望使協(xié)作變得更容易。

以下是類型提示如何改進(jìn)函數(shù)簽名的示例：

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

在這個(gè)例子中，類型提示 file_path: str 表明參數(shù)應(yīng)該是一個(gè)字符串，而 ->; pd.DataFrame 指示該函數(shù)返回一個(gè) Pandas DataFrame。這使得該函數(shù)的行為一目了然。類型提示還可以與 IDE 和 linter（例如 PyCharm、VSCode 或 mypy）很好地配合使用，在傳遞不兼容的類型時(shí)提供自動(dòng)完成和早期警告。

如果函數(shù)可以返回多種類型或無(wú)，您可以使用輸入模塊中的可選：

pyenv install 3.12.2

這表明該函數(shù)可以返回字符串或 None。對(duì)于更復(fù)雜的數(shù)據(jù)結(jié)構(gòu)，您可以使用輸入模塊中的 List、Dict 或 Tuple 來指定預(yù)期類型。

第 6 步：編寫測(cè)試

編寫單元測(cè)試是一種簡(jiǎn)單的方法，可以確保您的代碼執(zhí)行預(yù)期的操作，而不會(huì)出現(xiàn)意外的情況。它們可以幫助您及早發(fā)現(xiàn)錯(cuò)誤并充滿信心地進(jìn)行更改，因?yàn)槟酪磺腥匀话搭A(yù)期運(yùn)行。在 Python 中，有多個(gè)可用于單元測(cè)試的庫(kù)，每個(gè)庫(kù)都有其優(yōu)點(diǎn)和生態(tài)系統(tǒng)：

• 單元測(cè)試

• pytest

• 鼻子2

• 假設(shè)

對(duì)于本指南，我們將使用 pytest 因?yàn)樗?jiǎn)單、靈活且易于使用。您可以使用以下命令安裝它：

brew update && brew upgrade pyenv

接下來，在 tests/ 文件夾中創(chuàng)建一個(gè)名為 test_data_tools.py 的文件。讓我們?yōu)橹皩?shí)現(xiàn)的代碼編寫一些測(cè)試。這是我們的 load_and_clean_data() 函數(shù)和環(huán)境變量檢索邏輯的示例測(cè)試：

在 test_load_and_clean_data() 中，我們使用 StringIO 模擬 CSV 文件作為輸入。這使我們無(wú)需實(shí)際文件即可進(jìn)行測(cè)試。該測(cè)試驗(yàn)證該函數(shù)是否正確刪除重復(fù)項(xiàng)和 NaN 值，檢查 DataFrame 是否沒有丟失數(shù)據(jù)，并確認(rèn)“名稱”列中的唯一條目正確。

在test_get_database_url()和test_get_api_key()中，我們使用pytest提供的monkeypatch工具來在測(cè)試過程中臨時(shí)設(shè)置環(huán)境變量。這確保函數(shù)返回預(yù)期值，而不需要真正的環(huán)境變量。

要運(yùn)行所有測(cè)試，只需執(zhí)行以下命令：

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

我喜歡pytest的原因之一是它的靈活性。它超越了基本的單元測(cè)試，提供了強(qiáng)大的功能，如夾具、參數(shù)化測(cè)試和插件。夾具可讓您設(shè)置多個(gè)測(cè)試可以重復(fù)使用的測(cè)試數(shù)據(jù)或配置，從而使您的代碼保持干燥（不要重復(fù)）。參數(shù)化測(cè)試允許您使用不同的輸入運(yùn)行相同的測(cè)試，從而節(jié)省時(shí)間并減少重復(fù)。如果您需要擴(kuò)展 pytest 的功能，可以使用廣泛的插件生態(tài)系統(tǒng)，例如測(cè)試 Django 應(yīng)用程序、測(cè)量代碼覆蓋率或模擬 HTTP 請(qǐng)求。

第 7 步：代碼質(zhì)量和預(yù)提交 Hook

保持高代碼質(zhì)量可確保您的代碼易于閱讀、維護(hù)并且沒有常見錯(cuò)誤。有多種工具可以幫助實(shí)施一致的編碼標(biāo)準(zhǔn)、自動(dòng)格式化代碼并及早檢測(cè)潛在問題。一些流行的選項(xiàng)包括 pylint、flake8、黑色 和 檢測(cè)秘密。

• pylint 強(qiáng)制執(zhí)行編碼標(biāo)準(zhǔn)并捕獲常見錯(cuò)誤。

• flake8 結(jié)合了檢測(cè)樣式違規(guī)和邏輯錯(cuò)誤的工具。

• black 是一個(gè)固執(zhí)己見的格式化程序，可確保您的代碼遵循 PEP8 標(biāo)準(zhǔn)。

• 檢測(cè)秘密掃描您的代碼以防止硬編碼的秘密被暴露。

您可以通過以下方式安裝這些工具：

pyenv install 3.12.2

例如，在特定文件或目錄上運(yùn)行 pylint：

brew update && brew upgrade pyenv

您將收到一份報(bào)告，其中包含警告和改進(jìn)代碼的建議。要忽略特定警告，您可以使用：

brew install readline xz

您還可以使用flake8來查找樣式問題和邏輯錯(cuò)誤：

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

要自動(dòng)格式化代碼，請(qǐng)運(yùn)行 black:

pyenv install 3.12.2

您可以使用預(yù)提交掛鉤自動(dòng)執(zhí)行該過程，而不是每次進(jìn)行更改時(shí)手動(dòng)運(yùn)行這些工具。預(yù)提交掛鉤在每次提交之前自動(dòng)運(yùn)行，如果任何工具失敗，則會(huì)阻止提交。

首先，安裝預(yù)提交軟件包：

brew update && brew upgrade pyenv

接下來，在項(xiàng)目目錄中創(chuàng)建一個(gè) .pre-commit-config.yaml 文件，其中包含以下內(nèi)容（這里我使用了所有我最喜歡的基本預(yù)提交）：

激活本地存儲(chǔ)庫(kù)中的預(yù)提交掛鉤：

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

現(xiàn)在，每次您嘗試提交時(shí)，這些工具都會(huì)自動(dòng)運(yùn)行。如果任何工具失敗，提交將被阻止，直到問題得到解決。您還可以在代碼庫(kù)中手動(dòng)運(yùn)行所有掛鉤：

pyenv install 3.12.2

第8步：創(chuàng)建分發(fā)包

現(xiàn)在我們已經(jīng)構(gòu)建了我們的項(xiàng)目，編寫了一些代碼，添加了測(cè)試并設(shè)置了預(yù)提交掛鉤，下一步是弄清楚其他人（甚至未來的我們）如何輕松使用它。打包項(xiàng)目使這成為可能。它允許我們將所有內(nèi)容整齊地捆綁在一起，以便無(wú)需手動(dòng)復(fù)制文件即可安裝和使用。

要共享您的項(xiàng)目，您需要正確構(gòu)建包、編寫有意義的自述文件、創(chuàng)建啟動(dòng)腳本并生成分發(fā)包。一個(gè)好的自述文件通常包括項(xiàng)目名稱和其功能的簡(jiǎn)要描述、安裝說明、使用示例、設(shè)置環(huán)境的開發(fā)說明以及貢獻(xiàn)指南。您可以在存儲(chǔ)庫(kù)中找到我們的 blog_de_toolkit 項(xiàng)目的簡(jiǎn)單 README.md 示例。

任何 Python 包的核心都是 setup.py 文件。該文件是我們定義打包和安裝項(xiàng)目所需的元數(shù)據(jù)和配置的地方。它包括項(xiàng)目的 名稱、版本和描述，這使其可識(shí)別。 long_description 從 README 文件中讀取內(nèi)容，以便當(dāng)用戶在 PyPI 上看到該項(xiàng)目時(shí)為他們提供有關(guān)該項(xiàng)目的更多背景信息。我們?cè)?install_requires 列表中指定依賴項(xiàng)，以便它們與包一起自動(dòng)安裝。 entry_points 部分定義了命令行界面 (CLI) 條目，以便用戶可以從終端運(yùn)行該工具。我們使用 find_packages() 來包含包中的所有子模塊，并且 classifiers 部分提供元數(shù)據(jù)，例如項(xiàng)目使用的 Python 版本和許可證。最后，python_requires 字段確保包僅安裝在兼容的 Python 版本上。這是我們的 blog_de_toolkit 項(xiàng)目的 setup.py 配置：

配置setup.py后，您可以構(gòu)建分發(fā)包。首先安裝必要的工具：

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

然后構(gòu)建包：

pyenv install 3.12.2

此命令創(chuàng)建兩個(gè)分發(fā)文件：

• sdist：源存檔（例如 .tar.gz）

• bdist_wheel：構(gòu)建的包（例如.whl）

這些文件將位于 dist/ 目錄中。要測(cè)試該包，請(qǐng)使用以下命令在本地安裝它：

brew update && brew upgrade pyenv

您還可以通過運(yùn)行來測(cè)試 CLI 命令：

brew install readline xz

他應(yīng)該打印數(shù)據(jù)庫(kù) URL、API 密鑰以及來自 sample_data.csv.

如果您想公開分享該包，您可以將其上傳到PyPI。首先，安裝 Twine：

pyenv virtualenv 3.12.2 de_toolkit

然后上傳包：

pyenv local de_toolkit

系統(tǒng)將提示您輸入 PyPI 憑據(jù)。上傳后，其他人可以直接從 PyPI 安裝您的包：

pip install setuptools wheel twine pandas 

第10步：保護(hù)主分支

隨著您的項(xiàng)目的發(fā)展，更多的人通常會(huì)同時(shí)在同一個(gè)代碼庫(kù)上工作。如果沒有適當(dāng)?shù)谋Ｗo(hù)措施，錯(cuò)誤、未經(jīng)測(cè)試的代碼或意外合并很容易潛入并造成混亂。為了保持事情順利進(jìn)行并保持高標(biāo)準(zhǔn)，保護(hù)主干就變得至關(guān)重要。在此步驟中，我們將了解如何設(shè)置分支保護(hù)規(guī)則，并分享一些對(duì)拉取請(qǐng)求進(jìn)行順利代碼審查的技巧。

分支保護(hù)規(guī)則確保任何人都無(wú)法在未通過測(cè)??試或代碼審查的情況下直接推送到主分支。這可以防止未完成的功能、錯(cuò)誤或不良代碼潛入并破壞項(xiàng)目。它還通過要求拉取請(qǐng)求來促進(jìn)團(tuán)隊(duì)合作，讓其他人有機(jī)會(huì)提供反饋。另外，自動(dòng)檢查（如測(cè)試和 linter）可確保代碼在合并之前是可靠的。

在 GitHub 上設(shè)置分支保護(hù)規(guī)則非常簡(jiǎn)單。前往存儲(chǔ)庫(kù)的設(shè)置，然后單擊“代碼和自動(dòng)化”部分下的分支。查找分支保護(hù)規(guī)則并單擊添加分支保護(hù)規(guī)則。在分支名稱字段中輸入 main，現(xiàn)在是時(shí)候調(diào)整一些設(shè)置了。

您可以設(shè)置分支保護(hù)規(guī)則來要求拉取請(qǐng)求審查，確保有人在合并之前檢查代碼。狀態(tài)檢查確保測(cè)試通過并且 linter 順利運(yùn)行，并使分支保持最新更改有助于避免沖突。如果需要，您可以限制誰(shuí)可以推送到分支，甚至需要簽名提交以提高安全性。一切設(shè)置完畢后，單擊創(chuàng)建，就像這樣 - 不再直接推送或跳過測(cè)試。

當(dāng)您的拉取請(qǐng)求接受審核時(shí)，最好讓審核者感到輕松。首先清楚地描述您的更改的作用以及為什么需要它們。使用有意義的提交消息來反映已更新的內(nèi)容。如果更改較小且重點(diǎn)突出，則審核過程會(huì)變得更加順利和更快。不要忘記禮貌地回復(fù)評(píng)論并跟進(jìn)請(qǐng)求的更改 - 這表明您重視反饋并有助于保持積極的合作。

如果您是審查拉取請(qǐng)求的人，那么您的工作不僅僅是發(fā)現(xiàn)錯(cuò)誤 - 還包括改進(jìn)代碼并支持您的隊(duì)友。首先閱讀拉取請(qǐng)求描述，以了解更改試圖實(shí)現(xiàn)的目標(biāo)。專注于提供建設(shè)性反饋——如果需要，建議替代方案，并解釋為什么它們可能效果更好。通過簡(jiǎn)單的“重構(gòu)不錯(cuò)？！”來認(rèn)可優(yōu)秀的工作還有助于創(chuàng)造積極的評(píng)論體驗(yàn)。密切關(guān)注測(cè)試，確保它們存在、相關(guān)且通過。如果有些事情不清楚，請(qǐng)?zhí)岢鰡栴}而不是做出假設(shè)。歸根結(jié)底，評(píng)論是關(guān)于團(tuán)隊(duì)合作的——合作使項(xiàng)目變得更好。

使用審核模板可以讓每個(gè)人都專注于重要的事情，從而使流程更加順利。以下是拉取請(qǐng)求審核模板的示例：

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

將這樣的模板添加到您的貢獻(xiàn)指南中或?qū)⑵滏溄拥酱鎯?chǔ)庫(kù)中，可以讓審閱者輕松保持在正軌上。它還使評(píng)論之間的內(nèi)容保持一致，幫助團(tuán)隊(duì)維護(hù)干凈且有組織的代碼庫(kù)。

第 11 步：CI/CD 的 GitHub Actions

基于保護(hù)主分支的重要性，確保在合并或部署之前對(duì)每個(gè)代碼更改進(jìn)行正確的測(cè)試、審查和驗(yàn)證也至關(guān)重要。這就是持續(xù)集成（CI）和持續(xù)交付/部署（CD）發(fā)揮作用的地方。 CI/CD 自動(dòng)化運(yùn)行測(cè)試、執(zhí)行代碼檢查和部署更改的過程，為開發(fā)人員提供快速反饋并減少錯(cuò)誤進(jìn)入生產(chǎn)的機(jī)會(huì)。

GitHub Actions 是直接集成到 GitHub 中的自動(dòng)化工具。它使您能夠創(chuàng)建響應(yīng)存儲(chǔ)庫(kù)中的事件（例如推送或拉取請(qǐng)求）的工作流程。在 GitHub Actions 中，我們可以自動(dòng)執(zhí)行多項(xiàng)關(guān)鍵任務(wù)以維護(hù)健康的代碼庫(kù)。例如：

• 每當(dāng)推送代碼或創(chuàng)建拉取請(qǐng)求時(shí)運(yùn)行測(cè)試，確保新的更改不會(huì)破壞任何內(nèi)容。

• 檢查代碼風(fēng)格和 linting 以執(zhí)行一致的編碼標(biāo)準(zhǔn)。

• 應(yīng)用預(yù)提交掛鉤來格式化代碼并捕獲尾隨空格等小問題。

• 在所有檢查通過后生成文檔甚至部署代碼。

讓我們?cè)O(shè)置一個(gè) GitHub Actions 工作流程，運(yùn)行我們的單元測(cè)試，并在主分支上發(fā)生推送或拉取請(qǐng)求時(shí)應(yīng)用預(yù)提交 linter（如黑色）。

首先，創(chuàng)建工作流程文件：

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

這是ci.yml的內(nèi)容：

每當(dāng)在主分支上推送代碼或打開拉取請(qǐng)求時(shí)，此工作流程都會(huì)自動(dòng)進(jìn)行測(cè)試和檢查。它確保在合并代碼之前通過所有質(zhì)量檢查。 actions/checkout 操作將存儲(chǔ)庫(kù)克隆到運(yùn)行器中，我們使用 actions/setup-python 為工作流程配置 Python 3.12。依賴項(xiàng)是使用 pip 從requirements.txt 安裝的。之后，所有測(cè)試都使用 pytest 運(yùn)行，預(yù)提交掛鉤確保代碼遵循格式和樣式指南。如果任何測(cè)試或檢查失敗，工作流程就會(huì)停止，以防止損壞的代碼被合并。

讓我們測(cè)試一下。首先，從主分支創(chuàng)建一個(gè)新分支并進(jìn)行一些更改。

就我而言，我更新了自述文件文件。提交您的更改并向主分支打開拉取請(qǐng)求。

現(xiàn)在您將看到需要進(jìn)行審核，并且 GitHub Actions (GA) 正在運(yùn)行所有檢查。即使合并被分支保護(hù)規(guī)則阻止，我仍然可以“無(wú)需等待滿足要求即可合并”，因?yàn)槲业臋?quán)限允許繞過保護(hù)。

您可以在 Actions 選項(xiàng)卡中跟蹤 GitHub Actions 工作流程的結(jié)果。

以下是運(yùn)行期間 pytest 步驟的示例：

第 12 步：語(yǔ)義版本控制 (SemVer)

手動(dòng)跟蹤項(xiàng)目的版本可能會(huì)變得混亂，尤其是隨著項(xiàng)目的增長(zhǎng)。這就是 語(yǔ)義版本控制 (SemVer) 的用武之地 - 它遵循 MAJOR.MINOR.PATCH 模式來傳達(dá)每個(gè)版本中發(fā)生的更改。使用 python-semantic-release 自動(dòng)進(jìn)行版本控制使這變得更加容易。它會(huì)分析您的提交消息，根據(jù)更改類型、標(biāo)記版本來升級(jí)版本，如果需要，甚至可以將您的包發(fā)布到 PyPI。這消除了版本管理中的猜測(cè)并確保了一致性。

為了實(shí)現(xiàn)無(wú)縫版本控制，您可以將 python-semantic-release 直接集成到 GitHub Actions 中。官方文檔提供了每當(dāng)您推送到主分支時(shí)自動(dòng)進(jìn)行版本更新和發(fā)布的工作流程。通過此設(shè)置，發(fā)布過程變得順暢且無(wú)需干預(yù)，因此您可以專注于編寫代碼，而不必?fù)?dān)心手動(dòng)管理版本。

常見工作流程示例 — python-semantic-release

為了實(shí)現(xiàn)此目的，您的提交消息需要遵循傳統(tǒng)的提交標(biāo)準(zhǔn)。每種類型的提交決定版本是否會(huì)提升 PATCH、MINOR 或 MAJOR 級(jí)別：

• 修復(fù)：觸發(fā) PATCH 版本更新（例如 1.0.0 → 1.0.1）。

• 壯舉：觸發(fā)次要版本更新（例如，1.0.0 → 1.1.0）。

• 重大更改：提交消息中的 或 ! 會(huì)觸發(fā)主要版本更新（例如，1.0.0 → 2.0.0）。

通過遵循這些簡(jiǎn)單的約定，您將始終知道每個(gè)新版本會(huì)發(fā)生什么。

結(jié)論

我們涵蓋了從組織項(xiàng)目和管理機(jī)密到編寫測(cè)試、自動(dòng)化工作流程以及使用語(yǔ)義版本控制處理發(fā)布的所有內(nèi)容。有了正確的工具和流程，構(gòu)建可靠且可維護(hù)的項(xiàng)目就會(huì)變得更加順利，甚至充滿樂趣。

關(guān)鍵是保持一致，盡可能實(shí)現(xiàn)自動(dòng)化，并不斷改進(jìn)。隨著時(shí)間的推移，每一個(gè)小步驟都會(huì)產(chǎn)生很大的變化?，F(xiàn)在輪到你了——去構(gòu)建、實(shí)驗(yàn)并享受這個(gè)過程！嘗試將這些步驟應(yīng)用到您的下一個(gè)項(xiàng)目中 - 并隨時(shí)在評(píng)論中分享您的經(jīng)驗(yàn)！

以上是為初學(xué)者組織和維護(hù) Python 代碼庫(kù)的步驟的詳細(xì)內(nèi)容。更多信息請(qǐng)關(guān)注PHP中文網(wǎng)其他相關(guān)文章！