> * 原文地址：[How to set up a perfect Python project](https://sourcery.ai/blog/python-best-practices/) > * 原文作者：Brendan Maginnis > * 譯者：HelloGitHub-丫丫 > * 校對者：HelloGitHub-削微寒  當開始一個新的 Python 專案時，大家很容易一頭扎進去就開始編碼。其實花一點時間選擇優秀的庫，將為以後的開發節省大量時間，並帶來更快樂的編碼體驗。 在理想世界中，所有開發人員的關係是相互依賴和關聯的（協作開發），程式碼要有完美的格式、沒有低階的錯誤、並且測試覆蓋了所有程式碼。另外，所有這些將在每次提交時都可以得到保證。（程式碼風格統一、型別檢測、測試覆蓋率高、自動檢測） 在本文中，我將介紹如何建立一個可以做到這些點的專案。您可以按照步驟操作，也可以直接跳到 **使用 cookiecutter 生成專案** 部分（老手）。 首先，讓我們建立一個新的專案目錄： ```shell mkdir best_practices cd best_practices ``` ## pipx 安裝 Python 三方庫的命令列工具 [Pipx](https://pipxproject.github.io/pipx/) 是一個可用於快速安裝 Python 三方庫的命令列工具。我們將使用它來安裝 pipenv 和 cookiecutter。通過下面的命令安裝 pipx： ```shell python3 -m pip install --user pipx python3 -m pipx ensurepath ``` ## 使用 pipenv 進行依賴管理 > [Pipenv](https://github.com/pypa/pipenv) 為您的專案自動建立和管理 virtualenv（虛擬環境），並在安裝/解除安裝軟體包時從 Pipfile 新增/刪除軟體包。它還會生成非常重要的 Pipfile.lock 用於保證依賴的可靠性。 當你知道，你和你的隊友正在使用相同的庫版本時，這將會極大地提高程式設計的信心和樂趣。Pipenv 很好地解決了使用相同的庫，版本不同的這一問題，Pipenv 在過去的一段時間裡獲得了廣泛的關注和認可，你可以放心使用。安裝命令如下： ```shell pipx install pipenv ``` ## 使用 black 和 isort 進行程式碼格式化 [black](https://github.com/psf/black) 可以格式化我們的程式碼： > Black 是毫不妥協的 Python 程式碼格式化庫。通過使用它，你將放棄手動調整程式碼格式的細節。作為回報，Black 可以帶來速度、確定性和避免調整 Python 程式碼風格的煩惱，從而有更多的精力和時間放在更重要的事情上。 > > 無論你正在閱讀什麼樣的專案，用 black 格式化過的程式碼看起來都差不多。一段時間後格式不再是問題，這樣你就可以更專注於內容。 > > black 通過減少程式碼的差異性，使程式碼檢查更快。 而 [isort](https://github.com/timothycrosley/isort) 是對我們的 imports 部分進行排序： > isort 為您匯入的 Python 包部分（imports）進行排序，因此你不必再對 imports 進行手動排序。它可以按字母順序對匯入進行排序，並自動將其拆分成多個部分。 使用 pipenv 安裝它，以便它們不會使部署混亂（可以指定只在開發環境安裝）： ```shell pipenv install black isort --dev ``` Black 和 isort 並不相容的預設選項，因此我們將讓 isort 遵循 black 的原則。建立一個 `setup.cfg` 檔案並新增以下配置： ``` [isort] multi_line_output=3 include_trailing_comma=True force_grid_wrap=0 use_parentheses=True line_length=88 ``` 我們可以使用以下命令執行這些工具： ```shell pipenv run black pipenv run isort ``` ## 使用 flake8 保證程式碼風格 Flake8 確保程式碼遵循 PEP8 中定義的標準 Python 程式碼規範。使用 pipenv 安裝： ```shell 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 ``` 現在我們可以執行 flake8 了，命令：`pipenv run flake8` 。 ## 使用 mypy 進行靜態型別檢查 > [Mypy](http://mypy-lang.org/) 是 Python 的非強制的靜態型別檢查器，旨在結合動態（或 “鴨子”）型別和靜態型別的優點。Mypy 將 Python 的表達能力和便利性與功能強大的型別系統的編譯時型別檢查結合在一起，使用任何 Python VM 執行它們，基本上沒有執行時開銷。 在 Python 中使用型別需要一點時間來適應，但是好處卻是巨大的。如下： - 靜態型別可以使程式更易於理解和維護 - 靜態型別可以幫助您更早地發現錯誤，並減少測試和除錯的時間 - 靜態型別可以幫助您在程式碼投入生產之前發現難以發現的錯誤 ```shell pipenv install mypy --dev ``` 預設情況下，Mypy 將遞迴檢查所有匯入包的型別註釋，當庫不包含這些註釋時，就會報錯。我們需要將 mypy 配置為僅在我們的程式碼上執行，並忽略沒有型別註釋的匯入錯誤。我們假設我們的程式碼位於以下配置的 `best_practices` 包中。將此新增到 `setup.cfg` ： ```toml [mypy] files=best_practices,test ignore_missing_imports=true ``` 現在我們可以執行 mypy 了： ```shell pipenv run mypy ``` 這是一個有用的 [備忘單](https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html) 。 ## 用 pytest 和 pytest-cov 進行測試 使用 [pytest](https://docs.pytest.org/en/latest/) 編寫測試非常容易，消除編寫測試的阻力意味著可以快速的編寫更多的測試！ ```shell pipenv install pytest pytest-cov --dev ``` 這是 pytest 網站上的一個簡單示例： ```python # content of test_sample.py def inc(x): return x + 1 def test_answer(): assert inc(3) == 5 ``` 要執行它： ```shell $ 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 ``` 如果還想檢視測試覆蓋率。建立一個新檔案 `.coveragerc`，指定只返回我們的專案程式碼的覆蓋率統計資訊。比如示例的 `best_practices` 專案，設定如下： ``` [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__.: ``` 現在，我們就可以執行測試並檢視覆蓋率了。 ```shell pipenv run pytest --cov --cov-fail-under=100 ``` `--cov-fail-under=100` 是設定專案的測試覆蓋率如果小於 100％ 那將認定為失敗。 ## pre-commit 的 Git hooks Git hooks 可讓您在想要提交或推送時隨時執行指令碼。這使我們能夠在每次提交/推送時，自動執行所有檢測和測試。[pre-commit](https://pre-commit.com/) 可輕鬆配置這些 hooks。 > Git hook 指令碼對於在提交程式碼審查之前，識別簡單問題很有用。我們在每次提交時都將執行 hooks，以自動指出程式碼中的問題，例如缺少分號、尾隨空白和除錯語句。通過在 code review 之前指出這些問題，程式碼審查者可以專注於變更的程式碼內容，而不會浪費時間處理這些瑣碎的樣式問題。 在這裡，我們將上述所有工具配置為在提交 Python 程式碼改動時執行（git commit），然後僅在推送時執行 pytest coverage（因為測試要在最後一步）。建立一個新檔案 `.pre-commit-config.yaml`，配置如下： ```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 生成專案 現在，我們已經知道了理想專案中包含了什麼，我們可以將其轉換為 [模板](https://github.com/sourcery-ai/python-best-practices-cookiecutter) 從而可以使用單個命令生成一個包含這些庫和配置的新專案： ```shell pipx run cookiecutter gh:sourcery-ai/python-best-practices-cookiecutter ``` 填寫專案名稱和倉庫名稱，將為您生成新的專案。 要完成設定，請執行下列步驟： ```shell # Enter project direc