现已发布！了解 11 月份的新功能和修复。

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 扩展不会自动添加或更改此设置。
interpreter.infoVisibility "onPythonRelated" 控制何时在状态栏上显示所选的解释器信息。
默认情况下，它仅在编辑器中打开与 Python 相关的文件时显示。
如果您希望它始终显示在状态栏上，则可以将其设置为 "always"，或者设置为 "never" 以完全隐藏它。
pipenvPath "pipenv" 用于激活的 pipenv 可执行文件的路径。
venvFolders [] 创建虚拟环境的文件夹的路径。
根据所使用的虚拟化工具，它可以是项目本身：${workspaceFolder}，或所有虚拟环境并排的单独文件夹：.\envs、~/.virtualenvs 等。
envFile "${workspaceFolder}/
.env"		 包含环境变量定义的文件的绝对路径。
请参阅配置 Python 环境 - 环境变量定义文件。
globalModuleInstallation false 指定是仅使用 --user 命令行参数（默认值）为当前用户安装包，还是为全局环境中的所有用户安装包（设置为 true 时）。使用虚拟环境时将被忽略。
有关 --user 参数的更多信息，请参阅pip - 用户安装。
poetryPath "poetry" 指定Poetry 依赖项管理器可执行文件的位置（如果已安装）。默认值 "poetry" 假定可执行文件在当前路径中。
当 Poetry 可用且工作区文件夹中存在 poetry.lock 文件时，Python 扩展使用此设置来安装包。
terminal.launchArgs [] 使用诸如“Python：在终端中运行 Python 文件”之类的命令运行文件时，传递给 Python 解释器的启动参数。
在 launchArgs 列表中，每个项都是一个顶级命令行元素，由空格分隔（包含空格的带引号的值是一个顶级元素，因此是列表中的一项）。
例如，对于参数 --a --b --c {"value1" : 1, "value2" : 2}，列表项应为 ["--a", "--b", "--c", "{\"value1\" : 1, \"value2\" : 2}\""]。
请注意，VS Code 在调试时会忽略此设置，因为它改为使用 launch.json 中所选调试配置的参数。
terminal.executeInFileDir false 指示是在文件目录中运行文件，还是在当前文件夹中运行文件。
terminal.activateEnvironment true 指示是否在创建新终端时自动激活您使用“Python：选择解释器”命令选择的环境。
例如，当此设置是 true 并且您选择虚拟环境时，该扩展程序会在创建新终端时自动运行环境的激活命令（在 macOS/Linux 上为 source env/bin/activate；在 Windows 上为 env\scripts\activate）。
terminal.activateEnvInCurrentTerminal false 指定在使用所选的虚拟环境激活 Python 扩展时，是否激活当前打开的终端。
terminal.focusAfterLaunch false 在启动 Python 终端时是否将光标焦点切换到终端。
logging.level error 指定扩展程序执行的日志记录级别。
可能的日志记录级别（按提供的信息级别递增）为 off、error、warn、info 和 debug。
设置为 off 时（不推荐），仍将显示基本信息，例如启动信息和 Python 扩展运行的命令。
在 error 级别，将显示基本信息和错误。
在 warn 级别，将显示基本信息、错误和警告信息。在 info 级别，将显示基本信息、错误、警告和其他信息，例如方法执行时间和返回值。此时，debug 级别不显示其他信息。
experiments.enabled true 启用Python 扩展中的 A/B 实验。如果启用，可能会为您提供建议的增强功能和/或功能。

代码分析设置

IntelliSense 引擎设置

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

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

Python 语言服务器设置

Pylance 语言服务器

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

