函數?

該模塊提供了下列函數：

winreg.CloseKey(hkey)?

關(guān)閉之前打開(kāi)的注冊表鍵。參數 hkey 指之前打開(kāi)的鍵。

備注

如果沒(méi)有使用該方法關(guān)閉 hkey (或者通過(guò) hkey.Close())，在對象 hkey 被 Python 銷(xiāo)毀時(shí)會(huì )將其關(guān)閉。

winreg.ConnectRegistry(computer_name, key)?

建立到另一臺計算上上的預定義注冊表句柄的連接，并返回一個(gè) handle 對象.

computer_name 是遠程計算機的名稱(chēng)，以 r"\\computername" 的形式。如果是 None ，將會(huì )使用本地計算機。

key 是所連接到的預定義句柄。

返回值是所開(kāi)打鍵的句柄。如果函數失敗，則引發(fā)一個(gè) OSError 異常。

引發(fā)一個(gè) 審計事件 winreg.ConnectRegistry，附帶參數 computer_name, key。

在 3.3 版更改: 參考 上文。

winreg.CreateKey(key, sub_key)?

創(chuàng )建或打開(kāi)特定的鍵，返回一個(gè) handle 對象。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

sub_key 是用于命名該方法所打開(kāi)或創(chuàng )建的鍵的字符串。

如果 key 是預定義鍵之一，sub_key 可能會(huì )是 None。該情況下，返回的句柄就是傳入函數的句柄。

如果鍵已經(jīng)存在，則該函數打開(kāi)已經(jīng)存在的該鍵。

返回值是所開(kāi)打鍵的句柄。如果函數失敗，則引發(fā)一個(gè) OSError 異常。

引發(fā)一個(gè) 審計事件 winreg.CreateKey，附帶參數 key, sub_key, access。

引發(fā)一個(gè) 審計事件 winreg.OpenKey/result，附帶參數 key。

在 3.3 版更改: 參考 上文。

winreg.CreateKeyEx(key, sub_key, reserved=0, access=KEY_WRITE)?

創(chuàng )建或打開(kāi)特定的鍵，返回一個(gè) handle 對象。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

sub_key 是用于命名該方法所打開(kāi)或創(chuàng )建的鍵的字符串。

reserved 是一個(gè)保留的證書(shū)，必須是零。默認值為零。

access 為一個(gè)整數，用于給鍵的預期安全訪(fǎng)問(wèn)指定訪(fǎng)問(wèn)掩碼。默認值為 KEY_WRITE。 參閱 Access Rights 了解其它允許值。

如果 key 是預定義鍵之一，sub_key 可能會(huì )是 None。該情況下，返回的句柄就是傳入函數的句柄。

如果鍵已經(jīng)存在，則該函數打開(kāi)已經(jīng)存在的該鍵。

返回值是所開(kāi)打鍵的句柄。如果函數失敗，則引發(fā)一個(gè) OSError 異常。

引發(fā)一個(gè) 審計事件 winreg.CreateKey，附帶參數 key, sub_key, access。

引發(fā)一個(gè) 審計事件 winreg.OpenKey/result，附帶參數 key。

3.2 新版功能.

在 3.3 版更改: 參考 上文。

winreg.DeleteKey(key, sub_key)?

刪除指定的鍵。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

sub_key 這個(gè)字符串必須是由 key 參數所指定鍵的一個(gè)子項。該值項不可以是 None，同時(shí)鍵也不可以有子項。

該方法不能刪除帶有子項的鍵。

如果方法成功，則整個(gè)鍵，包括其所有值項都會(huì )被移除。如果方法失敗，則引發(fā)一個(gè) OSError 異常。

引發(fā)一個(gè) 審計事件 winreg.DeleteKey，附帶參數 key, sub_key, access。

在 3.3 版更改: 參考 上文。

winreg.DeleteKeyEx(key, sub_key, access=KEY_WOW64_64KEY, reserved=0)?

刪除指定的鍵。

備注

函數 DeleteKeyEx() 通過(guò) RegDeleteKeyEx 這個(gè) Windows API 函數實(shí)現，該函數為 Windows 的64位版本專(zhuān)屬。 參閱 RegDeleteKeyEx 文檔。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

sub_key 這個(gè)字符串必須是由 key 參數所指定鍵的一個(gè)子項。該值項不可以是 None，同時(shí)鍵也不可以有子項。

reserved 是一個(gè)保留的證書(shū)，必須是零。默認值為零。

access 為一個(gè)整數，用于給鍵的預期安全訪(fǎng)問(wèn)指定訪(fǎng)問(wèn)掩碼。默認值為常量 _WOW64_64KEY 。參閱 Access Rights 了解其它允許值。

