per-file-ignores и noqa

Параметр per-file-ignores позволяет отключать определённые правила для файлов, соответствующих glob-паттерну. Это более гибкий аналог глобального ignore, действующий только для указанных файлов.

Синтаксис: ключ — glob-паттерн файлов, значение — список правил для отключения:

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]
"tests/**/*.py" = ["S101", "E501"]
"migrations/*.py" = ["ALL"]
"settings.py" = ["S105", "S106"]

Типичные сценарии использования

Glob-паттерны: подробности

Ruff использует glob-паттерны для сопоставления файлов. Вот как они работают:

Полный пример конфигурации с per-file-ignores

[tool.ruff.lint]
select = ["E", "F", "I", "N", "UP", "B", "S", "ANN"]
ignore = ["E501"]

[tool.ruff.lint.per-file-ignores]
# в тестах разрешены assert и длинные строки
"tests/**/*.py" = ["S101", "ANN", "D"]

# в миграциях отключено всё — они автосгенерированы
"*/migrations/*.py" = ["ALL"]

# в __init__.py разрешён реэкспорт
"**/__init__.py" = ["F401"]

# в conftest не нужны аннотации
"**/conftest.py" = ["ANN"]

# в конфигах можно hardcoded значения
"**/settings*.py" = ["S105", "S106"]

# в скриптах не обязательны аннотации
"scripts/**/*.py" = ["ANN", "D"]

# в примерах документации не нужна документрация
"**/docs/**/examples/**/*.py" = ["D", "ANN"]

pyproject.toml

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]
"tests/**/*.py" = ["S101", "E501"]

ruff.toml

[lint.per-file-ignores]
"__init__.py" = ["F401"]
"tests/**/*.py" = ["S101", "E501"]

Комментарий # noqa на строке кода отключает проверки Ruff для этой строки. Это самый точный способ подавления предупреждений — он действует только на одну строку и не затрагивает остальной код.

Форматы noqa

import os  # noqa: F401               # отключить одно правило
import sys  # noqa: F401, E302        # несколько правил
import json  # noqa                   # отключить все правила для строки

x = 1  # noqa: E501                  # длинная строка, но тут коротко

class MyClass:  # noqa: N801          # разрешить имя не в CamelCase
    pass

Правильный способ использования noqa

Хорошая практика — комментировать причину отключения:

# Хорошо: указан код и причина
import os  # noqa: F401 — используется в type: ignore

# Плохо: без кода — непонятно что отключено
import os  # noqa

# Плохо: без причины — придётся гадать на код-ревью
import os  # noqa: F401

Специальный комментарий # ruff: noqa в первой строке файла (или сразу после shebang) отключает проверки для всего файла. Это удобнее и чище, чем per-file-ignores для отдельных случаев.

# ruff: noqa                    # отключить все правила в файле

# ruff: noqa: E501              # отключить E501 во всём файле

# ruff: noqa: E501, F401        # несколько правил для всего файла

# ruff: noqa: E501, F401, N801  # комбинированный

Когда использовать # ruff: noqa вместо per-file-ignores:

Ruff поддерживает комментарии isort для управления группировкой импортов. Это позволяет контролировать, как Ruff (в режиме isort) обрабатывает импорты в конкретных файлах.

# isort: skip_file
import os
import sys
# Этот файл не будет сортироваться isort

import os
import sys

# isort: split — принудительное разделение

import django  # эта группа не смешается с stdlib
import requests

# isort: skip — пропустить один импорт
import os
import sys  # isort: skip  # этот импорт не будет переставлен
import json

Правило RUF100 (Ruff-specific) находит # noqa комментарии, которые стали не нужны — то есть правила, которые они отключают, больше не срабатывают на этой строке. Это помогает поддерживать код в чистоте и не накапливать мёртвые подавления.

Как это работает

Когда правило перестаёт срабатывать на строке (например, вы исправили код, обновили конфиг или правило было удалено), # noqa для этого правила становится избыточным. RUF100 сообщит об этом:

import os  # noqa: F401

# Если F401 больше не активен (правило отключено в конфиге),
# Ruff выдаст: RUF100 Unused noqa directive 'F401'

Автоматическое удаление лишних noqa

Ruff может автоматически удалять ненужные noqa-комментарии:

# Запустить проверку + автоудаление лишних noqa
ruff check --fix --unsafe-fixes

# Только RUF100
ruff check --select RUF100 --fix

Типичные причины появления лишних noqa

1. Правило было отключено в конфиге (через ignore), но noqa остался.
2. Правило было удалено из select, но noqa остался.
3. Код был изменён и больше не нарушает правило.
4. Обновление Ruff — правило перестало существовать или было переименовано.

