Ruff: format và lint code Python tự động, cấu hình pre-commit
Giữ code đúng PEP 8 không cần nhớ luật: ruff format, ruff check --fix, chọn bộ luật trong pyproject.toml, tích hợp VS Code, pre-commit.
Học xong bài này, bạn sẽ
- Hiểu PEP 8 và lý do cần công cụ tự động
- Dùng ruff format và ruff check --fix
- Cấu hình Ruff trong pyproject.toml và pre-commit
Nên học trước: Git và GitHub cho lập trình viên Python
Nội dung bài viết
Trong một nhóm, nếu mỗi người viết một kiểu (người dùng 2 dấu cách, người 4; người để dòng dài 200 ký tự), thời gian review code bị tiêu vào tranh cãi định dạng thay vì logic. Còn những lỗi như import thừa, so sánh == None, except: trơn thì mắt người rất dễ bỏ sót. Ruff giải quyết cả hai: tự định dạng code (formatter) và tự tìm lỗi, thói quen xấu (linter), nhanh đến mức chạy trên cả dự án lớn trong chớp mắt.
1. PEP 8 và vì sao cần công cụ
PEP 8 là quy chuẩn trình bày code Python: thụt lề 4 dấu cách, tên hàm chu_thuong, tên lớp CapWords, khoảng trắng quanh toán tử, hai dòng trống giữa các hàm cấp module... Bạn không cần thuộc lòng: hãy để công cụ áp dụng tự động, và dành sức để đặt tên tốt, chia hàm hợp lý, những thứ công cụ không làm thay được.
2. Cài và chạy
$ uv add --dev ruff # trong dự án uv
$ uv tool install ruff # hoặc cài dùng chung cho mọi dự án
$ ruff --version
ruff 0.17.3
Lấy một file viết ẩu làm ví dụ, bao_cao.py:
# (minh họa) bao_cao.py: code chưa qua Ruff
import os, sys
import json
from pathlib import Path
def tong_tien(ds,thue = 0.08):
tong=0
for i in range(len(ds)):
tong+=ds[i]
if thue == None:
thue = 0
return tong*(1+thue)
def doc(p):
try:
return json.loads(Path(p).read_text())
except:
return []
3. ruff check: tìm lỗi
Với cấu hình ở mục 5, ruff check báo (dạng rút gọn):
$ ruff check --output-format concise bao_cao.py
bao_cao.py:1:1: E401 [*] Multiple imports on one line
bao_cao.py:1:1: I001 [*] Import block is un-sorted or un-formatted
bao_cao.py:1:8: F401 [*] `os` imported but unused
bao_cao.py:1:12: F401 [*] `sys` imported but unused
bao_cao.py:9:16: E711 Comparison to `None` should be `cond is None`
bao_cao.py:16:5: E722 Do not use bare `except`
Found 6 errors.
[*] 4 fixable with `--fix` (1 unsafe fix available with `--fix --unsafe-fixes`).
Mỗi dòng gồm vị trí, mã luật và mô tả. Mã luật cho biết nhóm: F (Pyflakes: lỗi thật như biến chưa định nghĩa, import thừa), E/W (pycodestyle: PEP 8), I (sắp xếp import), B (bugbear: bẫy hay gặp), UP (nâng cú pháp lên phiên bản mới), SIM (đơn giản hóa). Không hiểu luật nào, chạy ruff rule E722 để đọc giải thích và ví dụ.
$ ruff check --fix bao_cao.py
Found 6 errors (4 fixed, 2 remaining).
--fix tự sửa các lỗi có dấu [*] (an toàn, không đổi hành vi): tách và sắp xếp import, xóa import thừa. Hai lỗi còn lại cần bạn quyết định: == None được đánh dấu "unsafe" vì về lý thuyết một lớp có thể định nghĩa __eq__ lạ, và except: trơn thì chỉ bạn biết nên bắt loại lỗi nào.
4. ruff format: định dạng tự động
$ ruff format bao_cao.py
1 file reformatted
Sau check --fix, format và sửa tay hai lỗi còn lại (đồng thời viết lại cho Pythonic hơn):
import json
from pathlib import Path
def tong_tien(ds: list[float], thue: float | None = 0.08) -> float:
if thue is None:
thue = 0
return sum(ds) * (1 + thue)
def doc(p: str | Path) -> list:
try:
return json.loads(Path(p).read_text(encoding="utf-8"))
except (FileNotFoundError, json.JSONDecodeError):
return []
print(tong_tien([100, 200]), doc("khong_co.json"))
324.0 []
ruff format tương thích với Black, công cụ định dạng phổ biến trước đó: hầu như mọi dự án Python mở trên GitHub hiện nay đều được định dạng theo phong cách này. ruff format --check chỉ kiểm tra không sửa, dùng trong CI (chặng 10).
5. Cấu hình trong pyproject.toml
[tool.ruff]
line-length = 100 # mặc định 88
target-version = "py312" # cho phép đề xuất cú pháp từ 3.12
[tool.ruff.lint]
select = ["E", "F", "W", "I", "B", "UP", "SIM"]
ignore = ["E501"] # ví dụ: bỏ luật độ dài dòng, để formatter lo
[tool.ruff.lint.per-file-ignores]
"tests/*" = ["S101"] # cho phép assert trong test nếu bật nhóm S (bảo mật)
Mặc định Ruff chỉ bật E và F cơ bản. Bộ select ở trên là điểm khởi đầu tốt cho dự án mới; bật thêm dần (ví dụ "PL" của Pylint, "S" cho bảo mật) khi nhóm đã quen. Với code cũ có hàng trăm lỗi, đừng sửa một lần: bật từng nhóm luật một.
6. Tích hợp VS Code và pre-commit
Cài extension Ruff (của Astral) trong VS Code, rồi thêm vào settings.json để mỗi lần lưu file là tự format và sắp xếp import:
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll": "explicit",
"source.organizeImports": "explicit"
}
}
pre-commit chạy kiểm tra ngay trước mỗi lần git commit: code chưa đạt thì không commit được. Tạo file .pre-commit-config.yaml ở gốc dự án:
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.17.3 # nên trùng phiên bản ruff của dự án
hooks:
- id: ruff-check
args: [--fix]
- id: ruff-format
$ uv add --dev pre-commit
$ uv run pre-commit install # gắn hook vào kho git, làm một lần
$ uv run pre-commit run --all-files # chạy thử trên mọi file
Từ giờ, mỗi lần commit, Ruff tự sửa những gì sửa được; nếu có thay đổi hoặc còn lỗi, commit bị dừng để bạn xem lại, git add và commit lại.
def tt(d,t=0.08) thành def tt(d, t=0.08), nhưng không biến nó thành def tong_tien(gia_list, thue=0.08). Code dễ đọc vẫn là trách nhiệm của bạn; xem thêm bài đọc thêm về viết code Python sạch.Tóm tắt
ruff checktìm lỗi,--fixtự sửa phần an toàn;ruff rule MÃđể hiểu luật.ruff formatđịnh dạng theo phong cách Black;--checkcho CI.- Cấu hình
[tool.ruff]trongpyproject.toml; bật dần nhóm luật. - VS Code format khi lưu; pre-commit chặn commit code chưa đạt.
Bài tập
Bài 1. Dọn một dự án cũ
Chạy ruff check với bộ luật ở mục 5 trên dự án chi tiêu hoặc thư viện của bạn, sửa hết lỗi, ghi lại ba lỗi bạn thấy đáng chú ý nhất và lý do.
Xem gợi ý
Ba lỗi người mới hay gặp nhất và ý nghĩa: B006 (list, dict làm giá trị mặc định: bẫy dùng chung ở chặng 2), E722 hoặc BLE001 (bắt ngoại lệ quá rộng: nuốt lỗi, chặng 3), SIM108 (if/else bốn dòng có thể thành biểu thức điều kiện một dòng). Chạy ruff check --statistics để xem luật nào bị vi phạm nhiều nhất.
Bài 2. Cài pre-commit
Cài pre-commit với hook Ruff. Cố tình thêm import os không dùng vào một file rồi commit, quan sát điều gì xảy ra.
Xem đáp án
$ git commit -am "Thử pre-commit"
ruff check...............................................................Failed
- hook id: ruff-check
- files were modified by this hook
Found 1 error (1 fixed, 0 remaining).
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook
1 file reformatted
ruff-check tự xóa import os; xóa xong đầu file còn dòng trống thừa nên ruff-format sửa tiếp. Vì file bị thay đổi, commit bị dừng. Chạy git diff để xem Ruff đã sửa gì, rồi git add và commit lại: lần này mọi hook đều Passed.
Nguồn tham khảo: Ruff documentation; Ruff: Rules; ruff-pre-commit; PEP 8.
Bài tập thực hành
- Chạy ruff check trên một dự án cũ của bạn, sửa hết lỗi, giải thích 3 lỗi đáng chú ý nhất.
- Cài pre-commit với hook Ruff để mỗi lần commit tự format và lint.
Làm xong bài tập mới chuyển sang bài tiếp theo: tự viết code là cách duy nhất để nhớ lâu.


