Python 设置参考

Visual Studio Code 的 Python 扩展是高度可配置的。本文档介绍了一些可以使用的关键设置。

有关在 VS Code 中使用设置的一般信息，请参阅用户和工作区设置，以及变量参考，了解有关预定义变量支持的信息。

常规 Python 设置

设置 (python.)	默认值	描述
condaPath	`"conda"`	`conda` 可执行文件的路径。
defaultInterpreterPath	`"python"`	Python 扩展首次加载到工作区时使用的默认 Python 解释器的路径，或包含 Python 解释器的文件夹的路径。可以使用变量，如 `${workspaceFolder}` 和 `${workspaceFolder}/.venv`。使用指向文件夹的路径，允许处理项目的任何人根据其操作系统在 `.venv` 文件夹中创建环境，而无需指定完全依赖于平台的路径。然后可以将 `settings.json` 文件包含在源代码存储库中。注意：在为工作区选择了解释器后对此设置所做的更改将不会被 Python 扩展应用或考虑。Python 扩展不会自动添加或更改此设置。
envFile	`"${workspaceFolder}/` `.env"`	包含环境变量定义的文件的绝对路径。请参阅配置 Python 环境 - 环境变量定义文件。
experiments.enabled	`true`	启用 Python 扩展中的 A/B 实验。如果启用，可能会向您提供建议的增强功能和/或功能。
globalModuleInstallation	`false`	指定是仅使用 `--user` 命令行参数（默认）为当前用户安装包，还是设置为 `true` 时为全局环境中的所有用户安装包。使用虚拟环境时将忽略此设置。有关 `--user` 参数的更多信息，请参阅 pip - 用户安装。
interpreter.infoVisibility	`"onPythonRelated"`	控制何时在状态栏上显示所选解释器信息。默认情况下，仅在编辑器中打开与 Python 相关的文件时才显示。如果您希望它始终显示在状态栏上，可以将其设置为 `"always"`；如果要完全隐藏它，则设置为 `"never"`。
pipenvPath	`"pipenv"`	用于激活的 pipenv 可执行文件的路径。
poetryPath	`"poetry"`	指定 Poetry 依赖管理器可执行文件的位置（如果已安装）。默认值 `"poetry"` 假定可执行文件位于当前路径中。当 Poetry 可用且工作区文件夹中存在 `poetry.lock` 文件时，Python 扩展会使用此设置来安装包。
REPL.enableREPLSmartSend	`true`	指定 `Shift+Enter` 是否利用智能发送。智能发送会查看光标所在位置的代码，将最小的可运行代码块发送到 Python REPL，然后将光标置于下一行代码上。
terminal.activateEnvInCurrentTerminal	`false`	指定在 Python 扩展激活时，是否激活当前打开的终端，使用所选的虚拟环境。
terminal.activateEnvironment	`true`	指示当创建新终端时，是否自动激活使用 Python: Select Interpreter 命令选择的环境。例如，当此设置为 `true` 并且您选择了一个虚拟环境时，扩展会在创建新终端时自动运行环境的激活命令（macOS/Linux 上为 `source env/bin/activate`；Windows 上为 `env\scripts\activate`）。
terminal.executeInFileDir	`false`	指示是应在文件的目录中运行文件，而不是在当前文件夹中运行文件。
terminal.focusAfterLaunch	`false`	启动 Python 终端时是否将光标焦点切换到终端。
terminal.launchArgs	`[]`	当您使用 Python: Run Python File in Terminal 等命令运行文件时，提供给 Python 解释器的启动参数。在 `launchArgs` 列表中，每个项都是一个由空格分隔的顶级命令行元素（包含空格的带引号的值是一个顶级元素，因此是列表中的一项）。例如，对于参数 `--a --b --c {"value1" : 1, "value2" : 2}`，列表项应为 `["--a", "--b", "--c", "{\"value1\" : 1, \"value2\" : 2}\""]`。请注意，VS Code 会忽略此设置，因为在调试时它会改用 `launch.json` 中所选调试配置的参数。
terminal.useEnvFile	`false`	控制是否将来自 env 文件和 python.envFile 设置的环境变量注入到终端中。
venvFolders	`[]`	创建虚拟环境的文件夹的路径。根据使用的虚拟化工具，它可以是项目本身：`${workspaceFolder}`，或者并排放置所有虚拟环境的单独文件夹：`.\envs`, `~/.virtualenvs`，依此类推。

调试器设置

常规调试

