VSCode Pylance 扩展的使用和设置说明

VSCode Pylance 扩展

VSCode 中的Pylance扩展，为 Python 语言开发提供了强大的支持，比如，代码的智能提示，补全，诊断和分析。在一般情况下，该扩展会跟随Python扩展一同安装，并将成为Python扩展认定的 Python 语言服务器。

设置 Pylance 扩展

和大部分的 VSCode 扩展一样，Pylance为开发人员提供了设置项，你可以通过编辑工作区.vscode文件夹中的setting.json文件，或在设置面板中编辑相关项，来调整和改变Pylance扩展所实现的某些功能。

设置 Python 类型检查功能

Pylance扩展的设置项python.analysis.typeCheckingMode，可用于设置Pylance的类型检查模式（Type Checking Mode），不同的类型检查模式对应了不同的类型检查规则集（Rule Set），从松散到严格，类型检查模式分为以下几种。

off 模式

off模式是python.analysis.typeCheckingMode设置项的默认值，他表示不对 Python 代码进行类型检查，仅诊断无效的语法，未定义而被读取的内容（变量，函数等），以及未能被解析的导入（比如，导入了无法访问的 Python 模块或包，或导入了不存在的内容）。

basic 模式

basic模式包含off模式中的所有规则，以及基础的类型检查规则，比如，不应该访问未知的类特性，调用方法或函数时应该给出全部的必要参数。

standard 模式

standard模式包含off模式中的所有规则，以及基础和标准的类型检查规则，因此他相对于basic模式更为严格。

strict 模式

strict模式是最严格的类型检查模式，包含off模式中的所有规则，以及所有类型检查规则，比如，报告无法推导出其类型的变量或参数。

{
	// 最严格的模式 strict
	"python.analysis.typeCheckingMode": "strict",
}

pyright/docs/configuration.md at main · microsoft/pyright

{
	// 自定义 Python 类型检查规则的严重性级别
	"python.analysis.diagnosticSeverityOverrides": {
		// 无法被解析的导入
		"reportMissingImports": "warning"
	},
}

设置需要被诊断的 Python 文件

Pylance扩展的设置项python.analysis.diagnosticMode（诊断模式），可用于设置Pylance在什么范围内诊断 Python 代码文件，诊断后得到的问题将显示在问题面板中，该设置项的有效值为以下两种。

openFilesOnly 模式

openFilesOnly模式是python.analysis.diagnosticMode设置项的默认值，他表示Pylance仅诊断已在 VSCode 中打开的 Python 代码文件。

workspace 模式

workspace模式表示Pylance将诊断 VSCode 工作区中的所有 Python 代码文件，以及 VSCode 打开的 Python 代码文件。

{
	// 诊断工作区所有以及打开的 Python 代码文件
	"python.analysis.diagnosticMode": "workspace",
}

{
	// 需要被诊断的文件的路径信息
	"python.analysis.include": [
		// 以 s 和 c 开头的三个字符的文件夹
		"s?c\\",
		// src 文件夹的一级子文件夹
		"src\\*\\",
		// src 文件夹或其任意子文件夹中，以 s.py 结尾的文件或文件夹
		"src\\**\\*s.py"
	],
}

{
	// 不需要诊断的文件的路径信息
	"python.analysis.exclude": [
		// src 文件夹或其任意子文件夹中，以 test.py 结尾的文件或文件夹
		"src\\**\\*test.py"
	],
}

设置忽略诊断结果的 Python 文件

Pylance扩展的设置项python.analysis.ignore是一个包含路径信息的数组（其默认值为[]），如果某个 Python 代码文件路径的开始部分符合该数组的某一项，那么Pylance关于该文件的诊断结果（包括错误和警告）将被忽略（不予展示）。

与python.analysis.include设置项类似，python.analysis.ignore也可以使用相对路径，绝对路径以及路径通配符。

{
	// 忽略诊断结果的文件的路径信息
	"python.analysis.ignore": [
		// src 文件夹中名称包含 test 的一级子文件夹
		"src\\*test*\\"
	],
}

设置 Python 类型存根文件目录

Pylance扩展的设置项python.analysis.stubPath，可用于指定类型存根（Type Stub）文件所在的目录，与python.analysis.include类似，你可以采用相对路径或绝对路径。python.analysis.stubPath的默认值为typings，即 VSCode 工作区根目录下的typings文件夹。