# Пример: правило отключено через ignore
# [tool.ruff.lint]
# ignore = ["F401"]

import os  # noqa: F401   # RUF100: это больше не нужно — F401 и так отключён

Флаг --add-noqa автоматически добавляет # noqa: {rule} ко всем строкам, где Ruff находит нарушения. Это полезно, когда вы внедряете Ruff в существующий проект и хотите сначала заглушить все ошибки, а потом исправлять их постепенно.

# Добавить noqa ко всем текущим нарушениям
ruff check --add-noqa

# Добавить noqa только для конкретного правила
ruff check --add-noqa --select F401

# Добавить noqa для конкретной директории
ruff check src/ --add-noqa

После добавления noqa, код будет чист с точки зрения Ruff, и вы сможете постепенно удалять noqa по мере исправления кода:

# До --add-noqa:
import os
import sys

# После --add-noqa:
import os  # noqa: F401
import sys  # noqa: F401

Стратегия внедрения Ruff в legacy проект

1. Установите Ruff и настройте select минимально (например, E, F, I).
2. Запустите ruff check --add-noqa — все текущие ошибки будут заглушены noqa.
3. Настройте pre-commit с Ruff.
4. Теперь Ruff будет проверять только новый код (старые ошибки заглушены).
5. Постепенно исправляйте старые noqa (RUF100 подсветит неактуальные).
6. Добавляйте новые категории правил по одной.

# Шаг 1: минимальная конфигурация
[tool.ruff.lint]
extend-select = ["E", "F", "I"]

# Шаг 2: заглушить все ошибки
# ruff check --add-noqa

# Шаг 3: починить код и удалить noqa
# ruff check --fix

# Шаг 4: добавить больше правил
[tool.ruff.lint]
extend-select = ["E", "F", "I", "N", "UP"]

# Шаг 5: снова заглушить новые ошибки и повторять

Если вам нужно отключить проверку для нескольких строк подряд без # noqa на каждой строке, есть два варианта:

1. Добавить # ruff: noqa в начало файла — отключит всё в файле.
2. Вынести проблемный код в отдельный файл и настроить per-file-ignores.

Когда вы используете несколько механизмов подавления, работает следующий приоритет (от высшего к низшему):

1. # noqa на конкретной строке — имеет наивысший приоритет.
2. # ruff: noqa в начале файла — отключает для всего файла.
3. per-file-ignores — настройка в конфиге для паттерна файлов.
4. ignore — глобальное отключение правил.
5. select / extend-select — какие правила вообще включены.

Это означает, что:

• # noqa: F401 переопределит select = ["F401"] (правило включено, но noqa отключает).
• per-file-ignores переопределит глобальный select для конкретных файлов.
• Если правило не входит в select, никакой noqa для него не нужен.

Пример 1: Django проект

[tool.ruff.lint]
select = ["E", "F", "I", "N", "UP", "B", "S", "DJ"]

[tool.ruff.lint.per-file-ignores]
"*/migrations/*.py" = ["ALL"]
"*/tests/**/*.py" = ["S101", "DJ"]
"**/settings.py" = ["S105", "S106"]
"**/admin.py" = ["F401", "D"]
"**/models.py" = ["D"]

Пример 2: FastAPI проект

[tool.ruff.lint]
select = ["E", "F", "I", "N", "UP", "B", "ANN"]

[tool.ruff.lint.per-file-ignores]
"**/schemas.py" = ["B008"]       # Pydantic использует Field(...) в дефолтах
"**/dependencies.py" = ["B008"]  # FastAPI зависимости
"**/routers/**/*.py" = ["ANN"]   # В роутерах аннотации необязательны
"tests/**/*.py" = ["ANN", "S101"]
"**/config.py" = ["S105"]

Пример 3: Пакет с __init__.py реэкспортами

# my_package/__init__.py
from my_package.core import MyClass  # noqa: F401 — реэкспорт для внешнего API
from my_package.utils import helper  # noqa: F401

__all__ = ["MyClass", "helper"]

Или через per-file-ignores:

[tool.ruff.lint.per-file-ignores]
"**/__init__.py" = ["F401"]

Пример 4: Проект с Jupyter ноутбуками

[tool.ruff.lint]
select = ["E", "F", "I"]

[tool.ruff.lint.per-file-ignores]
"**/notebooks/**/*.py" = ["ALL"]   # экспортированные ноутбуки
"**/experiments/**/*.py" = ["ALL"] # экспериментальный код