Как убрать F821 в ноутбуках Databricks: builtins в Ruff для spark

F821 undefined-name при использовании spark в ноутбуках Databricks? Настройте Ruff: добавьте spark в builtins, чтобы убрать предупреждение без noqa в проекте.

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

Работая с ноутбуками в управляемой среде вроде Databricks, вы часто опираетесь на глобальные объекты, которые платформа подмешивает за вас. Один из самых распространённых — spark. Локально, однако, ваш линтер не видит этого контекста выполнения и выдаёт F821 undefined-name. Для инструмента это справедливое предупреждение, но в данном случае — лишний шум.

Минимальный воспроизводимый пример

Ниже — фрагмент, который в ноутбуке Databricks работает без нареканий, но ruff check сообщает F821:

# Источник ноутбука Databricks
result_frame = spark.sql("SELECT 'hello world'")
result_frame.show()

Почему возникает F821

Код ссылается на имя, которое не объявлено в самом файле. В рантайме Databricks spark приходит из окружения, но линтер видит лишь исходник и считает идентификатор неопределённым — отсюда ошибка F821 undefined-name.

Есть очевидные обходные пути — явно загружать глобальный объект или расставлять # noqa: F821 в нужных местах, — но это либо плодит шаблонный код, либо засоряет строки. Есть более аккуратный способ объявить такие имена для Ruff.

Решение: сообщите Ruff о ваших глобальных переменных через builtins

В Ruff есть настройка для объявления дополнительных встроенных имён. Добавив туда spark, вы даёте линтеру понять, что это известный глобальный объект, и он перестанет помечать его как неопределённый. Конфигурацию можно разместить в pyproject.toml или ruff.toml.

# pyproject.toml
[tool.ruff]
builtins = ["spark"]

# ruff.toml
builtins = ["spark"]

После добавления этой записи Ruff больше не будет поднимать F821 при использовании spark в ваших ноутбуках.

Зачем это делать

Объявляя в Ruff глобальные объекты, которые предоставляет среда, вы держите код сосредоточенным на бизнес-логике — без лишних импортов и подавлений на каждой строке. К тому же это фиксирует осознанный контракт с окружением выполнения в одном централизованном месте — конфигурации линтера, — обеспечивая единообразие по всему проекту.

Вывод

Если ваши Python‑ноутбуки зависят от глобалей, которые предоставляет Databricks, например spark, настройте Ruff так, чтобы он узнавал их через параметр builtins. Кодостанется чистым, лишний шум исчезнет, а полезные статические проверки сохранятся повсюду.