該方法不能刪除帶有子項的鍵。

如果方法成功，則整個(gè)鍵，包括其所有值項都會(huì )被移除。如果方法失敗，則引發(fā)一個(gè) OSError 異常。

在不支持的 Windows 版本之上，將會(huì )引發(fā) NotImplementedError 異常。

引發(fā)一個(gè) 審計事件 winreg.DeleteKey，附帶參數 key, sub_key, access。

3.2 新版功能.

在 3.3 版更改: 參考 上文。

winreg.DeleteValue(key, value)?

從某個(gè)注冊鍵中刪除一個(gè)命名值項。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

value 為標識所要刪除值項的字符串。

引發(fā)一個(gè) 審計事件 winreg.DeleteValue，附帶參數 key, value。

winreg.EnumKey(key, index)?

列舉某個(gè)已經(jīng)打開(kāi)注冊表鍵的子項，并返回一個(gè)字符串。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

index 為一個(gè)整數，用于標識所獲取鍵的索引。

每次調用該函數都會(huì )獲取一個(gè)子項的名字。通常它會(huì )被反復調用，直到引發(fā) OSError 異常，這說(shuō)明已經(jīng)沒(méi)有更多的可用值了。

引發(fā)一個(gè) 審計事件 winreg.EnumKey，附帶參數 key, index。

在 3.3 版更改: 參考 上文。

winreg.EnumValue(key, index)?

列舉某個(gè)已經(jīng)打開(kāi)注冊表鍵的值項，并返回一個(gè)元組。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

index 為一個(gè)整數，用于標識要獲取值項的索引。

每次調用該函數都會(huì )獲取一個(gè)子項的名字。通常它會(huì )被反復調用，直到引發(fā) OSError 異常，這說(shuō)明已經(jīng)沒(méi)有更多的可用值了。

結果為3元素的元組。

索引	含意
0	用于標識值項名稱(chēng)的字符串。
1	保存值項數據的對象，其類(lèi)型取決于背后的注冊表類(lèi)型。
2	標識值項數據類(lèi)型的整數。（請查閱 SetValueEx() 文檔中的表格）

引發(fā)一個(gè) 審計事件 winreg.EnumValue，附帶參數 key, index。

在 3.3 版更改: 參考 上文。

winreg.ExpandEnvironmentStrings(str)?

Expands environment variable placeholders %NAME% in strings like REG_EXPAND_SZ:

>>>

>>> ExpandEnvironmentStrings('%windir%')
'C:\\Windows'

引發(fā)一個(gè) 審計事件 winreg.ExpandEnvironmentStrings，附帶參數 str。

winreg.FlushKey(key)?

將某個(gè)鍵的所有屬性寫(xiě)入注冊表。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

沒(méi)有必要調用 FlushKey() 去改動(dòng)注冊表鍵。注冊表的變動(dòng)是由其延遲刷新機制更新到磁盤(pán)的。在系統關(guān)機時(shí)，也會(huì )將注冊表的變動(dòng)寫(xiě)入磁盤(pán)。與 CloseKey() 不同， FlushKey() 方法只有等到所有數據都寫(xiě)入注冊表后才會(huì )返回。只有需要絕對確認注冊表變動(dòng)已寫(xiě)入磁盤(pán)時(shí)，應用程序才應去調用 FlushKey()。

備注

如果不知道是否要調用 FlushKey() ，可能就是不需要。

winreg.LoadKey(key, sub_key, file_name)?

在指定鍵之下創(chuàng )建一個(gè)子鍵，并將指定文件中的注冊表信息存入該子鍵中。

key 是由 ConnectRegistry() 返回的句柄，或者是常量 HKEY_USERS 或 HKEY_LOCAL_MACHINE。

sub_key 是個(gè)字符串，用于標識需要載入的子鍵。

file_name 是要加載注冊表數據的文件名。該文件必須是用 SaveKey() 函數創(chuàng )建的。在文件分配表（FAT）文件系統中，文件名可能不帶擴展名。

如果調用 LoadKey() 的進(jìn)程沒(méi)有 SE_RESTORE_PRIVILEGE 權限，則調用會(huì )失敗。請注意，特權與權限不同 —— 更多細節請參閱 RegLoadKey 文檔。

如果 key 是由 ConnectRegistry() 返回的句柄，那么 file_name 指定的路徑是相對于遠程計算機而言的。

引發(fā)一個(gè) 審計事件 winreg.LoadKey，附帶參數 key, sub_key, file_name。

winreg.OpenKey(key, sub_key, reserved=0, access=KEY_READ)?

