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）使用一致的格式化规则。
立即学习“Python免费学习笔记（深入）”；
以下是推荐的 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 导入语句的条件式多行格式化。这不仅提高了代码的可读性，也确保了团队内部代码风格的一致性，从而提升了开发效率和代码质量。