设置
(python.analysis.)		 默认值 描述
typeCheckingMode off 指定要执行的类型检查分析的级别。
可用值为 off、basic 和 strict。
设置为 off 时，不进行类型检查分析；将生成未解析的导入/变量诊断。
设置为 basic 时，将使用非类型检查相关规则（off 中的所有规则）以及基本类型检查规则。
当设置为 strict 时，将使用最高错误严重级别的所有类型检查规则（包括 off 和 basic 类别中的所有规则）。
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
diagnosticMode openFilesOnly 指定语言服务器分析哪些代码文件以查找问题。
可用值为 workspace 和 openFilesOnly。
include [] 应该包含在分析中的目录或文件的路径。
如果未指定路径，Pylance 默认使用包含工作区根目录的目录。
路径可以包含通配符，例如 ** （一个目录或多个级别的目录）、* （零个或多个字符的序列）或 ? （单个字符）。
exclude [] 不应包含在分析中的目录或文件的路径。
这些路径会覆盖 python.analysis.include 设置下列出的目录，允许排除特定的子目录。
请注意，如果此 exclude 设置中列出的文件被未在排除列表中的源文件引用/导入，则这些文件仍可能包含在分析中。
路径可以包含通配符，例如 ** （一个目录或多个级别的目录）、* （零个或多个字符的序列）或 ? （单个字符）。
如果未指定排除路径，Pylance 会自动排除以下内容： **/node_modules、**/\_\_pycache\_\_、.git 和任何虚拟环境目录。
ignore [] 应该禁止其诊断输出（错误和警告）的目录或文件的路径，即使它们是包含的文件或包含文件的传递闭包中的文件。
路径可以包含通配符，例如 ** （一个目录或多个级别的目录）、* （零个或多个字符的序列）或 ? （单个字符）。
如果未提供值，则将使用 python.linting.ignorePatterns 的值（如果已设置）。
stubPath ./typings 指定包含自定义类型存根的目录的路径。每个包的类型存根文件应位于其自己的子目录中。
autoSearchPaths true 指示是否基于一些预定义的名称（如 src）自动添加搜索路径。可用值为 true 和 false。
extraPaths [] 指定用于导入解析的额外搜索路径。
接受指定为字符串的路径，如果有多个路径，则用逗号分隔。例如：["path 1","path 2"]。
indexing true 用于指定 Pylance 是否应在启动时索引用户文件以及已安装的第三方库，以便在自动导入、快速修复、自动完成等功能中提供更完整的符号集。
接受的值为 true 或 false。
当设置为 true 时，默认情况下，Pylance 会索引已安装包的顶级符号（即 package/__init__.py 下的 __all__ 中的符号）以及最多 2000 个用户文件的所有符号。
当设置为 false 时，Pylance 只会显示之前在编辑器中打开或加载的文件中已引用或使用的符号。
packageIndexDepths [] 用于覆盖每个包下要索引的已安装包的级别数。
默认情况下，只索引顶层模块（深度 = 1）。
要索引子模块，请为你想要索引的每个子模块级别将深度增加 1。
接受的值是类似 {"name": "包名称 (str)", "depth": "扫描深度 (int)", "includeAllSymbols": "是否包含所有符号 (bool)"} 的对象元组。
如果 includeAllSymbols 设置为 false，则仅包含每个包的 __all__ 中的符号。当它设置为 true 时，Pylance 将索引文件中的每个模块/顶级符号声明。
使用示例：[{"name": "sklearn", "depth": 2, "includeAllSymbols": true}, {"name": "matplotlib", "depth": 3, "includeAllSymbols": false}]
userFileIndexingLimit 2000 设置 Pylance 在工作区中要索引的最大用户文件数。当设置为 -1 时，Pylance 将索引所有文件。
请注意，索引文件是一项性能密集型任务。
autoFormatStrings false 当在字符串中键入 "{" 时，是否自动在其前面加上 "f"。
completeFunctionParens false 将括号添加到函数补全中。接受的值为 true 和 false。
useLibraryCodeForTypes true 当未找到类型存根时，解析包的源代码。可用值为 true 和 false。
includeAliasesFromUserFiles false 是否在自动导入建议和添加导入快速修复中包含用户文件中的别名符号。禁用后，Pylance 将从定义符号的位置提供导入建议。启用后，它还将从导入符号的文件（即别名）提供导入建议。可用值为 true 和 false。
autoImportCompletions false 控制在补全中提供自动导入。可用值为 true 和 false。
importFormat absolute 定义自动导入模块时的默认格式。接受的值为 absolute 或 relative。
aiCodeActions true 是否启用特定的 AI 辅助代码操作。需要启用 GitHub Copilot Chat 扩展。
接受的值是一个对象，其中代码操作作为键，布尔值作为值。
可用作键的代码操作
  • implementAbstractClasses：启用代码操作以实现从抽象类继承的类的方法，使用来自 GitHub Copilot 的 AI 建议来填充方法主体。
使用示例：{"implementAbstractClasses": true}
inlayHints.variableTypes false 是否显示变量类型的内嵌提示。接受的值为 true 或 false。
inlayHints.functionReturnTypes false 是否显示函数返回类型的内嵌提示。接受的值为 true 或 false。
inlayHints.callArgumentNames false 是否显示调用参数名称的内嵌提示。接受的值为 true 或 false。
inlayHints.pytestParameters false 是否显示 pytest fixture 参数类型的内嵌提示。接受的值为 true 或 false。
diagnosticSeverityOverrides {} 允许用户覆盖各个诊断的严重级别。
对于每个规则，可用的严重级别为 error（红色波浪线）、warning（黄色波浪线）、information（蓝色波浪线）和 none（禁用规则）。
有关用于诊断严重性规则的键的信息，请参见下面的 诊断严重性规则 部分。
fixAll [] 运行 全部修复 命令或 source.fixAll 代码操作时要运行的代码操作列表。
此列表中接受的值
  • source.unusedImports：删除打开的文件中所有未使用的导入
  • source.convertImportFormat：根据 python.analysis.importFormat 设置转换导入
logLevel Error 指定语言服务器要执行的日志记录级别。
可能的日志记录级别（按提供的信息量递增排序）为 Error、Warning、Information 和 Trace。
autoIndent true 键入 Python 代码时，是否根据语言语义自动调整缩进。
接受的值为 true 或 false。

诊断严重性规则

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

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

自动完成设置

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

测试设置

常规测试

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

unittest 框架

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

pytest 框架

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

预定义变量

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、格式化和重构。
  • 代码检查 - 启用、配置和应用各种 Python 代码检查器。
  • 调试 - 学习在本地和远程调试 Python。
  • 测试 - 配置测试环境并发现、运行和调试测试。
3/6/2023