winreg.OpenKeyEx(key, sub_key, reserved=0, access=KEY_READ)?

打開(kāi)指定的注冊表鍵，返回 handle對象。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

sub_key 是個(gè)字符串，標識了需要打開(kāi)的子鍵。

reserved 是個(gè)保留整數，必須為零。默認值為零。

access 是個(gè)指定訪(fǎng)問(wèn)掩碼的整數，掩碼描述了注冊表鍵所需的安全權限。 默認值為 KEY_READ。 其他合法值參見(jiàn) 訪(fǎng)問(wèn)權限。

返回結果為一個(gè)新句柄，指向指定的注冊表鍵。

如果調用失敗，則會(huì )觸發(fā) OSError 。

觸發(fā) 審計事件 winreg.OpenKey，附帶參數為 key 、sub_key 、 access。

引發(fā)一個(gè) 審計事件 winreg.OpenKey/result，附帶參數 key。

在 3.2 版更改: 允許使用命名參數。

在 3.3 版更改: 參考 上文。

winreg.QueryInfoKey(key)?

以元組形式返回某注冊表鍵的信息。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

結果為3元素的元組。

索引	含意
0	整數值，給出了此注冊表鍵的子鍵數量。
1	整數值，給出了此注冊表鍵的值的數量。
2	整數值，給出了此注冊表鍵的最后修改時(shí)間，單位為自 1601 年 1 月 1 日以來(lái)的 100 納秒。

觸發(fā) 審計事件 winreg.QueryInfoKey，附帶參數為 key。

winreg.QueryValue(key, sub_key)?

讀取某鍵的未命名值，形式為字符串。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

sub_key 是個(gè)字符串，用于保存與某個(gè)值相關(guān)的子鍵名稱(chēng)。如果本參數為 None 或空，函數將讀取由 SetValue() 方法為 key 鍵設置的值。

注冊表中的值包含名稱(chēng)、類(lèi)型和數據。本方法將讀取注冊表鍵值的第一個(gè)名稱(chēng)為 NULL 的數據?？墒堑讓拥?API 調用不會(huì )返回類(lèi)型，所以只要有可能就一定要使用 QueryValueEx()。

觸發(fā) 審計事件 winreg.QueryValue，附帶參數為 key、 sub_key 、 value_name。

winreg.QueryValueEx(key, value_name)?

讀取已打開(kāi)注冊表鍵指定值名稱(chēng)的類(lèi)型和數據。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

value_name 是字符串，表示要查詢(xún)的值。

結果為二元組：

索引	含意
0	注冊表項的值。
1	整數值，給出該值的注冊表類(lèi)型（請查看文檔中的表格了解 SetValueEx() ）。

觸發(fā) 審計事件 winreg.QueryValue，附帶參數為 key、 sub_key 、 value_name。

winreg.SaveKey(key, file_name)?

將指定注冊表鍵及其所有子鍵存入指定的文件。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

file_name 是要保存注冊表數據的文件名。該文件不能已存在。如果文件名包括擴展名，也不能在文件分配表（FAT）文件系統中用于 LoadKey() 方法。

如果 key 代表遠程計算機的注冊表鍵，那么 file_name 所描述的路徑是相對于遠程計算機的。本方法的調用者必須擁有 SeBackupPrivilege 特權。請注意，特權與權限是不同的 —— 更多細節請參見(jiàn) 用戶(hù)權利和權限之間的沖突文檔。

本函數將 NULL 傳給 API 的 security_attributes。

引發(fā)一個(gè) 審計事件 winreg.SaveKey，附帶參數 key, file_name。

winreg.SetValue(key, sub_key, type, value)?

將值與指定的注冊表鍵關(guān)聯(lián)。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

sub_key 是個(gè)字符串，用于命名與該值相關(guān)的子鍵。

type 是個(gè)整數，用于指定數據的類(lèi)型。目前這必須是 REG_SZ ，意味著(zhù)只支持字符串。請用 SetValueEx() 函數支持其他的數據類(lèi)型。

value 是設置新值的字符串。

如果 sub_key 參數指定的注冊表鍵不存在，SetValue 函數會(huì )創(chuàng )建一個(gè)。

值的長(cháng)度受到可用內存的限制。較長(cháng)的值（超過(guò) 2048 字節）應存為文件，并將文件名存入配置注冊表。這有助于提高注冊表的使用效率。

由 key 參數標識的注冊表鍵，必須已用 KEY_SET_VALUE 方式打開(kāi)。

觸發(fā) 審計事件 winreg.SetValue，附帶參數 key、 sub_key 、 type 、 value。

winreg.SetValueEx(key, value_name, reserved, type, value)?