{
	// 指定类型存根文件目录为工作区的 my_typings 文件夹
	"python.analysis.stubPath": "my_typings",
}

Pylance扩展的设置项python.analysis.useLibraryCodeForTypes是一个布尔值，可用于指定当需要分析的 Python 模块没有对应的类型存根文件时，是否分析该模块对应的 Python 代码文件，默认为true，分析对应的代码文件。

{
	// 不分析模块对应的代码文件，当类型存根文件不存在时
	"python.analysis.useLibraryCodeForTypes": false,
}

设置额外 Python 模块路径

Pylance扩展的设置项python.analysis.extraPaths是一个包含额外模块路径信息的数组（其默认值为[]），Pylance可尝试在这些路径中查找并分析 Python 模块对应的代码文件，当他们被导入时。需要指出，额外模块路径不会影响 Python 自身的模块搜索路径。

在路径设置方面，python.analysis.extraPaths与python.analysis.include设置项类似，你可以使用相对路径，绝对路径以及路径通配符。python.analysis.extraPaths中的路径需要指向文件夹或zip压缩文件，指向其他可能会无效。

{
	// 设置额外的 Python 模块路径
	"python.analysis.extraPaths": [
		// 在工作区根目录的 extra.zip 中搜索模块
		"extra.zip"
	],
}

Pylance扩展的设置项python.analysis.autoSearchPaths是一个布尔值，可用于指定是否启用模块自动搜索路径，将python.analysis.autoSearchPaths设置为true（默认值），Pylance可尝试从一些预定义的路径（比如，VSCode 工作区根目录下的src文件夹）中查找并分析 Python 模块对应的代码文件，当他们被导入时。

在效果方面，模块自动搜索路径与额外模块路径是相似的，只不过python.analysis.autoSearchPaths中的路径是预设的，而python.analysis.extraPaths中的路径则由开发人员指定。模块自动搜索路径同样不会影响 Python 自身的模块搜索路径，并可能在运行时提示模块未找到ModuleNotFoundError。

{
	// 禁用 Python 模块自动搜索路径
	"python.analysis.autoSearchPaths": false,
}

设置 Python 索引编制功能

Pylance扩展的设置项python.analysis.indexing，可用于控制是否对用户文件（VSCode 工作区中的 Python 代码文件，其对应的模块应具备有效的完全限定名），Python 第三方包或模块进行索引编制（默认为true，进行索引编制），有效的索引是Pylance实现自动导入模块，添加导入语句等功能的前提。

{
	// 禁用 Python 索引编制功能
	"python.analysis.indexing": false,
}

Pylance扩展的设置项python.analysis.packageIndexDepths是一个包含索引编制方案的数组，不同的 Python 包可以拥有不同的索引编制方案。在默认情况下，Pylance仅为直接位于第三方包目录的包（不包含模块，以及包中的子包或子模块）编制索引。

如果想为包的子包或子模块编制索引，那么需要将对应方案的depth设置项设置为2（默认为1），name设置项设置为包的名称，如果想为子包的子包或子模块编制索引，则需要将depth设置为3，以此类推。如果希望为包或模块的所有特性编制索引，则需要将对应方案的includeAllSymbols设置项设置为true，在一些情况下，includeAllSymbols并不能发挥其作用，Pylance会为所有特性编制索引。

Pylance扩展的设置项python.analysis.persistAllIndices是一个布尔值，可用于设置是否将已经编制的 Python 第三方包和模块的索引，作为json索引文件保存在Pylance扩展安装目录的dist文件夹的.cache子文件夹中，以便下一次使用，默认为true，保存。如果将python.analysis.persistAllIndices设置为false，那么json索引文件不会被使用，即便他已经存在。

Pylance扩展的设置项python.analysis.userFileIndexingLimit，可用于设置进行索引编制的用户文件的最大数量，默认为2000，如果设置为-1，则表示不限制参与索引编制的用户文件的数量。由于索引编制可能会在短时间内进行大量的运算，因此，不建议将其设置为-1。

