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
各项参数解释：
- 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，可以确保开发环境与项目级配置保持一致。这种方法不仅提升了代码格式化的一致性，也优化了开发体验，使得代码风格管理更加高效和自动化。
