如何建立一個完美的 Python 項目
當開始一個新的 Python 項目時，大家很容易一頭扎進去就開始編碼。其實花一點時間選擇優秀的庫，將為以后的開發節省大量時間，并帶來更快樂的編碼體驗。
在理想世界中，所有開發人員的關系是相互依賴和關聯的（協作開發），代碼要有完美的格式、沒有低級的錯誤、并且測試覆蓋了所有代碼。另外，所有這些將在每次提交時都可以得到保證。（代碼風格統一、類型檢測、測試覆蓋率高、自動檢測）
在本文中，我將介紹如何建立一個可以做到這些點的項目。您可以按照步驟操作，也可以直接跳到 使用 cookiecutter 生成項目 部分（老手）。
首先，讓我們創建一個新的項目目錄：
- 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] 為您的項目自動創建和管理 virtualenv（虛擬環境），并在安裝/卸載軟件包時從 Pipfile 添加/刪除軟件包。它還會生成非常重要的 Pipfile.lock 用于保證依賴的可靠性。
當你知道，你和你的隊友正在使用相同的庫版本時，這將會極大地提高編程的信心和樂趣。Pipenv 很好地解決了使用相同的庫，版本不同的這一問題，Pipenv 在過去的一段時間里獲得了廣泛的關注和認可，你可以放心使用。安裝命令如下：
- pipx install pipenv
使用 black 和 isort 進行代碼格式化
black [4] 可以格式化我們的代碼：
Black 是毫不妥協的 Python 代碼格式化庫。通過使用它，你將放棄手動調整代碼格式的細節。作為回報，Black 可以帶來速度、確定性和避免調整 Python 代碼風格的煩惱，從而有更多的精力和時間放在更重要的事情上。
無論你正在閱讀什么樣的項目，用 black 格式化過的代碼看起來都差不多。一段時間后格式不再是問題，這樣你就可以更專注于內容。
black 通過減少代碼的差異性，使代碼檢查更快。
而 isort [5] 是對我們的 imports 部分進行排序：
isort 為您導入的 Python 包部分（imports）進行排序，因此你不必再對 imports 進行手動排序。它可以按字母順序對導入進行排序，并自動將其拆分成多個部分。
使用 pipenv 安裝它，以便它們不會使部署混亂（可以指定只在開發環境安裝）：
- 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
我們可以使用以下命令運行這些工具：
- pipenv run black
- pipenv run isort
使用 flake8 保證代碼風格
Flake8 確保代碼遵循 PEP8 中定義的標準 Python 代碼規范。使用 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
現在我們可以運行 flake8 了，命令： pipenv run flake8 。
使用 mypy 進行靜態類型檢查
Mypy [6] 是 Python 的非強制的靜態類型檢查器，旨在結合動態（或 “鴨子”）類型和靜態類型的優點。Mypy 將 Python 的表達能力和便利性與功能強大的類型系統的編譯時類型檢查結合在一起，使用任何 Python VM 運行它們，基本上沒有運行時開銷。
在 Python 中使用類型需要一點時間來適應，但是好處卻是巨大的。如下：
-
靜態類型可以使程序更易于理解和維護
-
靜態類型可以幫助您更早地發現錯誤，并減少測試和調試的時間
-
靜態類型可以幫助您在代碼投入生產之前發現難以發現的錯誤
- pipenv install mypy --dev
默認情況下，Mypy 將遞歸檢查所有導入包的類型注釋，當庫不包含這些注釋時，就會報錯。我們需要將 mypy 配置為僅在我們的代碼上運行，并忽略沒有類型注釋的導入錯誤。我們假設我們的代碼位于以下配置的 best_practices 包中。將此添加到 setup.cfg ：
- [mypy]
- files=best_practices,test
- ignore_missing_imports=true
現在我們可以運行 mypy 了：
- pipenv run mypy
這是一個有用的 備忘單 [7] 。
用 pytest 和 pytest-cov 進行測試
使用 pytest [8] 編寫測試非常容易，消除編寫測試的阻力意味著可以快速的編寫更多的測試！
- pipenv install pytest pytest-cov --dev
這是 pytest 網站上的一個簡單示例：
- # content of test_sample.py
- def inc(x):
- return x + 1
- def test_answer():
- assert inc(3) == 5
要執行它：
- $ 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__.:
現在，我們就可以運行測試并查看覆蓋率了。
- pipenv run pytest --cov --cov-fail-under=100
--cov-fail-under=100 是設定項目的測試覆蓋率如果小于 100％ 那將認定為失敗。
pre-commit 的 Git hooks
Git hooks 可讓您在想要提交或推送時隨時運行腳本。這使我們能夠在每次提交/推送時，自動運行所有檢測和測試。 pre-commit [9] 可輕松配置這些 hooks。
Git hook 腳本對于在提交代碼審查之前，識別簡單問題很有用。我們在每次提交時都將運行 hooks，以自動指出代碼中的問題，例如缺少分號、尾隨空白和調試語句。通過在 code review 之前指出這些問題，代碼審查者可以專注于變更的代碼內容，而不會浪費時間處理這些瑣碎的樣式問題。
在這里，我們將上述所有工具配置為在提交 Python 代碼改動時執行（git commit），然后僅在推送時運行 pytest coverage（因為測試要在最后一步）。創建一個新文件 .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 生成項目
現在，我們已經知道了理想項目中包含了什么，我們可以將其轉換為 模板 [10] 從而可以使用單個命令生成一個包含這些庫和配置的新項目：
- pipx run cookiecutter gh:sourcery-ai/python-best-practices-cookiecutter
填寫項目名稱和倉庫名稱，將為您生成新的項目。
要完成設置，請執行下列步驟：
- # Enter project directory
- cd <repo_name>
- # 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 文件和測試，可以試用上面這些工具。在編寫完代碼覺得沒問題后，就可以執行第一次 git commit ，所有的 hooks 都將運行。
集成到編輯器
雖然在提交時知道項目的代碼始終保持最高水準是件令人興奮的事情。但如果在代碼已全部修改完成之后（提交時），再發現有問題還是會讓人很不爽。所以，實時暴露出問題要好得多。
在保存文件時，花一些時間確保代碼編輯器運行這些命令。有及時的反饋，這意味著你可以在代碼還有印象的時候能迅速解決引入的任何小問題。
我個人使用一些出色的 Vim 插件來完成此任務：
-
ale [11] 實時運行 flake8 并在保存文件時運行 black、isort 和 mypy
-
與 projectionist 集成的 [12] vim-test [13] 在文件保存上運行 pytest