设置 (python.debugpy.)	默认值	描述	另请参阅
debugJustMyCode	`true`	指定调试器是否只单步执行用户编写的代码。禁用后，您可以单步执行库代码。	调试

测试设置

常规测试

设置 (python.testing.)	默认值	描述	另请参阅
autoTestDiscoverOnSaveEnabled	`true`	指定在保存测试文件时是启用还是禁用自动运行测试发现。	测试
cwd	null	指定测试的可选工作目录。	测试
debugPort	`3000`	用于调试 unittest 测试的端口号。	测试
promptToConfigure	`true`	指定当发现潜在测试时，VS Code 是否提示配置测试框架。	测试

unittest 框架

设置 (python.testing.)	默认值	描述	另请参阅
unittestArgs	`["-v", "-s", ".", "-p", "test.py"]`	传递给 unittest 的参数，其中由空格分隔的每个顶级元素是列表中的一个单独项。	测试
unittestEnabled	`false`	指定是否为测试启用了 unittest。	测试

pytest 框架

设置 (python.testing.)	默认值	描述	另请参阅
pytestArgs	`[]`	传递给 pytest 的参数，其中由空格分隔的每个顶级元素是列表中的一个单独项。使用 pytest-cov 调试测试时，请在这些参数中包含 `--no-cov`。	测试
pytestEnabled	`false`	指定是否为测试启用了 pytest。	测试
pytestPath	`"pytest"`	pytest 的路径。如果 pytest 位于当前环境之外，请使用完整路径。	测试

代码分析设置

IntelliSense 引擎设置

注意：如果您从未更改过语言服务器设置，则通过“默认”设置值，您的语言服务器设置为 Pylance。

设置 (python.)	默认值	描述
languageServer	默认值	定义语言服务器的类型（Default、Pylance、Jedi 和 None）。

Python 语言服务器设置

Pylance 语言服务器

当 python.languageServer 设置为 Pylance 或 Default 时，语言服务器设置适用。如果语言服务器出现问题，请参阅语言服务器存储库中的故障排除。

设置
(python.analysis.) 默认值描述

aiCodeActions

true

是否启用特定的 AI 辅助代码操作。需要启用 GitHub Copilot Chat 扩展。
可接受的值是一个对象，其中代码操作为键，布尔值为值。
可用于作为键的代码操作

implementAbstractClasses：启用代码操作以实现从抽象类继承的类的方法，使用来自 GitHub Copilot 的 AI 建议来填充方法体。

用法示例：{"implementAbstractClasses": true}

autoFormatStrings false 在字符串内键入 "{" 时，是否自动在其前面加上 "f"。

autoImportCompletions false 控制自动完成中自动导入的提供。可用值为 true 和 false。

autoIndent true 在键入 Python 代码时，是否根据语言语义自动调整缩进。
可接受的值为 true 或 false。

autoSearchPaths true 指示是根据一些预定义名称（如 src）自动添加搜索路径。可用值为 true 和 false。

completeFunctionParens false 向函数补全项添加括号。可接受的值为 true 和 false。

diagnosticMode openFilesOnly 指定语言服务器分析哪些代码文件以查找问题。
可用值为 workspace 和 openFilesOnly。

diagnosticSeverityOverrides {} 允许用户覆盖单个诊断的严重性级别。
对于每条规则，可用的严重性级别为 error（红色波浪线）、warning（黄色波浪线）、information（蓝色波浪线）和 none（规则禁用）。
有关用于诊断严重性规则的键的信息，请参阅下文的诊断严重性规则部分。

enableEditableInstalls false 通过解析根据 PEP 660 定义的可编辑模式（pip install -e .）安装的包的导入路径来启用改进的 IntelliSense 支持。

exclude [] 不应包含在分析中的目录或文件的路径。
这些会覆盖 python.analysis.include 设置下列出的目录，允许排除特定的子目录。
请注意，如果未在排除列表中源文件引用/导入了此 exclude 设置中列出的文件，这些文件仍可能包含在分析中。
路径可以包含通配符，例如 **（目录或多个目录级别）、*（零个或多个字符的序列）或 ?（单个字符）。
如果未指定排除路径，Pylance 会自动排除以下内容：**/node_modules、**/\_\_pycache\_\_、.git 和任何虚拟环境目录。

extraPaths [] 指定用于导入解析的额外搜索路径。
如果存在多个路径，则接受以逗号分隔的路径字符串。例如：["path 1","path 2"]。

