VSCode Pylance 延伸模組的使用和設定說明

VSCode Pylance 延伸模組

VSCode 中的Pylance延伸模組，為 Python 語言開發提供了強大的支援，比如，程式碼的智能提示，自動完成，診斷和分析。在一般情況下，該延伸模組會跟隨 VSCode 的Python延伸模組一同安裝，並將成為Python延伸模組認定的 Python 語言伺服器。

設定 VSCode Pylance 延伸模組

和大部分的 VSCode 延伸模組一樣，Pylance為開發人員提供了設定項，你可以通過編輯工作區.vscode資料夾中的setting.json檔案，或在 VSCode 的設定面板中編輯相關項，來調整和改變Pylance延伸模組所實作的某些功能。

設定 VSCode Pylance 延伸模組的 Python 型別檢查功能

Pylance延伸模組的設定項python.analysis.typeCheckingMode，可用於設定Pylance的 Python 型別檢查模式（Type Checking Mode），不同的型別檢查模式對應了不同的 Python 型別檢查規則集（Rule Set），從松散到嚴格，型別檢查模式分為以下幾種。

off 模式

off模式是python.analysis.typeCheckingMode設定項的預設值，他表示不對 Python 程式碼進行型別檢查，僅診斷無效的語法，未定義而被讀取的內容（變數，函式等），以及未能被解析的匯入（比如，匯入了無法存取的 Python 模組或套件，或匯入了不存在的內容）。

basic 模式

basic模式包含off模式中的所有規則，以及基礎的 Python 型別檢查規則，比如，不應該存取未知的類別特性，呼叫方法或函式時應該給出全部的必要參數。

standard 模式

standard模式包含off模式中的所有規則，以及基礎和標準的 Python 型別檢查規則，因此他相對於basic模式更為嚴格。

strict 模式

strict模式是最嚴格的型別檢查模式，包含off模式中的所有規則，以及所有 Python 型別檢查規則，比如，回報無法推斷出其型別的變數或參數。

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

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

{
	// 自訂 Python 型別檢查規則的嚴重性層級
	"python.analysis.diagnosticSeverityOverrides": {
		// 無法被解析的匯入
		"reportMissingImports": "warning"
	},
}

設定需要被 VSCode Pylance 延伸模組診斷的 Python 檔案

Pylance延伸模組的設定項python.analysis.diagnosticMode（診斷模式），可用於設定Pylance在什麽範圍內診斷 Python 程式碼檔案，診斷後得到的問題將顯示在 VSCode 的問題面板中，該設定項的有效值為以下兩種。

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"
	],
}

設定忽略 VSCode Pylance 延伸模組診斷結果的 Python 檔案

Pylance延伸模組的設定項python.analysis.ignore是一個包含路徑資訊的陣列（其預設值為[]），如果某個 Python 程式碼檔案路徑的開始部分符合該陣列的某一項，那麽Pylance關於該檔案的診斷結果（包括錯誤和警告）將被忽略（不予展示）。

與python.analysis.include設定項類似，python.analysis.ignore也可以使用相對路徑，絕對路徑以及路徑萬用字元。

{
	// 忽略診斷結果的檔案的路徑資訊
	"python.analysis.ignore": [
		// src 資料夾中名稱包含 test 的一級子資料夾
		"src\\*test*\\"
	],
}

設定 VSCode Pylance 延伸模組的 Python 型別虛設常式檔案目錄

Pylance延伸模組的設定項python.analysis.stubPath，可用於指定 Python 型別虛設常式（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,
}

設定 VSCode Pylance 延伸模組的額外 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 模組自動搜尋路徑，將python.analysis.autoSearchPaths設定為true（預設值），Pylance可嘗試從一些預定義的路徑（比如，VSCode 工作區根目錄下的src資料夾）中尋找並分析 Python 模組對應的程式碼檔案，當他們被匯入時。

在效果方面，模組自動搜尋路徑與額外模組路徑是相似的，只不過python.analysis.autoSearchPaths中的路徑是預設的，而python.analysis.extraPaths中的路徑則由開發人員指定。模組自動搜尋路徑同樣不會影響 Python 自身的模組搜尋路徑，並可能在執行階段提示模組未找到ModuleNotFoundError。

{
	// 停用 Python 模組自動搜尋路徑
	"python.analysis.autoSearchPaths": false,
}

設定 VSCode Pylance 延伸模組的 Python 索引編製功能

Pylance延伸模組的設定項python.analysis.indexing，可用於控製是否對使用者檔案（VSCode 工作區中的 Python 程式碼檔案，其對應的模組應具備有效的完整名稱），Python 第三方套件或模組進行索引編製（預設為true，進行索引編製），有效的索引是Pylance實作自動匯入模組，新增匯入陳述式等功能的先決條件。

