Black là trình định dạng mã Python tự động, tuân thủ nghiêm ngặt các quy ước về phong cách và không yêu cầu cấu hình phức tạp. Khả năng xử lý dữ liệu qua luồng chuẩn (stdin/stdout) khiến nó trở thành công cụ linh hoạt trong nhiều bối cảnh phát triển — từ tích hợp trình soạn thảo đến pipeline CI/CD.

Nguyên lý định dạng theo luồng

Khi được gọi với đối số -, Black đọc mã nguồn từ đầu vào chuẩn thay vì từ tệp. Kết quả được in trực tiếp ra đầu ra chuẩn, giúp loại bỏ nhu cầu tạo tệp tạm hoặc ghi đè lên mã gốc. Đây là cơ sở cho các workflow dựa trên pipe và automation.

Cách sử dụng cơ bản

Định dạng một đoạn mã đơn giản:

echo "def greet(name): return f'Hello {name}!'" | black -

Đầu ra sẽ là:

def greet(name):
    return f"Hello {name}!"
reformatted -
All done! ✨ 🍰 ✨
1 file reformatted.

Xử lý trường hợp đặc biệt

Một số ngữ cảnh yêu cầu chỉ định rõ loại tệp hoặc phiên bản Python để đảm bảo phân tích cú pháp chính xác:

• Tập tin stub (.pyi): cat api_stub.pyi | black --pyi -
• Ô mã Jupyter: printf "x = 42\nprint(x)" | black --ipynb -
• Đích Python 3.9: echo "dataclass(frozen=True)" | black --target-version=py39 -

Tích hợp nâng cao

Black có thể kết hợp mượt mà với các công cụ khác thông qua shell pipeline:

• Kiểm tra và định dạng đồng thời:

python -m py_compile -q - | black - 2>/dev/null || echo "Syntax OK"

• Trong Neovim/Vim (định dạng vùng chọn):

:'<,'>!black - --quiet

• Xử lý nhiều tệp bằng tên ảo (tránh lỗi khi không có đường dẫn thực):

find src/ -name "*.py" -exec cat {} + | black - --stdin-filename=__main__.py

Cấu hình linh hoạt

Black tự động tải cấu hình từ pyproject.toml nếu tồn tại trong thư mục hiện hành. Ví dụ cấu hình tối thiểu:

[tool.black]
line-length = 90
skip-string-normalization = true
include = '\.pyi?$'

Để áp dụng cấu hình từ vị trí tùy chọn:

echo "x=1" | black - --config ./configs/black.toml

Mẹo vận hành hiệu quả

• Dùng --quiet để chỉ in mã đã định dạng, bỏ qua thông báo trạng thái.
• Dùng --check để kiểm tra tính nhất quán mà không sửa đổi: echo "a = 1" | black - --check && echo "OK" || echo "Needs formatting".
• Dùng --no-cache khi cần bỏ qua bộ nhớ đệm (ví dụ trong môi trường CI).
• Lỗi cú pháp sẽ được gửi tới stderr và trả về mã thoát khác 0 — điều này hỗ trợ dễ dàng tích hợp vào script kiểm tra.