importFormat absolute 定义自动导入模块时的默认格式。可接受的值为 absolute 或 relative。

include [] 应包含在分析中的目录或文件的路径。
如果未指定任何路径，Pylance 默认为包含工作区根目录的目录。
路径可以包含通配符，例如 **（目录或多个目录级别）、*（零个或多个字符的序列）或 ?（单个字符）。

fixAll

[]

运行 Fix All 命令或 source.fixAll 代码操作时要运行的代码操作列表。
此列表中的可接受值

source.unusedImports：删除打开文件中所有未使用的导入
source.convertImportFormat：根据 python.analysis.importFormat 设置转换导入

includeAliasesFromUserFiles false 是否在自动导入建议和添加导入快速修复中包含来自用户文件的别名符号。禁用时，Pylance 将提供来自符号定义位置的导入建议。启用时，它还会提供来自符号导入（即别名化）文件的导入建议。可用值为 true 和 false。

ignore [] 应抑制其诊断输出（错误和警告）的目录或文件的路径，即使它们是已包含的文件或已包含文件的传递闭包内的文件。
路径可以包含通配符，例如 **（目录或多个目录级别）、*（零个或多个字符的序列）或 ?（单个字符）。
如果未提供值，则使用 python.linting.ignorePatterns（如果设置了）的值。

indexing true 用于指定 Pylance 在启动时是索引用户文件还是已安装的第三方库，以在自动导入、快速修复、自动完成等功能中提供更完整的符号集。
可接受的值为 true 或 false。
如果设置为 true，默认情况下 Pylance 会索引已安装包的顶级符号（即 package/__init__.py 下 __all__ 中的符号），以及多达 2000 个用户文件中的所有符号。
如果设置为 false，Pylance 只会显示先前在编辑器中打开或加载的文件中已引用或使用的符号。

inlayHints.callArgumentNames off 控制调用参数名称的尾随提示的显示。
可用值为 off、partial 和 all。
当设置为 off 时，不显示任何尾随提示。当设置为 partial 时，对仅位置参数和仅关键字参数禁用提示。当设置为 all 时，对所有参数显示提示。

inlayHints.functionReturnTypes false 是否显示函数返回类型的尾随提示。可接受的值为 true 或 false。

inlayHints.pytestParameters false 是否显示 pytest fixture 参数类型的尾随提示。可接受的值为 true 或 false。

inlayHints.variableTypes false 是否显示变量类型的尾随提示。可接受的值为 true 或 false。

languageServerMode

default

提供预定义配置，以根据开发需求优化 Pylance 的性能。
可用值为 default 和 light。
当设置为 default 时，语言服务器为大多数机器提供足够的功能，而不会使系统过载。
当设置为 light 时，它启用轻量级、内存高效的设置。此模式禁用各种功能，使 Pylance 的功能更像一个简化的文本编辑器，这对于那些不需要全部 IntelliSense 功能且偏爱 Pylance 尽可能节省资源的人来说是理想的选择。
每个模式都会覆盖默认设置值，如下所示

设置	`light` 模式	`default` 模式
python.analysis.exclude	["**"]	[]
python.analysis.useLibraryCodeForTypes	false	true
python.analysis.enablePytestSupport	false	true
python.analysis.indexing	false	true

logLevel Error 指定语言服务器执行日志记录的级别。
按信息量递增的顺序，可能的日志记录级别为 Error、Warning、Information 和 Trace。

nodeArguments "--max-old-space-size=8192" 将自定义参数直接传递给由 python.analysis.nodeExecutable 定义的自定义 Node.js 可执行文件。这可用于分配更多内存或配置 Node.js 行为。
接受 Node.js 支持的参数列表。每个 "arg=value" 应在列表中以逗号分隔。
用法示例："python.analysis.nodeArguments": ["--max-old-space-size=8192"]

nodeExecutable "" 指定要使用的 Node.js 可执行文件，这允许 Pylance 分配更多内存。
可接受的值是带有可执行文件路径的字符串、空字符串或 "auto"。
当设置为空字符串时，Pylance 将使用 VS Code 的 node 可执行文件。当设置为 "auto" 时，它会自动下载 Node.js。