{
	// 停用 Python 索引編製功能
	"python.analysis.indexing": false,
}

Pylance延伸模組的設定項python.analysis.packageIndexDepths是一個包含索引編製方案的陣列，不同的 Python 套件可以擁有不同的索引編製方案。在預設情況下，Pylance僅為直接位於第三方套件目錄的 Python 套件（不包含模組，以及套件中的子套件或子模組）編製索引。

如果想為 Python 套件的子套件或子模組編製索引，那麽需要將對應方案的depth設定項設定為2（預設為1），name設定項設定為 Python 套件的名稱，如果想為子套件的子套件或子模組編製索引，則需要將depth設定為3，以此類推。如果希望為 Python 套件或模組的所有特性編製索引，則需要將對應方案的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 }
	],
}

設定 VSCode Pylance 延伸模組的程式碼自動完成功能

Pylance延伸模組的設定項python.analysis.autoImportCompletions，可用於設定是否啟用 Python 匯入陳述式自動完成功能，該功能可自動書寫import或from…import匯入 Python 模組，當你使用了模組特性且並未匯入相關模組時，預設為false，不進行匯入陳述式的自動完成。如果python.analysis.indexing設定項為false，那麽Pylance的匯入陳述式自動完成功能僅針對在 VSCode 中開啟過的 Python 程式碼檔案（檔案對應的模組應具備有效的完整名稱）。

Pylance延伸模組的設定項python.analysis.importFormat，可用於設定 Python 匯入陳述式自動完成的格式，其有效值包含以下兩種。

absolute 格式

absolute格式是python.analysis.importFormat設定項的預設值，他表示以完整名稱自動完成 Python 匯入陳述式。

relative 格式

relative格式表示盡可能以相對名稱的方式自動完成 Python 匯入陳述式，如果無法完成，則采用完整名稱。

Pylance延伸模組的設定項python.analysis.completeFunctionParens，可用於設定是否啟用 Python 函式或方法括弧的自動完成功能，該功能可在選擇呼叫的函式或方法後自動書寫括弧()，預設為false，不進行函式或方法括弧的自動完成。

Pylance延伸模組的設定項python.analysis.autoFormatStrings，可用於設定是否為 Python 字串自動完成首碼f，當你在字串中書寫{時（請註意，該功能在某些情況下達不到預期效果）。python.analysis.autoFormatStrings的預設值為false，不進行首碼f的自動完成。

{
	// 啟用匯入陳述式的自動完成
	"python.analysis.autoImportCompletions": true,
	// 匯入陳述式的自動完成采用相對名稱
	"python.analysis.importFormat": "relative",
	// 啟用函式或方法的括弧自動完成
	"python.analysis.completeFunctionParens": true,
	// 啟用字串的 f 首碼自動完成（可能沒有效果）
	"python.analysis.autoFormatStrings": true,
}

設定 VSCode Pylance 延伸模組的程式碼內嵌提示功能

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,
}

設定 VSCode Pylance 延伸模組的程式碼導航功能

Pylance延伸模組的設定項python.analysis.gotoDefinitionInStringLiteral，可用於設定是否啟用 Python 字串的模組導航功能（預設為true，啟用），該功能可為 Python 字串中被認為是模組的文字提供導航，比如"sys is here"中的sys，針對sys使用操作功能表或鍵盤快速鍵，可跳躍至模組sys相關的程式碼檔案或型別虛設常式檔案。

{
	// 停用字串的模組導航功能
	"python.analysis.gotoDefinitionInStringLiteral": false,
}

設定 VSCode Pylance 延伸模組的記錄功能

Pylance延伸模組的設定項python.analysis.logLevel，可用於設定Pylance將哪些內容輸出為記錄，他擁有以下有效取值。

Error 層級

Error層級表示僅將錯誤輸出為記錄。

Warning 層級

Warning層級表示將錯誤和警告輸出為記錄。

Information 層級

Information層級是設定項python.analysis.logLevel的預設值，他表示將錯誤，警告和資訊輸出為記錄。

Trace 層級

Trace層級表示將錯誤，警告，資訊和追蹤輸出為記錄。

{
	// 設定 Pylance 僅匯報錯誤
	"python.analysis.logLevel": "Error",
}

設定 VSCode 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"
	],
}

設定執行 VSCode 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",
}

自訂 VSCode Pylance 延伸模組的 Python 語法醒目提示樣式

通過editor.semanticTokenColorCustomizations設定項，你可以針對 VSCode 的某個主題或所有主題，自訂Pylance延伸模組的 Python 語法醒目提示樣式，當然，主要是指色彩。以下是Pylance延伸模組所支援的，可用於自訂 Python 語法醒目提示樣式的具體語義類型（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