如何建立一個完美的 Python 項目？

• 原文地址：How to set up a perfect Python project^[1]
• 原文作者：Brendan Maginnis
• 譯者：HelloGitHub-丫丫
• 校對者：HelloGitHub-削微寒

當開始一個新的 Python 項目時，大家很容易一頭扎進去就開始編碼。其實花一點時間選擇優(yōu)秀的庫，將為以后的開發(fā)節(jié)省大量時間，并帶來更快樂的編碼體驗。

在理想世界中，所有開發(fā)人員的關(guān)系是相互依賴和關(guān)聯(lián)的（協(xié)作開發(fā)），代碼要有完美的格式、沒有低級的錯誤、并且測試覆蓋了所有代碼。另外，所有這些將在每次提交時都可以得到保證。（代碼風(fēng)格統(tǒng)一、類型檢測、測試覆蓋率高、自動檢測）

在本文中，我將介紹如何建立一個可以做到這些點的項目。您可以按照步驟操作，也可以直接跳到?使用 cookiecutter 生成項目?部分（老手）。

首先，讓我們創(chuàng)建一個新的項目目錄：

mkdir?best_practices
cd?best_practices

pipx 安裝 Python 三方庫的命令行工具

Pipx^[2]?是一個可用于快速安裝 Python 三方庫的命令行工具。我們將使用它來安裝 pipenv 和 cookiecutter。通過下面的命令安裝 pipx：

python3?-m?pip?install?--user?pipx
python3?-m?pipx?ensurepath

使用 pipenv 進行依賴管理

Pipenv^[3]?為您的項目自動創(chuàng)建和管理 virtualenv（虛擬環(huán)境），并在安裝/卸載軟件包時從 Pipfile 添加/刪除軟件包。它還會生成非常重要的 Pipfile.lock 用于保證依賴的可靠性。

當你知道，你和你的隊友正在使用相同的庫版本時，這將會極大地提高編程的信心和樂趣。Pipenv 很好地解決了使用相同的庫，版本不同的這一問題，Pipenv 在過去的一段時間里獲得了廣泛的關(guān)注和認可，你可以放心使用。安裝命令如下：

pipx?install?pipenv

使用 black 和 isort 進行代碼格式化

black^[4]?可以格式化我們的代碼：

Black 是毫不妥協(xié)的 Python 代碼格式化庫。通過使用它，你將放棄手動調(diào)整代碼格式的細節(jié)。作為回報，Black 可以帶來速度、確定性和避免調(diào)整 Python 代碼風(fēng)格的煩惱，從而有更多的精力和時間放在更重要的事情上。

無論你正在閱讀什么樣的項目，用 black 格式化過的代碼看起來都差不多。一段時間后格式不再是問題，這樣你就可以更專注于內(nèi)容。

black 通過減少代碼的差異性，使代碼檢查更快。

而?isort^[5]?是對我們的 imports 部分進行排序：

isort 為您導(dǎo)入的 Python 包部分（imports）進行排序，因此你不必再對 imports 進行手動排序。它可以按字母順序?qū)?dǎo)入進行排序，并自動將其拆分成多個部分。

使用 pipenv 安裝它，以便它們不會使部署混亂（可以指定只在開發(fā)環(huán)境安裝）：

pipenv?install?black?isort?--dev

Black 和 isort 并不兼容的默認選項，因此我們將讓 isort 遵循 black 的原則。創(chuàng)建一個?setup.cfg?文件并添加以下配置：

[isort]
multi_line_output=3
include_trailing_comma=True
force_grid_wrap=0
use_parentheses=True
line_length=88

我們可以使用以下命令運行這些工具：

pipenv?run?black
pipenv?run?isort

使用 flake8 保證代碼風(fēng)格

Flake8 確保代碼遵循 PEP8 中定義的標準 Python 代碼規(guī)范。使用 pipenv 安裝：

pipenv?install?flake8?--dev

就像 isort 一樣，它需要一些配置才能很好地與 black 配合使用。將這些配置添加到?setup.cfg?：

