文 | Brendan Maginnis  譯 | EarlGrey 

推薦 | 程式設計派公眾號（ID：codingpy） 

原文：https://sourcery.ai/blog/python-best-practices/

在開始一個新的Python專案時，很容易不做規劃直接進入編碼環節。花費少量時間，用最好的工具設定專案，將節省大量時間並帶來更快樂的編碼體驗。

在理想的世界中，所有開發人員使用的依賴庫都是相同的，程式碼將被完美地格式化，禁止常見錯誤，並且測試將涵蓋所有內容。此外，每次提交程式碼時都會確保符合這些要求。

在本文中，我將介紹如何設定一個這樣的理想專案。你可以跟隨我的步驟操作，也可以直接開始安裝pipx和pipenv，然後生成新專案。

讓我們建立一個新的專案目錄：

mkdir best_practices	
cd best_practices

Python命令列工具與pipx

Pipx是一個方便的實用程式，允許快速安裝python命令列工具。我們將用它來安裝 pipenv 和 cookiecutter 。

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

使用 pipenv 進行依賴管理

Pipenv自動為您的專案建立和管理virtualenv，以及在安裝/解除安裝軟體包時從Pipfile新增/刪除軟體包。它還生成了非常重要的Pipfile.lock檔案，用於生成確定性構建。

知道你和你的同事正在使用相同的庫版本，可以極大提升信心。Pipenv 可以實現這個點，因此在過去一年多裡得到了大量開發者的青睞

pipx install pipenv

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

Black是程式碼格式化工具：

Black是不妥協的Python程式碼格式化程式。通過使用它，意味著您同意放棄對手動格式化細節的控制。作為回報，Black 為你提供速度和確定性，並且無需處理 pycodestyle 的繁瑣提示。你將有更多的時間，來處理更重要的事情。

無論是什麼專案，Black 格式化後的程式碼看起來都是一樣的。習慣之後，你不會再注意到格式的問題，可以專注於內容。

Black產生的程式碼差異最小，可以加速程式碼審查。

isort則用來處理 import 的排序：

isort是可以按字母順序對 import 進行排序，並自動分成多個部分。

讓我們使用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的約定。使用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

現在我們可以使用 pipenv run flake8執行flake8。

使用 mypy 檢查靜態型別

Mypy是Python的一個可選靜態型別檢查器，旨在結合動態（或“鴨子”）型別和靜態型別的好處。Mypy將Python的表現力和便利性與強大的型別系統和編譯時型別檢查相結合。Mypy對標準Python程式進行型別檢查，使用 Python VM 執行 mypy 基本沒有執行時的開銷。

在Python中使用型別需要慢慢習慣，但好處是巨大的。mypy 官網這樣寫道：

• 靜態型別可以使程式更容易理解和維護

• 靜態型別可以幫助您更早地發現錯誤，並減少測試和除錯

• 靜態型別可以幫助您在程式碼投入生產之前找到難以發現的錯誤

    pipenv install mypy --dev

預設情況下，Mypy將遞迴檢查所有型別註釋的匯入，這會導致庫不包含這些註釋時出錯。我們需要將mypy配置為僅在我們的程式碼上執行，並忽略沒有型別註釋的匯入的任何錯誤。我們假設程式碼存在於以下配置的 best_practices包中。將如下配置新增到 setup.cfg：

[mypy]	
files=best_practices,test	
ignore_missing_imports=true

現在我們可以執行mypy：

pipenv run mypy

mypy 的速查表：https://mypy.readthedocs.io/en/latest/cheatsheetpy3.html

使用pytest和pytest-cov進行測試

使用pytest編寫測試非常容易，並且消除編寫測試的阻力，意味著我們會編寫更多的測試！

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

如果對應用程式程式碼的測試覆蓋率低於100％，則會失敗。

pre-commit 的 Git 鉤子

Git鉤子允許您在任何時候提交或推送時執行指令碼。這就可以支援我們在每次提交/推送時，自動執行所有的格式化和測試。pre-commit可以幫助我們輕鬆配置這些鉤子：

在提交程式碼審查之前，Git鉤子指令碼可以幫助識別簡單問題。每次提交時執行鉤子，自動指出程式碼中的問題，例如缺少分號，尾隨空格和除錯語句。在程式碼審查之前指出這些問題，可以讓程式碼審查者專注於程式碼架構的變化，而不是浪費時間檢查格式問題。

在這裡，我們配置在提交Python 檔案修改時，執行上述所有檢查，並且僅在推送時執行pytest覆蓋率測試，因為耗時可能較長。建立一個新檔案 .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

如果你需要跳過這些鉤子，你可以執行 git commit--no-verify或 git push--no-verify

使用cookiecutter生成專案

我們已經看到了理想專案都使用了哪些工具，可以將其固化為一個模板，只需要1個命令 即可生成新專案：

pipx run cookiecutter gh:sourceryai/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，這時所有的鉤子都會執行。

往期閱讀