现已发布！阅读 10 月份的新功能和修复。

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" 假设可执行文件位于当前路径中。
Python 扩展使用此设置在 Poetry 可用且工作区文件夹中存在 poetry.lock 文件时安装软件包。
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 并且您选择了虚拟环境时，扩展会自动运行环境的 activate 命令来创建新终端（在 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": "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}]
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 是否启用特定的人工智能辅助代码操作。需要启用GitHub Copilot Chat 扩展。
接受的值是一个以代码操作为键，以布尔值为值的 对象。
可用代码操作（用作键）
  • implementAbstractClasses：启用代码操作以使用来自 GitHub Copilot 的人工智能建议填充方法主体来实现从抽象类继承的类的 方法。
用法示例：{"implementAbstractClasses": true}
inlayHints.variableTypes false 是否为变量类型显示内嵌提示。接受的值为 true 或 false。
inlayHints.functionReturnTypes false 是否为函数返回类型显示内嵌提示。接受的值为 true 或 false。
inlayHints.callArgumentNames false 是否为调用参数名称显示内嵌提示。接受的值为 true 或 false。
inlayHints.pytestParameters false 是否为 pytest 夹具参数类型显示内嵌提示。接受的值为 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"
  }
}
Value 描述
reportGeneralTypeIssues 有关一般类型不一致、不支持的操作、参数/参数不匹配等的诊断信息。这涵盖了所有未涵盖在其他规则中的基本类型检查规则。它不包括语法错误。
reportPropertyTypeMismatch 有关属性的诊断信息，这些属性的值传递给设置器的类型无法分配给获取器返回的值。此类不匹配违反了属性的预期用途，属性旨在像变量一样起作用。
reportFunctionMemberAccess 有关函数上的成员访问的诊断信息。
reportMissingImports 有关没有相应导入的 python 文件或类型存根文件的导入的诊断信息。
reportMissingModuleSource 有关没有相应源文件的导入的诊断信息。当找到类型存根但找不到模块源文件时，会发生这种情况，表明在使用此执行环境时代码可能会在运行时失败。类型检查将使用类型存根完成。
reportMissingTypeStubs 有关没有相应类型存根文件（typeshed 文件或自定义类型存根）的导入的诊断信息。类型检查器需要类型存根才能尽其所能进行分析。
reportImportCycles 有关循环导入链的诊断信息。这些在 Python 中不是错误，但它们确实会减慢类型分析速度，并且通常暗示着架构分层问题。一般来说，应该避免它们。
reportUnusedImport 有关未在该文件中引用的导入符号的诊断信息。
reportUnusedClass 有关未访问的私有名称（以下划线开头）的类的诊断信息。
reportUnusedFunction 有关未访问的私有名称（以下划线开头）的函数或方法的诊断信息。
reportUnusedVariable 有关未访问的变量的诊断信息。
reportDuplicateImport 有关导入多次的导入符号或模块的诊断信息。
reportWildcardImportFromLibrary 有关从外部库进行通配符导入的诊断信息。
reportOptionalSubscript 有关尝试用 Optional 类型对变量进行下标（索引）的诊断信息。
reportOptionalMemberAccess 有关尝试访问具有 Optional 类型的变量的成员的诊断信息。
reportOptionalCall 有关尝试调用具有 Optional 类型的变量的诊断信息。
reportOptionalIterable 有关尝试将 Optional 类型用作可迭代值（例如，在 for 语句中）的诊断信息。
reportOptionalContextManager 尝试使用 Optional 类型作为上下文管理器（作为 with 语句的参数）的诊断信息。
reportOptionalOperand 尝试使用 Optional 类型作为二元或一元运算符（如 '+', '==', 'or', 'not'）的操作数的诊断信息。
reportUntypedFunctionDecorator 没有类型注释的函数装饰器的诊断信息。这些会模糊函数类型，从而影响许多类型分析功能。
reportUntypedClassDecorator 没有类型注释的类装饰器的诊断信息。这些会模糊类类型，从而影响许多类型分析功能。
reportUntypedBaseClass 无法静态确定类型的基类的诊断信息。这些会模糊类类型，从而影响许多类型分析功能。
reportUntypedNamedTuple 使用“namedtuple”而不是“NamedTuple”时的诊断信息。前者不包含类型信息，而后者则包含。
reportPrivateUsage 私有或受保护变量或函数使用不当的诊断信息。受保护的类成员以单个下划线 '_' 开头，只能被子类访问。私有类成员以双下划线开头，但不会以双下划线结尾，只能在声明类中访问。在类之外声明的变量和函数如果其名称以单个或双下划线开头，则被视为私有，并且无法在声明模块之外访问。
reportConstantRedefinition 尝试重新定义名称为全大写字母、下划线和数字的变量的诊断信息。
reportIncompatibleMethodOverride 以不兼容的方式（参数数量错误、参数类型不兼容或返回值类型不兼容）覆盖基类中同名方法的方法的诊断信息。
reportIncompatibleVariableOverride 覆盖基类中同名符号的类变量声明，其类型与基类符号类型不兼容的诊断信息。
reportInvalidStringEscapeSequence 字符串字面量中使用无效转义序列的诊断信息。Python 规范指出，此类序列将在未来的版本中生成语法错误。
reportUnknownParameterType 具有未知类型的函数或方法的输入或返回值参数的诊断信息。
reportUnknownArgumentType 具有未知类型的函数或方法的调用参数的诊断信息。
reportUnknownLambdaType 具有未知类型的 lambdas 的输入或返回值参数的诊断信息。
reportUnknownVariableType 具有未知类型的变量的诊断信息。
reportUnknownMemberType 具有未知类型的类或实例变量的诊断信息。
reportMissingTypeArgument 在没有提供显式或隐式类型参数的情况下使用泛型类的诊断信息。
reportInvalidTypeVarUse 在函数签名中不正确使用类型变量的诊断信息。
reportCallInDefaultInitializer 在默认值初始化表达式中进行函数调用的诊断信息。此类调用可能会掩盖在模块初始化时执行的昂贵操作。
reportUnnecessaryIsInstance 结果在静态上确定为始终为真或始终为假的 '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、格式化和重构。
  • Linting - 启用、配置和应用各种 Python linter。
  • 调试 - 学习在本地和远程调试 Python。
  • 测试 - 配置测试环境，并发现、运行和调试测试。
3/6/2023