Python Table Manner - 程式碼風格

這裡已經不再維護了，可以到我的個人部落格 看更新的文章

接下來要介紹的是 linter
它用來檢查程式是否符合特定的程式碼風格的一類工具
以 Python 來說，則是應該遵守 PEP 8
linter 除了能檢查是否不符風格，通常也能用來檢查語法錯誤

風格檢查 - flake8

flake8 是 Python 最常被使用的 linter 之一
幾乎是所有 Python 開源專案的標準配備

使用

以下面這段程式碼為例

# bad_code.py
import os
os =  "My Operating system"

這段程式碼出現了兩個問題

• 把模組 os 指派成一個字串，會導致無法使用 os 模組內的函式（因為 os 已經變成一個字串）
• os 的 = 後面加上兩個空白是不必要的，不符合 PEP 8 的規範

# 安裝 flake8
pipenv install flake8 --dev

# 執行 flake8
pipenv run flake8

flake8 預設對當前目錄下所有 Python 的檔案做檢查

執行後，flake8 會將這些錯誤點出來

./bad_code.py:4:1: F811 redefinition of unused 'os' from line 1
./bad_code.py:4:5: E222 multiple spaces after operator

透過這個錯誤碼（e.g., F811）可以在 flake8 rules 找到為什麼這是個錯誤和怎麼修正比較好

設定

某些狀況下，我們會不完全依照 flake8 的風格
例如 PEP 8 的每行只能有 79 個字元，已經越來越不被使用