{
	// 不对工作区中的 Python 代码文件编制索引，除非是打开的文件
	"python.analysis.userFileIndexingLimit": 0,
	// 设置名称为 just_test 的第三方包的索引编制方案
	"python.analysis.packageIndexDepths": [
		{ "name": "just_test", "depth": 3, "includeAllSymbols": true }
	],
}

设置代码补全功能

Pylance扩展的设置项python.analysis.autoImportCompletions，可用于设置是否启用导入语句补全功能，该功能可自动书写import或from…import导入 Python 模块，当你使用了模块特性且并未导入相关模块时，默认为false，不进行导入语句的补全。如果python.analysis.indexing设置项为false，那么Pylance的导入语句补全功能仅针对在 VSCode 中打开过的 Python 代码文件（文件对应的模块应具备有效的完全限定名）。

Pylance扩展的设置项python.analysis.importFormat，可用于设置导入语句补全的格式，其有效值包含以下两种。

absolute 格式

absolute格式是python.analysis.importFormat设置项的默认值，他表示以完全限定名补全导入语句。

relative 格式

relative格式表示尽可能以相对名称的方式补全导入语句，如果无法完成，则采用完全限定名。

Pylance扩展的设置项python.analysis.completeFunctionParens，可用于设置是否启用函数或方法括号的补全功能，该功能可在选择调用的函数或方法后自动书写括号()，默认为false，不进行函数或方法括号的补全。