[flake8]
ignore?=?E203,?E266,?E501,?W503
max-line-length?=?88
max-complexity?=?18
select?=?B,C,E,F,W,T4

現(xiàn)在我們可以運行 flake8 了，命令：pipenv run flake8?。

使用 mypy 進行靜態(tài)類型檢查

Mypy^[6]?是 Python 的非強制的靜態(tài)類型檢查器，旨在結(jié)合動態(tài)（或 “鴨子”）類型和靜態(tài)類型的優(yōu)點。Mypy 將 Python 的表達能力和便利性與功能強大的類型系統(tǒng)的編譯時類型檢查結(jié)合在一起，使用任何 Python VM 運行它們，基本上沒有運行時開銷。

在 Python 中使用類型需要一點時間來適應(yīng)，但是好處卻是巨大的。如下：

• 靜態(tài)類型可以使程序更易于理解和維護
• 靜態(tài)類型可以幫助您更早地發(fā)現(xiàn)錯誤，并減少測試和調(diào)試的時間
• 靜態(tài)類型可以幫助您在代碼投入生產(chǎn)之前發(fā)現(xiàn)難以發(fā)現(xiàn)的錯誤

pipenv?install?mypy?--dev

默認情況下，Mypy 將遞歸檢查所有導(dǎo)入包的類型注釋，當庫不包含這些注釋時，就會報錯。我們需要將 mypy 配置為僅在我們的代碼上運行，并忽略沒有類型注釋的導(dǎo)入錯誤。我們假設(shè)我們的代碼位于以下配置的?best_practices?包中。將此添加到?setup.cfg?：

[mypy]
files=best_practices,test
ignore_missing_imports=true

現(xiàn)在我們可以運行 mypy 了：

pipenv?run?mypy

這是一個有用的?備忘單^[7]?。

用 pytest 和 pytest-cov 進行測試

使用?pytest^[8]?編寫測試非常容易，消除編寫測試的阻力意味著可以快速的編寫更多的測試！

pipenv?install?pytest?pytest-cov?--dev

這是 pytest 網(wǎng)站上的一個簡單示例：

#?content?of?test_sample.py
def?inc(x):
????return?x?+?1

def?test_answer():
????assert?inc(3)?==?5

要執(zhí)行它：

$?pipenv?run?pytest
===========================?test?session?starts?============================
platform?linux?--?Python?3.x.y,?pytest-5.x.y,?py-1.x.y,?pluggy-0.x.y
cachedir:?$PYTHON_PREFIX/.pytest_cache
rootdir:?$REGENDOC_TMPDIR
collected?1?item

test_sample.py?F?????????????????????????????????????????????????????[100%]

=================================?FAILURES?=================================
_______________________________?test_answer?________________________________

????def?test_answer():
>???????assert?inc(3)?==?5
E???????assert?4?==?5
E????????+??where?4?=?inc(3)

test_sample.py:6:?AssertionError
=========================?1?failed?in?0.12?seconds?=========================

我們所有的測試代碼都放在?test?目錄中，因此請將此目錄添加到?setup.cfg?：

[tool:pytest]
testpaths=test

如果還想查看測試覆蓋率。創(chuàng)建一個新文件?.coveragerc，指定只返回我們的項目代碼的覆蓋率統(tǒng)計信息。比如示例的?best_practices?項目，設(shè)置如下：

[run]
source?=?best_practices

[report]
exclude_lines?=
????#?Have?to?re-enable?the?standard?pragma
????pragma:?no?cover

????#?Don't?complain?about?missing?debug-only?code:
????def?__repr__
????if?self\.debug

????#?Don't?complain?if?tests?don't?hit?defensive?assertion?code:
????raise?AssertionError
????raise?NotImplementedError

????#?Don't?complain?if?non-runnable?code?isn't?run:
????if?0:
????if?__name__?==?.__main__.:

現(xiàn)在，我們就可以運行測試并查看覆蓋率了。

pipenv?run?pytest?--cov?--cov-fail-under=100

