⭐ Python Developer · Chặng 6Bài 3/6Bài học~45 phút

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.

Ruff: format và lint code Python tự động, cấu hình 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
  1. 1. PEP 8 và vì sao cần công cụ
  2. 2. Cài và chạy
  3. 3. ruff check: tìm lỗi
  4. 4. ruff format: định dạng tự động
  5. 5. Cấu hình trong pyproject.toml
  6. 6. Tích hợp VS Code và pre-commit
  7. Tóm tắt
  8. Bài tập

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.

Formatter không thay được việc đặt tênRuff biến 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 check tìm lỗi, --fix tự sửa phần an toàn; ruff rule MÃ để hiểu luật.
  • ruff format định dạng theo phong cách Black; --check cho CI.
  • Cấu hình [tool.ruff] trong pyproject.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

  1. 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.
  2. 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.

Bài tiếp theo
Ban biên tập HocFree

Chúng tôi viết những bài hướng dẫn dễ hiểu, thực tế để ai cũng có thể tự học lập trình và AI, hoàn toàn miễn phí.