Day03 - 開發輔助工具設定 - iT 邦幫忙::一起幫忙解決難題，拯救 IT 人的一天

2023 iThome 鐵人賽

DAY 3

Software Development

Django REST 大冒險：探索精彩紛呈的 API 開發世界系列第 3 篇

Day03 - 開發輔助工具設定

15th鐵人賽 django django-rest-framework python web

拉布

團隊狗狗與睡袋的產地

2023-09-18 21:29:44

440 瀏覽

分享至

前言

昨天我們已經將 Django 的專案建立好了，今天我們要來把其他的設定設定好。

設定 linter 與 formatter

在寫程式的時候有良好的習慣以及排版是很重要的。當多人一起開發的時候 linter 可以在程式不符合 Python 的慣例或是規定時候會提醒開發者，同時也可以規定程式的風格並提早發現隱性的 bug 避免開發者犯下無心的錯誤，而 Formatter 可以自動地將程式排版好，整齊的程式別人在幫你 debug 的時候才會比較輕鬆。

這系列的文章我們會使用下方的工具：

Ruff: 這是一個 Rust 寫的 Python linter，他整合了原本的 flake8 與 isort 等等原本 Python 開發者習慣使用的工具，但他的速度更快所以我們這次會使用他。
Black: 這是一個自動排版的工具，他可以設定的部分很少。他希望使用 black 排版出來的程式碼都盡可能的相近，不會因為設定而排出來的不一樣。
Pyright: 這是一個 Microsoft 出的 Python type checker 他可以對 Python 的程式碼做型態檢查，盡可能地讓型態的錯誤在執行前就發現。

以上就是我們會使用的輔助工具，現在我們要將他們安裝起來。這邊我會使用 poetry 提供的 group dependencies 功能，他可以將依賴的套件分組，這樣我們可以區分套件的用途，在部屬的時候也可以只安裝必要的依賴，避免資源的浪費。

poetry add --group lint ruff black pyright

安裝完成後你會看到 pyproject.toml 裡面多了下面這個部分（版本號可能會有些許的不同，不過沒有關係的）

[tool.poetry.group.lint.dependencies]
ruff = "^0.0.290"
black = "^23.9.1"
pyright = "^1.1.327"

看到這個就代表你安裝好了，接著我們要設定 Ruff，我們需要在 pyproject.toml 裡面添加以下的內容（貼在最下面即可）

[tool.ruff]
target-version = "py311"
select = [
  # pyflakes
  "F",
  # pycodestyle
  "E",
  "W",
  # pep8-naming
  "N",
  # pylint
  "PL",
  # mccabe
  "C90",
  # isort
  "I",
  # pydocstyle
  "D",
  # pyupgrade
  "UP",
  # flake8-builtins
  "A",
  # flake8-commas
  "COM",
  # flake8-bugbear
  "B",
  # flake8-comprehensions
  "C4",
  # flake8-type-checking
  "TCH",
  # flake8-datetimez
  "DTZ",
  # flake8-print
  "T20",
  # flake8-tidy-imports
  "TID",
  # flake8-simplify
  "SIM",
  # flake8-quotes
  "Q",
  # flake8-use-pathlib
  "PTH",
  # flake8-import-conventions
  "ICN",
  # flake8-django
  "DJ",
]
ignore = [
  # pydocstyle: Do not require any docstring
  "D100",
  "D101",
  "D102",
  "D103",
  "D104",
  "D105",
  "D106",
  "D107",
  "D212",
  "D203",
  # pydocstyle: Allow blank line after docstring
  "D202",
]

[tool.ruff.flake8-tidy-imports]
ban-relative-imports = "all"

[tool.ruff.pydocstyle]
convention = "google"

上面的設定是告訴 Ruff 說我們需要使用哪些規則，詳細的規則設定可以參考官方的文件，接著我們要來設定 Pyright 了，一樣我們將下方的設定貼到 pyproject.toml 的最下方即可

[tool.pyright]
pythonVersion = "3.11"
typeCheckingMode = "basic"
reportUnnecessaryTypeIgnoreComment = true

上方的設定是告訴 Pyright 我們使用的 Python 版本是多少，以及要用什麼模式來進行 type check 這邊我們使用的 basic 基本模式，如果想要更嚴謹些可以使用 strict 嚴格模式，不過剛開始而已我們先用基本模式就好了。如果想要看更多 pyright 的設定可以參考官方文件。

到目前為止我們已經把輔助工具都設定好了，現在我們來看看怎麼觸發他吧！

先看看 Ruff 我們在終端機出入下方指令（要記得用 poetry shell 啟動虛擬環境唷）

ruff check .

執行完你應該會看到很多的錯誤，不過不要緊張 ruff 帶有自動修復功能

ruff check --fix .

太好了執行完成後就只剩下一個錯誤訊息了（如下）

server/settings.py:89:89: E501 Line too long (91 > 88 characters)
Found 55 errors (54 fixed, 1 remaining).

會發生這個問題的原因是因為檔案的那行超過規定的長度 88 個字元了，讓我們看看檔案的內容吧！

# ...... 以上省略 ......

AUTH_PASSWORD_VALIDATORS = [
    {
        "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator",
    },
    {
        "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
    },
    {
        "NAME": "django.contrib.auth.password_validation.CommonPasswordValidator",
    },
    {
        "NAME": "django.contrib.auth.password_validation.NumericPasswordValidator",
    },
]

# ...... 以下省略 ......

可以看到超出長度限制的是有 django.contrib.auth.password_validation.UserAttributeSimilarityValidator 的那行（第 89 行），但剛好那行全部都是字串，我們無法透過調整讓他小於 88 個字元，我們只能告訴 ruff 說單次的允許這行違反規則

# ...... 以上省略 ......

AUTH_PASSWORD_VALIDATORS = [
    {
        "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator",  # noqa: E501
    },
    {
        "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
    },
    {
        "NAME": "django.contrib.auth.password_validation.CommonPasswordValidator",
    },
    {
        "NAME": "django.contrib.auth.password_validation.NumericPasswordValidator",
    },
]

# ...... 以下省略 ......

我們在那行後面加上 # noqa: E501 是告訴 ruff 說這行可以違反規則 E501 請他忽略不要跳出錯誤，接著我們再次執行指令

ruff check .

P.S. 如果使用 VSCode 可以安裝 Ruff 套件來讓 ruff 的錯誤顯示在編輯器中。

就可以看到沒有任何錯誤了，接著我們來看看怎麼觸發 black

black .

這樣就可以自動排版了。

P.S. 如果你使用 VSCode 可以安裝 Black Formatter 套件讓編輯器支援自動排版。

最後我們來看看怎麼觸發 pyright 吧！

pyright .

這樣就可以進行 type check 了。

P.S. 如果你使用 VSCode 你只需要安裝 Pylance （通常安裝 Python 套件時就會自動安裝了）就可以在違反規則的時候收到警告了。

總結

今天我們安裝了幾個輔助工具 ruff, black 以及 pyright 來協助我們檢查我們的程式的品質，剛開始使用這些工具的時候可能會有些綁手綁腳，但養成好的開發習慣是很重要的，這可以讓你後面開發的速度越來越快，後續在修改程式的時候也會比較輕鬆些。在跟其他人協作的時候也會因為風格相同而更容易讀懂其他人的程式碼。

我們的環境建立終於完成啦！明天我們就會開始寫程式了（撒花～～～），一起進入 DRF 的奇妙世界吧！

P.S. 今天的檔案更新可以參考我的 Git Commit 大家可以搭配服用