packageIndexDepths [] 用于覆盖按包基础索引已安装包下多少级别。
默认情况下，仅索引顶级模块（深度 = 1）。
要索引子模块，请为要索引的每个子模块级别增加深度 1。
可接受的值是对象的元组，例如 {"name": "package name (str)", "depth": "depth to scan (int)", "includeAllSymbols": "whether to include all symbols (bool)"}。
如果将 includeAllSymbols 设置为 false，则只包含每个包的 __all__ 中的符号。当它设置为 true 时，Pylance 将索引文件中所有模块/顶级符号声明。
用法示例：[{"name": "sklearn", "depth": 2, "includeAllSymbols": true}, {"name": "matplotlib", "depth": 3, "includeAllSymbols": false}]

stubPath ./typings 指定包含自定义类型存根的目录的路径。每个包的类型存根文件应位于其自己的子目录中。

typeCheckingMode off 指定执行的类型检查分析级别。
可用值为 off、basic 和 strict。
设置为 off 时，不进行任何类型检查分析；会产生未解析的导入/变量诊断。
设置为 basic 时，使用非类型检查相关的规则（off 中的所有规则）以及基本的类型检查规则。
设置为 strict 时，使用最高严重性错误的所有类型检查规则（包括 off 和 basic 类别中的所有规则）。

useLibraryCodeForTypes true 当找不到类型存根时，解析包的源代码。可用值为 true 和 false。

userFileIndexingLimit 2000 设置 Pylance 在工作区中索引的用户文件数的上限。设置为 -1 时，Pylance 将索引所有文件。
请注意，索引文件是一项性能密集型任务。

诊断严重性规则

本节详细介绍了使用 python.analysis.diagnosticSeverityOverrides 设置可以自定义的所有规则，如以下示例所示。

{
  "python.analysis.diagnosticSeverityOverrides": {
    "reportUnboundVariable": "information",
    "reportImplicitStringConcatenation": "warning"
  }
}

值	描述
reportAssertAlwaysTrue	有关“assert”语句的诊断，该语句可能始终为真。这可能表明编程错误。
reportCallInDefaultInitializer	有关在默认值初始化表达式中调用函数的诊断。此类调用可能会掩盖在模块初始化时执行的昂贵操作。
reportConstantRedefinition	有关尝试重新定义名称全部大写并带有下划线和数字的变量的诊断。
reportDuplicateImport	有关导入的符号或模块被导入多次的诊断。
reportFunctionMemberAccess	有关对函数的成员访问的诊断。
reportGeneralTypeIssues	有关一般类型不一致、不受支持的操作、参数/形参不匹配等的诊断。这涵盖了其他规则未涵盖的所有基本类型检查规则。它不包括语法错误。
reportImportCycles	有关循环导入链的诊断。这些在 Python 中不是错误，但它们会减慢类型分析的速度，并且通常暗示着架构分层问题。通常应避免使用它们。
reportImplicitStringConcatenation	有关两个或多个字符串文字紧随其后，表示隐式连接的诊断。这被认为是一种不良做法，并且通常会掩盖诸如缺少逗号之类的错误。
reportIncompatibleMethodOverride	有关覆盖基类中同名方法的声明，但方式不兼容（参数数量错误、参数类型不兼容或返回类型不兼容）的方法的诊断。
reportIncompatibleVariableOverride	有关覆盖基类中同名符号的类变量声明，但类型与基类符号类型不兼容的诊断。
reportInvalidStringEscapeSequence	有关在字符串文字中使用无效转义序列的诊断。Python 规范指出，此类序列将在未来版本中生成语法错误。
reportInvalidStubStatement	有关不应出现在存根文件中的语句的诊断。
reportInvalidTypeVarUse	有关在函数签名中不正确使用类型变量的诊断。
reportMissingImports	有关没有对应导入的 python 文件或类型存根文件的导入的诊断。
reportMissingModuleSource	有关没有对应源文件的导入的诊断。当找到类型存根但未找到模块源文件时会发生这种情况，这表明代码在使用此执行环境时可能会在运行时失败。类型检查将使用类型存根完成。
reportMissingTypeArgument	有关在使用泛型类时未提供显式或隐式类型参数的诊断。
reportMissingTypeStubs	有关没有对应类型存根文件（Typeshed 文件或自定义类型存根）的导入的诊断。类型检查器需要类型存根才能最好地完成分析工作。
reportOptionalCall	有关尝试调用具有 Optional 类型的变量的诊断。
reportOptionalContextManager	有关尝试将 Optional 类型用作上下文管理器的诊断（作为 with 语句的参数）。
reportOptionalIterable	有关尝试将 Optional 类型用作可迭代值的诊断（例如，在 for 语句中）。
reportOptionalMemberAccess	有关尝试访问具有 Optional 类型的变量的成员的诊断。
reportOptionalOperand	有关尝试将 Optional 类型用作二元或一元运算符（如 '+'、'=='、'or'、'not'）的操作数的诊断。
reportOptionalSubscript	有关尝试对具有 Optional 类型的变量进行下标（索引）的诊断。
reportPrivateUsage	有关不正确使用私有或受保护变量或函数的诊断。受保护的类成员以下划线 `_` 开头，只能被子类访问。私有类成员以下双下划线开头但不以下双下划线结尾，只能在声明类内访问。在类外部声明的变量和函数如果其名称以下划线或双下划线开头，则被视为私有，并且不能在声明模块外部访问。
reportPropertyTypeMismatch	有关属性的诊断，其中传递给 setter 的值的类型不可分配给 getter 返回的值。此类不匹配会违反属性的预期用途，属性旨在像变量一样工作。
reportSelfClsParameterName	有关实例方法中缺少或命名不正确的“self”参数以及类方法中“cls”参数的诊断。元类（从“type”派生的类）中的实例方法允许使用“cls”作为实例方法。
reportUndefinedVariable	有关未定义变量的诊断。
reportUnboundVariable	有关未绑定和可能未绑定变量的诊断。
reportUnknownArgumentType	有关类型未知的函数或方法的调用参数的诊断。
reportUnknownLambdaType	有关类型未知的 lambda 的输入或返回参数的诊断。
reportUnknownMemberType	有关类型未知的类或实例变量的诊断。
reportUnknownParameterType	有关类型未知的函数或方法的输入或返回参数的诊断。
reportUnknownVariableType	有关类型未知的变量的诊断。
reportUnnecessaryCast	有关静态确定不必要的“cast”调用的诊断。此类调用有时表明编程错误。
reportUnnecessaryIsInstance	有关 `isinstance` 或 `issubclass` 调用结果在静态上确定为始终为真或始终为假的诊断。此类调用通常表明编程错误。
reportUnusedCallResult	有关未被消耗且不为 None 的调用表达式结果的诊断。
reportUnusedClass	有关名称为私有（以下划线开头）但未被访问的类的诊断。
reportUnusedCoroutine	有关返回协程且其结果未被消耗的调用表达式的诊断。
reportUnusedFunction	有关名称为私有（以下划线开头）但未被访问的函数或方法的诊断。
reportUnusedImport	有关在文件中未引用的导入符号的诊断。
reportUnusedVariable	有关未被访问的变量的诊断。
reportUnsupportedDunderAll	有关对 `__all__` 执行不受支持操作的诊断。
reportWildcardImportFromLibrary	有关从外部库进行通配符导入的诊断。

