编辑

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` 且您选择了一个虚拟环境时，该扩展会在创建新终端时自动运行该环境的 activate 命令（在 macOS/Linux 上是 `source env/bin/activate`；在 Windows 上是 `env\scripts\activate`）。
terminal.executeInFileDir	`false`	指示是否在文件的目录中而不是当前文件夹中运行文件。
terminal.focusAfterLaunch	`false`	启动 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` 中选择的调试配置中的参数。
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	默认值	定义语言服务器的类型（默认、Pylance、Jedi 和无）。

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 通过解析以可编辑模式安装的包（pip install -e .）的导入路径，来启用改进的 IntelliSense 支持，如 PEP 660 中所定义。

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

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

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

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

fixAll

[]

运行全部修复命令或 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 false 是否显示调用参数名称的嵌入提示。接受的值为 true 或 false。

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、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": "包名 (str)", "depth": "扫描深度 (int)", "includeAllSymbols": "是否包含所有符号 (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	对具有未知类型的 lambdas 的输入或返回参数的诊断。
reportUnknownMemberType	对具有未知类型的类或实例变量的诊断。
reportUnknownParameterType	对具有未知类型的函数或方法的输入或返回参数的诊断。
reportUnknownVariableType	对具有未知类型的变量的诊断。
reportUnnecessaryCast	对静态确定为不必要的 'cast' 调用的诊断。此类调用有时表示编程错误。
reportUnnecessaryIsInstance	对 'isinstance' 或 'issubclass' 调用的诊断，其中结果被静态确定为总是 true 或总是 false。此类调用通常表示编程错误。
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