编辑

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` 是否利用智能发送（Smart Send）。智能发送会查看光标所在位置的代码，将最小的可运行代码块发送到 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: 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` 中所选调试配置中的参数。
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 引擎设置

注意：如果您从未更改过语言服务器设置，则您的语言服务器通过“Default”设置值设置为 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 通过解析以可编辑模式（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

[]

运行 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 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 指定语言服务器执行的日志记录级别。
可能的日志记录级别，按提供的信息量递增，分别为 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	针对类型未知的 lambda 的输入或返回参数的诊断。
reportUnknownMemberType	针对类型未知的类或实例变量的诊断。
reportUnknownParameterType	针对类型未知的函数或方法的输入或返回参数的诊断。
reportUnknownVariableType	针对类型未知的变量的诊断。
reportUnnecessaryCast	针对静态确定为不必要的 'cast' 调用的诊断。此类调用有时表示编程错误。
reportUnnecessaryIsInstance	针对 'isinstance' 或 'issubclass' 调用的诊断，其中结果静态确定为始终为真或始终为假。此类调用通常表示编程错误。
reportUnusedCallResult	针对其结果未被使用且不为 None 的调用表达式的诊断。
reportUnusedClass	针对具有私有名称（以下划线开头）且未被访问的类的诊断。
reportUnusedCoroutine	针对返回 Coroutine 且其结果未被使用的调用表达式的诊断。
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