自动完成设置

设置 (python.autoComplete.)	默认值	描述	另请参阅
extraPaths	`[]`	指定要为其加载自动完成数据的附加包的位置。	编辑

预定义变量

Python 扩展设置支持预定义变量。与常规 VS Code 设置类似，变量使用 ${variableName} 语法。具体来说，该扩展支持以下变量

${cwd} - 任务运行器在启动时的当前工作目录
${workspaceFolder} - VS Code 中打开的文件夹的路径
${workspaceRootFolderName} - VS Code 中打开的文件夹的名称，不带任何斜杠 (/)
${workspaceFolderBasename} - VS Code 中打开的文件夹的名称，不带任何斜杠 (/)
${file} - 当前打开的文件
${relativeFile} - 相对于 workspaceFolder 的当前打开的文件
${relativeFileDirname} - 相对于 workspaceFolder 的当前打开的文件的目录名
${fileBasename} - 当前打开的文件名
${fileBasenameNoExtension} - 当前打开的文件名（不带文件扩展名）
${fileDirname} - 当前打开的文件的目录名
${fileExtname} - 当前打开的文件的扩展名
${lineNumber} - 活动文件中当前选定的行号
${selectedText} - 活动文件中当前选定的文本
${execPath} - 正在运行的 VS Code 可执行文件的路径

有关预定义变量和用法示例的更多信息，请参阅常规 VS Code 文档中的变量参考。

后续步骤

Python 环境 - 控制用于编辑和调试的 Python 解释器。
编辑代码 - 了解 Python 的自动完成、IntelliSense、格式设置和重构。
Linting - 启用、配置和应用各种 Python linter。
调试 - 了解如何在本地和远程调试 Python。
测试 - 配置测试环境以及发现、运行和调试测试。

3/6/2023