Python linter: как настроить автоматический анализ кода и не сойти с ума

Столкнулся с ситуацией в одном проекте: команда из 8 человек писала код в разном стиле. Один использовал 4 пробела, другой — табы. Третий вообще забывал про type hints. На code review это выглядело как беспорядок. Потратили неделю на то, чтобы прибраться. Потом внедрили linter — и проблема исчезла.

Если ты разработчик и ещё не использовал Python linter, то упускаешь серьёзный инструмент. Он не только ловит ошибки, но и принуждает команду писать код в единообразном стиле. Честно? Большинство проектов, где я видел chaos в коде, просто не настроили linting.

Давай разбираться, что это вообще такое и как внедрить в реальном проекте.

Статический анализ кода: почему это не просто проверка синтаксиса

Многие путают linter с обычной проверкой синтаксиса. Типа, "компилятор проверил — и всё норм". Нет. Это совсем разные вещи.

Синтаксическая проверка — это когда интерпретатор просто читает код и говорит: "Тут скобка не закрыта, я не могу это запустить". Точка. Python это делает при импорте.

Linter же — это инструмент статического анализа, который смотрит на код ещё до запуска и говорит: "Слушай, тут у тебя переменная объявлена и не используется. Тут нарушен PEP 8. Тут потенциальная ошибка логики. Тут ты присваиваешь значение переменной после того, как её используешь — это выглядит странно".

По-хорошему, статический анализ — это целая область. Есть несколько слоёв:

Linting — проверка стиля и очевидные ошибки (неиспользуемые переменные, неправильное имение функций по PEP 8)

Type checking — анализ типов данных. Если функция ожидает int, а ты передаёшь str, то type checker это поймёт

Security scanning — поиск уязвимостей (SQL injection, небезопасные функции и т.д.)

Complexity analysis — проверка сложности функций, циклических зависимостей

Это разные инструменты, но работают они рядом. Вместе они создают систему контроля качества.

Основные Python linter'ы: что выбрать

На рынке несколько лидеров. Не буду убеждать, что один лучше другого — у каждого своя ниша.

Pylint — это классика. Самый строгий и полнофункциональный. Ловит много проблем, но может быть многословным в предупреждениях. Конфиг сложноват.

pip install pylint
pylint my_module.py

Вывод выглядит так:

your_module.py:1:0: C0111: Missing module docstring (missing-docstring)
your_module.py:5:4: W0612: Unused variable 'x' (unused-variable)

Flake8 — это средняя мера между строгостью и удобством. Комбинирует pycodestyle (PEP 8), pyflakes (логические ошибки) и McCabe (сложность). Я его использую в 80% проектов. Просто, понятно, расширяемо.

pip install flake8
flake8 my_module.py

Ruff — это новичок, написан на Rust. Очень быстрый. Если у тебя большой проект с тысячами файлов, Ruff проверит их в секунды, а не минуты. Постепенно вытесняет Flake8.

pip install ruff
ruff check my_module.py

Black — это не совсем linter, это formatter. Он не ловит ошибки, он их исправляет. Переписывает твой код в единообразном стиле (по его мнению). Либо ты его любишь, либо ненавидишь. Я люблю — экономит время на споры о стиле.

pip install black
black my_module.py  # Переписывает файл на месте

mypy — это type checker. Специализируется на проверке типов. Если ты используешь type hints (а ты должен), mypy найдёт несоответствия.

pip install mypy
mypy my_module.py

Ну вот смотрите, большинство команд используют комбинацию: Ruff (или Flake8) + Black + mypy. Каждый инструмент делает своё, но вместе они создают полноценную систему контроля.

Как настроить linter в реальном проекте

Теория — это хорошо, но без практики это просто слова. Давай настроим всё как надо.

Сначала создаём виртуальное окружение и ставим инструменты:

python -m venv venv
source venv/bin/activate  # На Windows: venv\Scripts\activate

pip install ruff black mypy

Теперь создаём конфиг в корне проекта — pyproject.toml. Это стандартный способ конфигурации современных Python проектов.

[tool.ruff]
line-length = 100
target-version = "py310"
exclude = [".git", ".venv", "build", "dist"]

[tool.ruff.lint]
select = [
    "E",    # pycodestyle errors
    "W",    # pycodestyle warnings
    "F",    # pyflakes
    "I",    # isort (import sorting)
    "C901", # mccabe complexity
    "B",    # flake8-bugbear
]
ignore = [
    "E501",  # line too long (Black будет следить за этим)
    "W503",  # line break before binary operator
]

[tool.black]
line-length = 100
target-version = ['py310']
exclude = '/(\.git|\.venv|build|dist)/'

[tool.mypy]
python_version = "3.10"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = false  # Строгий режим — включи если готов
ignore_missing_imports = true

