Гайды

Линтеры и форматтеры: Ruff, mypy, Black и pre-commit

pyproject.toml, хуки pre-commit, согласование с CI и версией Python в Docker.

~8 мин чтения

Разработка Python Линтинг Форматирование

Линтеры и форматтеры: Ruff, mypy, Black и pre-commit

Ruff — быстрый линтер/форматтер (замена части flake8 + isort и др.). mypy — статическая типизация. Black — мнениеформаттер (или форматтер Ruff). pre-commit — git hooks для локального прогона до push. Python-стек курса — Быстрый старт с FastAPI.

1. pyproject.toml (скелет)

toml

[tool.ruff]
line-length = 100
target-version = "py312"
select = ["E", "F", "I", "B", "UP"]

[tool.ruff.format]
quote-style = "double"

[tool.mypy]
python_version = "3.12"
strict = true
packages = ["app"]

2. pre-commit

.pre-commit-config.yaml:

yaml

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.6.9
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.11.2
    hooks:
      - id: mypy
        additional_dependencies: [types-requests]

bash

pre-commit install
pre-commit run --all-files

3. CI

Те же команды в GitHub Actions / GitLab CI — CI/CD: GitLab и GitHub Actions.

Типичный минимум в job:

bash

ruff check .
ruff format --check .
mypy

Для больших репозиториев в PR прогоняйте ruff check только по диффу (ruff check $(git diff --name-only main...HEAD | grep '\.py$')) — быстрее, но полный прогон на main оставьте ночным или перед релизом.

4. Black и Ruff format

Не запускайте Black и ruff format на одних и тех же файлах без явной политики: форматы почти совпадают, но мелкие отличия дают шум в diff. Обычно выбирают один форматтер (часто Ruff как единая точка) и убирают Black из hooks.

5. Ruff: правила и игноры

per-file-ignores для миграций ("migrations/*" = ["E501"]). Подключайте pyupgrade, flake8-bugbear через extend-select. noqa: XXX001 оставляйте с комментарием «почему», иначе техдолг.

6. mypy: постепенное внедрение

[[tool.mypy.overrides]] для legacy-модулей с ignore_errors = true на время. warn_unused_ignores ловит устаревшие # type: ignore. Плагины pydantic / SQLAlchemy — отдельные пакеты типов.

7. Чек-лист

Единая версия Python в ruff/mypy и в Docker.
Постепенное ужесточение mypy (strict по модулям).
Не смешивать black и ruff format в одном файле без правил.
pre-commit autoupdate по расписанию с фиксацией rev в PR.
Кэш mypy (cache_dir) в CI для ускорения.

Дальше: тег «Линтинг»