isort 精细化配置：实现按需导入语句换行与VSCode集成

1. 理解 isort 的导入语句格式化行为

isort 是一个强大的 python 导入语句排序工具，它能自动将导入语句按字母顺序分组并排序。当与 black 这样的代码格式化工具结合使用时，isort 通常会遵循 black 的风格规范，包括行长限制和多行输出模式。然而，默认配置下，有时 isort 可能会将导入语句格式化为多行形式，即使单行并未超出设定的行长限制。这通常是由于 multi_line_output 参数的默认值或与 force_grid_wrap 参数的交互导致的。

例如，以下导入语句：

from tableau_api_lib.utils.querying import get_datasources_dataframe, get_workbooks_dataframe

在某些配置下，可能会被格式化为：

from tableau_api_lib.utils.querying import (
    get_datasources_dataframe,
    get_workbooks_dataframe,
)

而我们的目标是，只有当单行导入语句的长度超过指定阈值（如120字符）时，才进行换行。

2. 通过 pyproject.toml 精细化配置 isort

为了实现导入语句的按需换行，我们应该在项目的 pyproject.toml 文件中配置 isort。这种方式是管理项目级工具配置的最佳实践，因为它能确保所有开发者和 CI/CD 环境使用相同的规则。

在 pyproject.toml 中添加或修改 [tool.isort] 部分，示例如下：

[tool.isort]
line_length = 120
multi_line_output = 3
include_trailing_comma = true
force_grid_wrap = 0
use_parentheses = true
ensure_newline_before_comments = true

各项参数解释：

集简云

软件集成平台，快速建立企业自动化与智能化

22

查看详情

• line_length = 120: 设置最大行长为 120 字符。isort 将尝试在此限制内保持代码在单行。
• multi_line_output = 3: 这是实现按需换行的关键。
  • 3 代表 "Vertical Hanging Indent"（垂直悬挂缩进）模式。在这种模式下，isort 会优先尝试将导入语句保持在单行。只有当单行超出 line_length 限制时，它才会将其拆分为多行，并使用括号包裹，每个导入项一行，并进行缩进。
  • 其他常见的 multi_line_output 值，如 5 (Black profile default) 或 0 (Wrap) 等，可能会导致更激进的换行策略。
• force_grid_wrap = 0: 另一个关键参数。
  • 0 意味着 isort 不会强制使用网格布局换行。它将允许 multi_line_output 参数根据行长限制来决定是否换行。
  • 如果设置为非零值，isort 可能会在未达到行长限制时也强制换行，从而产生不期望的多行输出。
• include_trailing_comma = true: 在多行导入语句的最后一个元素后添加逗号，这与 black 风格保持一致，并有助于版本控制中的差异追踪。
• use_parentheses = true: 确保多行导入语句使用括号包裹，这也是 black 风格的常见做法。
• ensure_newline_before_comments = true: 在导入语句后的注释前添加一个新行，以提高可读性。

通过以上配置，isort 将在命令行运行（如 isort --line-length 120 --profile black .）时，严格遵循这些规则。

3. VSCode 集成与配置优化

为了让 VSCode 在保存时自动应用 isort 的这些配置，我们需要调整 settings.json。关键在于让 VSCode 的 Python 扩展（ms-python.python）能够识别并使用 pyproject.toml 中的 isort 配置，而不是通过 VSCode 自己的 isort.args 来传递参数。

移除 isort.args 配置，并确保 source.organizeImports 被启用。修改后的 settings.json 片段如下：

{
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "ms-python.python", // 确保使用Python扩展作为默认格式化器
    "[python]": {
        "editor.codeActionsOnSave": {
            "source.organizeImports": true // 启用保存时组织导入
        }
    }
    // 移除或注释掉任何 isort.args 配置，例如：
    // "isort.args": ["--line-length", "120", "--profile", "black"]
}

注意事项：

• editor.defaultFormatter: 确保将其设置为 "ms-python.python"。Python 扩展会检测并使用项目中配置的格式化工具（如 black 和 isort）。
• 移除 isort.args: 这是至关重要的一步。如果 isort.args 存在于 settings.json 中，它会优先于 pyproject.toml 中的配置，导致项目级设置失效。通过移除它，VSCode 会自动查找并应用 pyproject.toml 中定义的 isort 规则。
• Python 环境: 确保 VSCode 使用的项目虚拟环境（venv）中安装了 isort。如果项目使用 poetry 或 pipenv，VSCode 通常能自动检测并激活正确的环境。

4. 总结

通过在 pyproject.toml 文件中精细配置 isort 的 multi_line_output = 3 和 force_grid_wrap = 0 参数，我们可以有效地控制导入语句的换行行为，使其仅在超出指定行长时才进行多行格式化。结合优化的 VSCode 设置，移除冗余的 isort.args，可以确保开发环境与项目级配置保持一致。这种方法不仅提升了代码格式化的一致性，也优化了开发体验，使得代码风格管理更加高效和自动化。

以上就是isort 精细化配置：实现按需导入语句换行与VSCode集成的详细内容，更多请关注php中文网其它相关文章！