如何配置Ruff linter忽略Databricks环境提供的全局变量？

我在Databricks环境里维护一个包含Notebook的Python代码库，环境会自动提供spark这类全局变量，示例代码如下：

# Databricks notebook source
df = spark.sql("SELECT 'hello world'")
df.show()

但执行ruff check时会触发F821（未定义名称）错误，之前的两种规避方案都有弊端：要么显式加载全局变量增加复杂度，要么加# noqa: F821注释让代码变乱。下面是几个更优的解决办法：

1. 在Ruff配置文件中声明全局变量 #

直接在项目根目录的pyproject.toml或.ruff.toml里添加Databricks提供的全局变量列表，Ruff会把这些变量当作已定义的内置变量，不用改任何业务代码。

示例pyproject.toml配置：

[tool.ruff.lint]
builtins = ["spark", "dbutils", "display"]

如果用.ruff.toml：

lint.builtins = ["spark", "dbutils", "display"]

这是最干净的方案，完全不影响代码逻辑，也不会增加复杂度。

2. 给Notebook单独配置规则 #

如果项目里混有普通Python代码和Databricks Notebook，可以针对Notebook目录单独配置规则，保证普通代码检查严格的同时适配Notebook环境。

比如在pyproject.toml里这么写：

[tool.ruff.lint]
# 普通代码的全局配置
builtins = []

# 针对Notebook目录的特殊配置
[[tool.ruff.lint.per-file-ignores]]
path = "notebooks/**/*.py"
builtins = ["spark", "dbutils", "display"]

3. 用类型注解标记全局变量 #

要是不想改配置文件，就在Notebook开头加一行极简的类型注解，只给静态分析工具看，完全不影响运行：

# Databricks notebook source
from pyspark.sql import SparkSession
spark: SparkSession  # 仅用于告诉Ruff这是全局变量

df = spark.sql("SELECT 'hello world'")
df.show()

这种方式侵入性极低，代码也不会显得杂乱。

内容的提问来源于stack exchange，提问作者Fabitosh