--cov-fail-under=100?是設(shè)定項目的測試覆蓋率如果小于 100％ 那將認定為失敗。

pre-commit 的 Git hooks

Git hooks 可讓您在想要提交或推送時隨時運行腳本。這使我們能夠在每次提交/推送時，自動運行所有檢測和測試。pre-commit^[9]?可輕松配置這些 hooks。

Git hook 腳本對于在提交代碼審查之前，識別簡單問題很有用。我們在每次提交時都將運行 hooks，以自動指出代碼中的問題，例如缺少分號、尾隨空白和調(diào)試語句。通過在 code review 之前指出這些問題，代碼審查者可以專注于變更的代碼內(nèi)容，而不會浪費時間處理這些瑣碎的樣式問題。

在這里，我們將上述所有工具配置為在提交 Python 代碼改動時執(zhí)行（git commit），然后僅在推送時運行 pytest coverage（因為測試要在最后一步）。創(chuàng)建一個新文件?.pre-commit-config.yaml，配置如下：

repos:
??-?repo:?local
????hooks:
??????-?id:?isort
????????name:?isort
????????stages:?[commit]
????????language:?system
????????entry:?pipenv?run?isort
????????types:?[python]

??????-?id:?black
????????name:?black
????????stages:?[commit]
????????language:?system
????????entry:?pipenv?run?black
????????types:?[python]

??????-?id:?flake8
????????name:?flake8
????????stages:?[commit]
????????language:?system
????????entry:?pipenv?run?flake8
????????types:?[python]
????????exclude:?setup.py

??????-?id:?mypy
????????name:?mypy
????????stages:?[commit]
????????language:?system
????????entry:?pipenv?run?mypy
????????types:?[python]
????????pass_filenames:?false

??????-?id:?pytest
????????name:?pytest
????????stages:?[commit]
????????language:?system
????????entry:?pipenv?run?pytest
????????types:?[python]

??????-?id:?pytest-cov
????????name:?pytest
????????stages:?[push]
????????language:?system
????????entry:?pipenv?run?pytest?--cov?--cov-fail-under=100
????????types:?[python]
????????pass_filenames:?false

如果需要跳過這些 hooks，可以運行?git commit --no-verify?或?git push --no-verify

使用 cookiecutter 生成項目

現(xiàn)在，我們已經(jīng)知道了理想項目中包含了什么，我們可以將其轉(zhuǎn)換為?模板^[10]?從而可以使用單個命令生成一個包含這些庫和配置的新項目：

pipx?run?cookiecutter?gh:sourcery-ai/python-best-practices-cookiecutter

填寫項目名稱和倉庫名稱，將為您生成新的項目。

要完成設(shè)置，請執(zhí)行下列步驟：

#?Enter?project?directory
cd?

#?Initialise?git?repo
git?init

#?Install?dependencies
pipenv?install?--dev

#?Setup?pre-commit?and?pre-push?hooks
pipenv?run?pre-commit?install?-t?pre-commit
pipenv?run?pre-commit?install?-t?pre-push

模板項目包含一個非常簡單的 Python 文件和測試，可以試用上面這些工具。在編寫完代碼覺得沒問題后，就可以執(zhí)行第一次?git commit，所有的 hooks 都將運行。

集成到編輯器

雖然在提交時知道項目的代碼始終保持最高水準是件令人興奮的事情。但如果在代碼已全部修改完成之后（提交時），再發(fā)現(xiàn)有問題還是會讓人很不爽。所以，實時暴露出問題要好得多。

在保存文件時，花一些時間確保代碼編輯器運行這些命令。有及時的反饋，這意味著你可以在代碼還有印象的時候能迅速解決引入的任何小問題。

我個人使用一些出色的 Vim 插件來完成此任務(wù)：

• ale^[11]?實時運行 flake8 并在保存文件時運行 black、isort 和 mypy
• 與?projectionist 集成的^[12]?vim-test^[13]?在文件保存上運行 pytest

參考資料