將數據存入已打開(kāi)的注冊表鍵的值中。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

value_name 是個(gè)字符串，用于命名與值相關(guān)的子鍵。

reserved 可以是任意數據 —— 傳給 API 的總是 0。

type 是個(gè)整數，用于指定數據的類(lèi)型。請參閱 Value Types 了解可用的類(lèi)型。

value 是設置新值的字符串。

本方法也可為指定的注冊表鍵設置額外的值和類(lèi)型信息。注冊表鍵必須已用 KEY_SET_VALUE 方式打開(kāi)。

請用 CreateKey() 或 OpenKey() 方法打開(kāi)注冊表鍵。

值的長(cháng)度受到可用內存的限制。較長(cháng)的值（超過(guò) 2048 字節）應存為文件，并將文件名存入配置注冊表。這有助于提高注冊表的使用效率。

觸發(fā) 審計事件 winreg.SetValue，附帶參數 key、 sub_key 、 type 、 value。

winreg.DisableReflectionKey(key)?

禁用運行于 64 位操作系統的 32 位進(jìn)程的注冊表重定向。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

如果在 32 位操作系統上執行，一般會(huì )觸發(fā) NotImplementedError。

如果注冊表鍵不在重定向列表中，函數會(huì )調用成功，但沒(méi)有實(shí)際效果。禁用注冊表鍵的重定向不會(huì )影響任何子鍵的重定向。

觸發(fā) 審計事件 winreg.DisableReflectionKey，附帶參數 key。

winreg.EnableReflectionKey(key)?

恢復已禁用注冊表鍵的重定向。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

如果在 32 位操作系統上執行，一般會(huì )觸發(fā) NotImplementedError。

恢復注冊表鍵的重定向不會(huì )影響任何子鍵的重定向。

觸發(fā) 審計事件 winreg.EnableReflectionKey，附帶參數 key。

winreg.QueryReflectionKey(key)?

確定給定注冊表鍵的重定向狀況。

key 為某個(gè)已經(jīng)打開(kāi)的鍵，或者預定義的 HKEY_* 常量 之一。

如果重定向已禁用則返回 True。

如果在 32 位操作系統上執行，一般會(huì )觸發(fā) NotImplementedError。

引發(fā)一個(gè) 審計事件 winreg.QueryReflectionKey，附帶參數 key。

常量?

以下常量定義成可供很多 _winreg 函數使用。

注冊表句柄對象?

該對象封裝了 Windows HKEY 對象，對象銷(xiāo)毀時(shí)會(huì )自動(dòng)關(guān)閉。為確保資源得以清理，可調用 Close() 方法或 CloseKey() 函數。

本模塊中的所有注冊表函數都會(huì )返回注冊表句柄對象。

本模塊中所有接受注冊表句柄對象的注冊表函數，也能接受一個(gè)整數，但鼓勵大家使用句柄對象。

注冊表句柄對象支持 __bool__() 語(yǔ)義 —— 因此如果當前句柄有效（未關(guān)閉或斷開(kāi)連接）：

if handle:
    print("Yes")

將會(huì )打印出 Yes 。

句柄對象還支持比較語(yǔ)義，因此若多個(gè)句柄對象都引用了同一底層 Windows 句柄值，那么比較操作結果將為 True。

句柄對象可轉換為整數（如利用內置函數 int()），這時(shí)會(huì )返回底層的 Windows 句柄值。用 Detach() 方法也可返回整數句柄，同時(shí)會(huì )斷開(kāi)與 Windows 句柄的連接。

PyHKEY.Close()?

關(guān)閉底層的 Windows 句柄。

如果句柄已關(guān)閉，不會(huì )引發(fā)錯誤。

PyHKEY.Detach()?

斷開(kāi)與 Windows 句柄的連接。

結果為一個(gè)整數，存有被斷開(kāi)連接之前的句柄值。如果該句柄已斷開(kāi)連接或關(guān)閉，則返回 0。

調用本函數后，注冊表句柄將被迅速禁用，但并沒(méi)有關(guān)閉。當需要底層的 Win32 句柄在句柄對象的生命周期之后仍然存在時(shí)，可以調用這個(gè)函數。

引發(fā)一條 審計事件 winreg.PyHKEY.Detach，附帶參數 key。

PyHKEY.__enter__()?

PyHKEY.__exit__(*exc_info)?

HKEY 對象實(shí)現了 __enter__() 和 __exit__() 方法，因此支持 with 語(yǔ)句的上下文協(xié)議：

with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
    ...  # work with key

在離開(kāi) with 語(yǔ)句塊時(shí)，key 會(huì )自動(dòng)關(guān)閉。