Хорошо. Теперь добавляем скрипты в package.json или в Makefile. Я предпочитаю Makefile — он универсален.

.PHONY: lint format typecheck

lint:
	ruff check .

format:
	black .
	ruff check . --fix

typecheck:
	mypy .

check: lint typecheck
	@echo "All checks passed!"

Теперь команда может просто вызвать:

make check      # Проверить всё
make format     # Автоматически исправить стиль

Если кто-то попробует закоммитить код с ошибками, мы его не пустим. Для этого используем pre-commit hook.

Ставим pre-commit:

pip install pre-commit

Создаём .pre-commit-config.yaml:

repos:
  - repo: https://github.com/charliermarsh/ruff-pre-commit
    rev: v0.1.11
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.7.1
    hooks:
      - id: mypy
        additional_dependencies: ['types-all']

Установили? Отлично:

pre-commit install

Теперь при каждом коммите автоматически запустится проверка. Если что-то не так — коммит не пройдёт. Разработчику придётся исправить код и попробовать снова.

Интеграция в CI/CD: настоящий контроль качества

Pre-commit hook — это хорошо, но этого недостаточно. Опытный разработчик может его обойти с флагом --no-verify. Нужна проверка на сервере.

Вот пример для GitHub Actions:

name: Code Quality

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      
      - name: Install dependencies
        run: |
          pip install ruff black mypy
      
      - name: Lint with Ruff
        run: ruff check .
      
      - name: Check formatting
        run: black --check .
      
      - name: Type check
        run: mypy .

Для GitLab CI похоже:

lint:
  image: python:3.10
  script:
    - pip install ruff black mypy
    - ruff check .
    - black --check .
    - mypy .

Теперь любой pull request будет проверен автоматически. Если тесты упадут — PR не сможет быть слит. Точка.

Статический анализ vs динамическое тестирование: что ловит что

Важно понимать: linter и unit-тесты — это разные вещи.

Статический анализ (linter) проверяет код без запуска:

• Стиль кода (PEP 8)
• Очевидные ошибки (неиспользуемые переменные, опечатки в именах)
• Типы данных (если используешь type hints)
• Потенциальные баги (например, сравнение с None неправильным способом)

Динамическое тестирование (unit-тесты) запускает код и проверяет результаты:

• Логика работает правильно
• Функция возвращает ожидаемый результат
• Обработка исключений работает
• Производительность приемлема

Linter никогда не поймёт, что твой алгоритм сортировки работает неправильно. Для этого нужен тест. Но linter поймёт, что ты забыл вернуть значение из функции. Или что переменная объявлена, но никогда не используется.

Вместе они создают двойную защиту. На одном проекте мы внедрили оба подхода: linting на pre-commit и в CI, плюс юнит-тесты с покрытием не менее 80%. Количество багов в production упало на 70%.

Когда linter становится помехой (и что с этим делать)

Честно? Иногда linter может быть раздражающим. Например, Black может переносить твой красивый код в странные места. Или Pylint может ныть по поводу того, что функция слишком сложная, хотя она логически простая.

В таких случаях можно отключить конкретные проверки. Либо глобально в конфиге, либо локально в коде:

# Отключаем проверку для конкретной строки
x = unused_variable  # noqa: F841

# Или для целой функции
def complex_function():  # noqa: C901
    # код

Но будь осторожен. Если ты отключаешь слишком много проверок, то теряешь смысл использования linter'а. Лучше обсудить с командой, какие правила имеют смысл именно для вас.

На одном проекте мы отключили проверку на длину строк (E501), потому что код был очень математический и переносы делали его нечитаемым. На другом проекте оставили все проверки как есть. Зависит от контекста.

Python linter online: когда нет возможности ставить локально

Иногда нужно быстро проверить код без установки инструментов. Есть несколько онлайн-сервисов.

Pylint online (pylint.pycqa.org) — просто вставляешь код и видишь результаты. Удобно для быстрой проверки.

CodeSandbox и Replit имеют встроенные linter'ы прямо в редакторе.

Но это временное решение. В реальном проекте нужно настроить всё локально и в CI/CD.

Так что, по-хорошему, Python linter — это не опция, а необходимость. Если ты работаешь в команде или на долгосрочном проекте, без него не обойтись.

Если ты уже внедрил linting в свой проект, то ты знаешь, о чём я говорю. Если нет — начни с Ruff и Black. Это займёт 30 минут, а экономить будет часы.

Кстати, говоря о автоматизации кода — мы в Distiq делаем похожую штуку, но для целых pull request'ов. Наш AI-бот анализирует каждый MR/PR и оставляет инлайн-комментарии с замечаниями: находит баги, уязвимости, проблемы с производительностью. Работает с Python, JavaScript, Go и другими языками. Если надоела ручная проверка чужого кода — попробуй.