理解isort的导入格式化行为
在使用isort工具进行python导入语句的排序和格式化时，开发者常常希望其行为能够智能地适应代码风格，例如仅在导入语句的行长度超出预设阈值时才将其拆分为多行。然而，默认或某些配置下，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,
)而我们期望的行为是，只有当第二行导入语句的字符长度超过120个字符时，才将其拆分为多行。
通过pyproject.toml配置isort
要实现这种精细化的控制，核心在于isort的配置。推荐使用项目根目录下的pyproject.toml文件进行配置，这样可以确保整个项目团队和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
各项配置的解释：
仅从仓库的暂存文件生成 Git 提交消息。当用户要求 Codex 根据暂存更改、缓存差异、Git 索引或已通过 `git add` 添加的文件来编写、起草、创建或建议提交消息时使用；切勿代表用户执行提交操作。
- line_length = 120: 设置单行代码的最大字符长度。isort将尝试遵守此限制，并在超出时进行换行。
- multi_line_output = 3: 这是实现条件换行的关键。multi_line_output定义了多行导入语句的输出样式。
- 3 对应于 VERTICAL_HANGING_INDENT 样式。在这种模式下，isort会尝试将导入语句保持在单行，除非超出 line_length 限制，或者当导入列表较长时，它会使用括号将导入项垂直排列并进行悬挂缩进。
- 其他常见样式包括：0 (NOQA), 1 (VERTICAL), 2 (GRID), 4 (HANGING_INDENT), 5 (NO_FOLLOWING_IMPORTS), 6 (CLOSE_PARENTHESIS_ONLY), 7 (VERTICAL_GRID).
- include_trailing_comma = true: 在多行导入列表的最后一个元素后添加逗号，这有助于版本控制系统（如Git）在添加新导入项时减少不必要的行更改。
- force_grid_wrap = 0: 禁用“强制网格换行”功能。如果设置为非零值（例如1或2），isort会强制将导入列表拆分为多行网格样式，即使行长未达到限制。将其设置为0是确保导入语句仅在必要时才换行的关键。
- use_parentheses = true: 确保在多行导入语句中使用括号包裹导入项。这与multi_line_output = 3配合使用，提供了清晰的视觉结构。
- ensure_newline_before_comments = true: 确保在导入语句后的注释前有一新行，保持代码整洁。
通过上述配置，isort将优先尝试保持导入语句在单行，只有当行长超过120字符时，才会将其拆分为使用括号包裹的垂直悬挂缩进样式。
在VSCode中集成isort配置
为了让VSCode编辑器在保存时自动应用上述isort配置，需要调整VSCode的settings.json。关键在于确保VSCode的isort扩展能够正确读取项目的pyproject.toml配置，而不是被VSCode自身的isort.args设置覆盖。
修改settings.json如下：
{
"editor.formatOnSave": true,
"editor.defaultFormatter": "ms-python.python", // 可以是ms-python.black-formatter或其他，但确保Python扩展能够处理isort
"[python]": {
"editor.codeActionsOnSave": {
"source.organizeImports": true
}
},
// 移除或注释掉isort.args，让isort读取pyproject.toml
// "isort.args": ["--line-length", "120", "--profile", "black"]
}关键点说明：
- "editor.formatOnSave": true: 启用文件保存时自动格式化功能。
- "editor.defaultFormatter": "ms-python.python": 设置Python文件的默认格式化器为Python扩展自身。Python扩展通常会与isort良好集成。如果使用black-formatter，它主要负责代码的整体格式化，而导入排序通常由source.organizeImports触发的isort处理。
- "[python]": { "editor.codeActionsOnSave": { "source.organizeImports": true } }: 这是触发isort在保存时运行的核心设置。source.organizeImports会调用已安装的isort工具来整理导入。
- 移除isort.args: 最重要的一步是移除（或注释掉）settings.json中任何isort.args的配置。当isort.args存在时，VSCode的isort扩展会优先使用这些参数，从而忽略pyproject.toml中的配置。移除后，isort将自动查找并使用项目根目录下的pyproject.toml文件。
验证和注意事项
- 安装isort: 确保isort已安装在您的项目虚拟环境（如使用Poetry管理的venv）中。例如，在项目根目录的虚拟环境中运行pip install isort或poetry add isort --group dev。
- 重启VSCode: 修改settings.json和pyproject.toml后，建议重启VSCode以确保所有配置生效。
- 测试: 打开一个Python文件，修改其导入语句，然后保存。观察导入语句是否按照预期进行格式化：短的保持单行，长的则自动换行。
通过上述配置，您可以实现对Python导入语句格式化行为的精确控制，确保代码风格的一致性，并在保持代码整洁的同时，避免不必要的格式化变动。这种基于项目配置的方法也使得团队协作更加高效，因为所有成员都遵循相同的格式化规则。