Pylance扩展的设置项python.analysis.autoFormatStrings，可用于设置是否为字符串补全前缀f，当你在字符串中书写{时（请注意，该功能在某些情况下达不到预期效果）。python.analysis.autoFormatStrings的默认值为false，不进行前缀f的补全。

{
	// 启用导入语句的补全
	"python.analysis.autoImportCompletions": true,
	// 导入语句的补全采用相对名称
	"python.analysis.importFormat": "relative",
	// 启用函数或方法的括号补全
	"python.analysis.completeFunctionParens": true,
	// 启用字符串的 f 前缀补全（可能没有效果）
	"python.analysis.autoFormatStrings": true,
}

设置代码嵌入提示功能

Pylance扩展的设置项python.analysis.inlayHints.variableTypes，可用于设置是否启用变量类型的嵌入提示功能（默认为false，不启用），该功能将嵌入变量类型的描述，当你没有使用:指明变量的类型，并且变量类型需要一个清晰的描述时。比如，a=[1,2]会被嵌入描述，b=1或c=set()则不会。

Pylance扩展的设置项python.analysis.inlayHints.functionReturnTypes，可用于设置是否启用函数或方法返回值的类型嵌入提示功能（默认为false，不启用），该功能将嵌入函数或方法返回值的类型描述，当你没有使用->指明函数或方法返回值的类型时。

Pylance扩展的设置项python.analysis.inlayHints.callArgumentNames，可用于设置是否启用参数名称的嵌入提示功能，该功能会尝试为实参嵌入参数名称，当该实参的名称没有被指明时，以帮助开发人员有效的识别实参的含义。python.analysis.inlayHints.callArgumentNames设置项的有效值包含以下几种。

off

off是python.analysis.inlayHints.callArgumentNames设置项的默认值，他表示禁用参数名称的嵌入提示功能。

partial

partial表示，如果一个实参既是位置参数又是命名参数，则尝试为其嵌入参数名称。

all

all表示尝试为所有实参嵌入参数名称。

Pylance扩展的设置项python.analysis.inlayHints.pytestParameters，可用于设置是否启用针对pytest函数或方法参数类型的嵌入提示功能（默认为false，不启用），该功能会在 Python 的pytest包能够推断出参数的类型，并且参数未使用:指明类型时，尝试嵌入参数类型的描述。需要指出，使用python.analysis.inlayHints.pytestParameters设置项的前提是具备可用的pytest包，并且python.analysis.enablePytestSupport设置项的值为true。

Pylance扩展的设置项python.analysis.enablePytestSupport是一个布尔值，可用于设置是否启用对pytest包的支持，默认为true，启用。

{
	// 启用变量类型的嵌入提示
	"python.analysis.inlayHints.variableTypes": true,
	// 启用函数或方法返回值的类型嵌入提示
	"python.analysis.inlayHints.functionReturnTypes": true,
	// 启用对所有参数的名称嵌入提示
	"python.analysis.inlayHints.callArgumentNames": "all",
	// 启用针对 pytest 函数或方法参数类型的嵌入提示
	"python.analysis.inlayHints.pytestParameters": true,
	// 禁用对 pytest 的支持，这将导致对 pytestParameters 的设置无效
	"python.analysis.enablePytestSupport": false,
}

设置代码导航功能

Pylance扩展的设置项python.analysis.gotoDefinitionInStringLiteral，可用于设置是否启用 Python 字符串的模块导航功能（默认为true，启用），该功能可为字符串中被认为是模块的文字提供导航，比如"sys is here"中的sys，针对sys使用上下文菜单或键盘快捷方式，可跳转至模块sys相关的代码文件或类型存根文件。

{
	// 禁用字符串的模块导航功能
	"python.analysis.gotoDefinitionInStringLiteral": false,
}

设置日志功能

Pylance扩展的设置项python.analysis.logLevel，可用于设置Pylance将哪些内容输出为日志，他拥有以下有效取值。

Error 级别

Error级别表示仅将错误输出为日志。

Warning 级别

Warning级别表示将错误和警告输出为日志。

Information 级别

Information级别是设置项python.analysis.logLevel的默认值，他表示将错误，警告和信息输出为日志。

Trace 级别

Trace级别表示将错误，警告，信息和跟踪输出为日志。

{
	// 设置 Pylance 仅汇报错误
	"python.analysis.logLevel": "Error",
}

设置 Pylance 扩展在修复命令中的行为

Pylance扩展的设置项python.analysis.fixAll是一个字符串数组（其默认值为[]），数组中的每一个项对应一种行为，这些行为决定了Pylance扩展在Fix All命令被执行时的表现，以下是python.analysis.fixAll数组的有效取值。

source.unusedImports 行为

source.unusedImports行为将移除已在 VSCode 打开的 Python 代码文件中的一些导入语句，因为这些语句导入的模块未被使用。

source.convertImportFormat 行为

source.convertImportFormat行为将根据设置项python.analysis.importFormat来转换已在 VSCode 打开的 Python 代码文件中的导入语句。

{
	// 设置在运行 Fix All 命令时的行为
	"python.analysis.fixAll": [
		"source.unusedImports",
		"source.convertImportFormat"
	],
}

设置运行 Pylance 扩展的 Node.js 可执行文件路径

Pylance扩展的设置项python.analysis.nodeExecutable用于指示一个外部 Node.js 可执行文件，Pylance将通过此外部 Node.js 运行，默认值为空字符串。而一般情况下，Pylance使用 VSCode 自身的 Node.js，其内存会受到 VSCode 的限制，如果你希望获得更多内存空间，那么设置python.analysis.nodeExecutable设置项是可行的。

python.analysis.nodeExecutable设置项的取值不限于 Node.js 可执行文件的路径，他还可以是某个指向 Node.js 的别名，但无论如何，你应该确保该取值能够在命令行中正确启动 Node.js。

{
	// 指向外部 Node.js（无法在 VSCode 工作区设置中使用）
	"python.analysis.nodeExecutable": "node",
}

自定义 Python 语法高亮样式

通过editor.semanticTokenColorCustomizations设置项，你可以针对 VSCode 的某个主题或所有主题，自定义Pylance扩展的 Python 语法高亮样式，当然，主要是指颜色。以下是Pylance扩展所支持的，可用于自定义语法高亮样式的具体语义类型（Semantic Token Type）和语义修饰符（Semantic Token Modifier），在实际使用时，项的名称应添加后缀:python，以限制其仅对 Python 语言生效，并将所有的项放置在rules设置项中。

语义类型包括但不限于，class，enum，parameter，variable，property，enumMember，function，member，module，intrinsic，magicFunction，selfParameter，clsParameter。语义修饰符包括但不限于，declaration，readonly，static，abstract，async，typeHint，typeHintComment，decorator，builtin。

{
	// 为所有主题自定义 Python 语法高亮
	"editor.semanticTokenColorCustomizations": {
		"rules": {
			// 指定类的颜色
			"class:python": "#da9797",
			// 指定声明的颜色，比如，类和函数的定义
			"*.declaration:python": "#82cb7a"
		}
	}
}

源码

settings.json·codebeatme/python·GitHub