除了可以直接在 flake8 指令後面加上參數
也可以直接寫入設定檔 setup.cfg (或 .flake8, tox.ini）
以下是我所使用的設定

[flake8]
ignore =
    # F632: use ==/!= to compare str, bytes, and int literals
    F632,
    # W503: Line break occurred before a binary operator
    W503,
    # E501: Line too long
    E501,
    # E203: Whitespace before ':' (for black)
    E203
exclude =
    .git,
    __pycache__,
    build,
    dist

max-line-length = 88

• ignore: 指定要忽略的錯誤類型（可以從 flake8 rules 找到這些錯誤碼）
• exclude: 不用被檢查的檔案
• max-line-length: 每行最長長度（這裡設定的 88，是後面會介紹到的 black 的預設值）

Read More 👉 Configuring Flake8

局部跳過檢查

另一種狀況是，我們只想在讓一兩行程式碼跳過 flake8 的檢查
但這份檔案的其他地方還是希望能被檢查
這時候可以在那行程式碼加上 # noqa: [error]

e.g.,

example = lambda: 'example'  # noqa: E731

風格檢查 - pylint

pylint 同樣是相當常見的 Python linter
一般來說，比 flake8 檢查的更加嚴格

使用

與 flake8 不同， pylint 指令需要指定模組或套件名稱才能進行檢查

# 安裝 pylint
pipenv install pylint --dev

# 執行 pylint
pipenv run pylint <package> ......

設定

因為 pylint 的設定非常多，可以使用它提供的指令來產生預設的設定檔
一般會建議透過內建的指令生成 .pylintrc

# 將預設的 pylint 設定檔寫入 `.pylintrc`
pipenv run pylint --generate-rcfile >> .pylintrc

我常用到的欄位有 disable 跟 max-line-length

disable 的錯誤可以在 pylint-messages 找到

..
disable=print-statement,
...
max-line-length=88

局部跳過檢查

pylint 同樣可以忽略部分的程式碼
只要在要忽略的程式碼前面一行加上 # pylint: disable=[error]
但需要注意的是，這行以後全部的檢查都會被關閉
所以要記得在需要開啟檢查的地方再加上 # pylint: enable=[error]

# pylint: disable=line-too-long
print("Imagine this is a really long line!")
# pylint: enable=line-too-long

flake8 v.s. pylint

除了相關的檢查外， pylint 會比 flake8 做更嚴格的檢查
也可以做更多的設定，但在執行上也會比較慢

在 PyCon US 2018 的 Automating Code Quality，Kyle Knapp 很詳細的比較了這兩個工具

我的使用上會把 flake8 作為強制檢查程式碼風格的一環
只要沒有通過 flake8 的檢查，就應該做修正
而 pylint 的警告則是只作為參考

flake8 在大多數狀況已經足夠
花時間去修改成符合某些 pylint 過於嚴格的檢查，或設定 .pylint，對我來說並不值得
而且 Guido 也是這麼說的 XD

型別檢查 - mypy

mypy 是為 Python 做靜態型別檢查的工具
Python 是一個動態型別的語言，所以可以隨意地不同型別的值指派給同一個變數
e.g.,

str_var = "This is a string"

str_var = 1

但這樣常常會造成邏輯上的錯誤
例如 import csv 時，如果使用了 csv 作為其他的變數名稱
就會將變數的值取代掉原本引入的模組

除此之外，型別標記的程式碼也會增加可讀性
因此近幾年越來越多人注意 Python 的型別標記

在 PyCon US 2017 中 Lisa Guo 和 Hui Ding 的 Keynote Session Python@Instagram 非常的精彩
相當建議可以觀看

使用

以下列的程式碼為例

# wrong_type_hint.py
from typing import List


def func(val: List[str]):
    print(val)


func([1, 2, 3])

func 的參數 val 標記為 List[str]
但在呼叫的時候卻傳入整數陣列

# 安裝 mypy
pipenv install --dev

# 執行 mypy
pipenv run mypy [files] --ignore-missing-imports

執行 mypy 後，它就會告訴跳出型別錯誤的警告

wrong_type_hint.py:8: error: List item 0 has incompatible type "int"; expected "str"

wrong_type_hint.py:8: error: List item 1 has incompatible type "int"; expected "str"

wrong_type_hint.py:8: error: List item 2 has incompatible type "int"; expected "str"

mypy 預設會去找所有引入的函式庫是否也有做好型別標記
所以一般使用上都會加上參數 --ignore-missing-imports
只要確保我們撰寫的部分都是正確的

設定

以下是我用來設定 mypy 的 setup.cfg

[mypy]
files=[your files]
ignore_missing_imports=true

自動排版 - black

比起 flake8, pylint 只做風格檢查
black 會更進一步的直接修正不符合風格的程式碼
原本我不太喜歡使用這種的工具
原因是每次執行的結果不一定相同，修正的結果不見得符合我的需求，這時就要再去做設定

black 某種程度上的解決了這些問題
black 每次執行的結果都會是相同的，而且大致上修正結果我還算滿意
它最特別的地方是，不太能做客製化設定，也不能只做局部程式碼修正

引述自 black 的文件

The Black code style

Black reformats entire files in place. It is not configurable. It doesn't take previous formatting into account. It doesn't reformat blocks that start with # fmt: off and end with # fmt: on. # fmt: on/off have to be on the same level of indentation. It also recognizes YAPF's block comments to the same effect, as a courtesy for straddling code.

為什麼這可能是件好事？
因為這能讓大家更專注於程式碼的功能本身
而不是這裡要不要加逗號？要不要斷行？如何去調教設定檔？

“There should be one-- and preferably only one --obvious way to do it.”
–The Zen of Python, by Tim Peters

使用

因為 black 還是 beta 版
透過 pipenv 安裝時還要加上 --pre 參數

# 安裝 black
pipenv install black --dev --pre

# 執行 black 修正程式碼風格
pipenv run black <package>

因為 black 是直接重新排版程式碼
我節錄了部分我在 pycontw-postevent-report-generator commit e64a 修正風格的結果
上面紅色的部分是原本的程式碼，下面綠色是修正過的結果
(p.s. 當時設定的長度是 119)

如果只想要檢查程式碼是否符合 black 的風格
而不要直接做修正，可以在指令後面加入 --check 參數

pipenv run black <package> --check

設定

雖然說 black 不能對風格做太多的設定
我們還是能先指定哪些檔案是要修正，哪些是不用的
以下是我放在 pyproject.toml 的設定
（p.s. line-length = 88 是 black 的預設值）

[tool.black]
line-length = 88
include = '\.pyi?$'
exclude = '''
/(
    \.eggs
  | \.git
  | \.hg
  | \.mypy_cache
  | \.tox
  | \.venv
  | _build
  | buck-out
  | build
  | dist
)/
'''

排序函式庫 - isort

isort 是自動排列函式庫引入順序的的工具
PEP 8 建議將引入的函式庫分為三類做排序

1. 標準函式庫
2. 第三方函式庫
3. 本地的函式庫

並在每一個種類間空一行
e.g.,

import os

import flask

import models

使用 isort 的原因跟 black 差不多
就是讓程式來決定比較枝微末節的事，專注在開發本身上面

執行

# 安裝 isort
pipenv install isort --dev

# 執行 isort
pipenv run isort --atomic --apply

• --atomic: 只有重新排序後的結果沒有語法錯誤，才會儲存
• --apply: 重新排序函式庫，不每個檔案逐一向使用者做確認

設定

為了跟前面提到的工具相容（主要應該是 black），以下是我在 pyproject.toml 內的設定

[tool.isort]
multi_line_output=3
include_trailing_comma=true
force_grid_wrap=0
use_parentheses=true
line_length=88

其他工具

• check-manifest: 檢查有沒有少放入 MAINIFEST.in 的檔案
• seed-isort-config

Bouns: 設定檔的選用

從前面的測試到現在有提到多種設定檔的格式
通常每個工具都會有自己的設定檔 (e.g., .coveragerc, .flake8) 或者用 Python 比較通用的格式 (e.g., pyproject.toml, setup.cfg)
其中 pyproject.toml 是在 PEP 518 提出的設定檔格式
不過還沒有被所有的工具支援
awesome-pyproject 整理了目前已經支援或討論是否要支援 proproject.toml 的工具

比起讓多個工具的設定散落在各個設定檔
我傾向統一管理在 pyproject.toml 或 setup.cfg
其中有兩個例外

• .pylintrc: 設定內容太長，如果併入通用的設定檔，容易造成其他設定閱讀困難
• pytest.ini: pytest 即將放棄對 setup.cfg 的支援，而且容易出錯 （Read More 👉 deprecate setup.cfg support #3523）

Reference

• Automating Code Quality - PyCon US 2018
• Life Is Better Painted Black, or: How to Stop Worrying and Embrace Auto-Formatting - PyCon US 2019
• Beyond PEP 8 -- Best practices for beautiful intelligible code - PyCon 2015