Python isort：按行长控制多行导入格式化

本教程详细介绍了如何配置 isort 和 VSCode，以实现 Python 导入语句的智能格式化。通过在 pyproject.toml 文件中设置 isort 的 multi_line_output 和 force_grid_wrap 参数，并相应调整 VSCode 的 settings.json，可以确保导入语句仅在超出指定行长度限制时才自动拆分为多行，从而保持代码的简洁性和可读性。

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

isort 是一个流行的 Python 库，用于自动排序和格式化导入语句。它提供了多种输出样式（multi_line_output），允许开发者根据团队规范或个人偏好来调整导入的显示方式。然而，在某些情况下，isort 可能会在导入语句未达到指定行长度限制时，也将其自动拆分为多行，这可能与预期行为不符。

例如，原始导入语句可能如下：

import pandas as pd
from tableau_api_lib.utils.querying import get_datasources_dataframe, get_workbooks_dataframe

在某些默认或不当配置下，isort 可能会将其格式化为：

import pandas as pd
from tableau_api_lib.utils.querying import (
    get_datasources_dataframe,
    get_workbooks_dataframe,
)

而我们期望的是，只有当导入语句的长度超过设定的 line_length（例如 120 字符）时，才将其拆分为多行。

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

为了实现基于行长度的条件式多行导入格式化，我们需要在项目的 pyproject.toml 文件中为 isort 进行详细配置。pyproject.toml 是现代 Python 项目中管理工具配置的首选方式，它能确保项目内所有开发者和自动化工具（如 GitHub Actions）使用一致的格式化规则。

以下是推荐的 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

各项配置的解释如下：

• line_length = 120: 设置单行代码的最大字符长度为 120。isort 将尝试在此限制内保持导入语句为单行。
• multi_line_output = 3: 指定多行导入的输出样式为“垂直悬挂缩进”（Vertical Hanging Indent）。这是 black 格式化器所采用的风格，它在导入语句需要拆分时，将每个导入项放置在新行上，并使用括号包裹。
  • 例如：

    from some_module import (
        item_one,
        item_two,
    )

• include_trailing_comma = true: 在多行导入的最后一个元素后添加逗号。这有助于版本控制系统中的差异对比，并允许更灵活地添加或删除导入项。
• force_grid_wrap = 0: 这是实现条件式多行格式化的关键。 将此值设置为 0 意味着 isort 不会强制将导入语句以网格（grid）形式（即每个导入项都独占一行）进行包装，除非它们超出了 line_length 限制。如果设置为 1 或更大，isort 会尝试在达到指定数量的导入项后强制换行，无论行长度如何。
• use_parentheses = true: 强制在多行导入中使用括号。这与 multi_line_output = 3 样式配合使用。
• ensure_newline_before_comments = true: 确保在导入语句后的注释前有一个新行，以提高可读性。

通过这些配置，isort 将只在导入语句的长度超过 120 字符时，才将其拆分为 multi_line_output = 3 样式。

3. 配置 VSCode 以配合 isort

为了让 VSCode 在保存文件时自动应用上述 isort 配置，我们需要调整 settings.json 文件。关键在于让 VSCode 知道 isort 的配置信息来自 pyproject.toml，而不是直接在 VSCode 中重复定义。

请更新您的 VSCode settings.json 文件，如下所示：

{
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "ms-python.python",
    "[python]": {
        "editor.codeActionsOnSave": {
            "source.organizeImports": true
        }
    }
}

各项配置的解释如下：

• "editor.formatOnSave": true: 启用在保存文件时自动格式化。
• "editor.defaultFormatter": "ms-python.python": 设置 Python 文件的默认格式化程序为 VSCode Python 扩展提供的内置格式化功能。请注意，如果您同时使用 black 作为主要的代码格式化工具，并希望它作为默认格式化器，则此项可能需要设置为 "ms-python.black-formatter"。然而，对于 isort 的导入组织功能，source.organizeImports 是关键。
• "[python]": { ... }: 针对 Python 文件特定的设置。
• "editor.codeActionsOnSave": { "source.organizeImports": true }: 这是触发 isort 工作的核心。 当保存 Python 文件时，VSCode 会执行 source.organizeImports 操作。这个操作会调用项目中安装的 isort 工具，并根据 pyproject.toml 中的配置来组织和格式化导入语句。

重要提示：

• 请确保移除 settings.json 中任何与 isort.args 相关的配置（例如 "isort.args": ["--line-length", "120", "--profile", "black"]），因为这些硬编码的参数会覆盖 pyproject.toml 中的设置。让 isort 自动发现并使用 pyproject.toml 是最佳实践。
• 确保您的项目虚拟环境中已安装 isort。如果您使用 poetry 或 pipenv 等工具管理依赖，请确保 isort 已添加到项目的依赖中。

4. 效果验证

经过上述配置后，当您在 VSCode 中保存 Python 文件时，isort 将按照 pyproject.toml 中定义的规则进行导入格式化。

• 对于长度未超过 120 字符的导入语句：

  from tableau_api_lib.utils.querying import get_datasources_dataframe, get_workbooks_dataframe

  它将保持在单行，因为 force_grid_wrap = 0 阻止了不必要的换行。

• 对于长度超过 120 字符的导入语句： 它将被自动拆分为多行，并采用 multi_line_output = 3 定义的垂直悬挂缩进样式。

这种配置方法不仅在本地开发环境中提供了智能的格式化体验，还能通过在 CI/CD 流水线（如 GitHub Actions）中使用 isort --check . 命令，确保整个团队的代码库都遵循相同的导入格式化标准。

总结

通过在 pyproject.toml 文件中精确配置 isort 的 line_length、multi_line_output 和 force_grid_wrap 等参数，并配合 VSCode 的 source.organizeImports 功能，我们能够实现 Python 导入语句的条件式多行格式化。这不仅提高了代码的可读性，也确保了团队内部代码风格的一致性，从而提升了开发效率和代码质量。