winreg --- 訪問 Windows 注冊(cè)表?

函數(shù)?

該模塊提供了下列函數(shù)：

winreg.CloseKey(hkey)?

關(guān)閉之前打開的注冊(cè)表鍵。參數(shù) hkey 指之前打開的鍵。

備注

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

winreg.ConnectRegistry(computer_name, key)?

建立到另一臺(tái)計(jì)算上上的預(yù)定義注冊(cè)表句柄的連接，并返回一個(gè) handle 對(duì)象.

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

key 是所連接到的預(yù)定義句柄。

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

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

在 3.3 版更改: 參考 上文。

winreg.CreateKey(key, sub_key)?

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

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

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

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

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

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

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

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

在 3.3 版更改: 參考 上文。

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

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

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

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

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

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

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

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

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

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

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

3.2 新版功能.

在 3.3 版更改: 參考 上文。

winreg.DeleteKey(key, sub_key)?

刪除指定的鍵。

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

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

該方法不能刪除帶有子項(xiàng)的鍵。

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

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

在 3.3 版更改: 參考 上文。

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

刪除指定的鍵。

備注

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

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

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

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

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

該方法不能刪除帶有子項(xiàng)的鍵。

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

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

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

3.2 新版功能.

在 3.3 版更改: 參考 上文。

winreg.DeleteValue(key, value)?

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

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

value 為標(biāo)識(shí)所要?jiǎng)h除值項(xiàng)的字符串。

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

winreg.EnumKey(key, index)?

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

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

index 為一個(gè)整數(shù)，用于標(biāo)識(shí)所獲取鍵的索引。

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

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

在 3.3 版更改: 參考 上文。

winreg.EnumValue(key, index)?

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

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

index 為一個(gè)整數(shù)，用于標(biāo)識(shí)要獲取值項(xiàng)的索引。

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

結(jié)果為3元素的元組。

索引	含意
0	用于標(biāo)識(shí)值項(xiàng)名稱的字符串。
1	保存值項(xiàng)數(shù)據(jù)的對(duì)象，其類型取決于背后的注冊(cè)表類型。
2	標(biāo)識(shí)值項(xiàng)數(shù)據(jù)類型的整數(shù)。（請(qǐng)查閱 SetValueEx() 文檔中的表格）

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

在 3.3 版更改: 參考 上文。

winreg.ExpandEnvironmentStrings(str)?

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

>>>

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

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

winreg.FlushKey(key)?

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

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

沒有必要調(diào)用 FlushKey() 去改動(dòng)注冊(cè)表鍵。注冊(cè)表的變動(dòng)是由其延遲刷新機(jī)制更新到磁盤的。在系統(tǒng)關(guān)機(jī)時(shí)，也會(huì)將注冊(cè)表的變動(dòng)寫入磁盤。與 CloseKey() 不同， FlushKey() 方法只有等到所有數(shù)據(jù)都寫入注冊(cè)表后才會(huì)返回。只有需要絕對(duì)確認(rèn)注冊(cè)表變動(dòng)已寫入磁盤時(shí)，應(yīng)用程序才應(yīng)去調(diào)用 FlushKey()。

備注

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

winreg.LoadKey(key, sub_key, file_name)?

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

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

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

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

如果調(diào)用 LoadKey() 的進(jìn)程沒有 SE_RESTORE_PRIVILEGE 權(quán)限，則調(diào)用會(huì)失敗。請(qǐng)注意，特權(quán)與權(quán)限不同 —— 更多細(xì)節(jié)請(qǐng)參閱 RegLoadKey 文檔。

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

引發(fā)一個(gè) 審計(jì)事件 winreg.LoadKey，附帶參數(shù) 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)?

打開指定的注冊(cè)表鍵，返回 handle對(duì)象。

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

sub_key 是個(gè)字符串，標(biāo)識(shí)了需要打開的子鍵。

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

access 是個(gè)指定訪問掩碼的整數(shù)，掩碼描述了注冊(cè)表鍵所需的安全權(quán)限。 默認(rèn)值為 KEY_READ。 其他合法值參見 訪問權(quán)限。

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

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

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

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

在 3.2 版更改: 允許使用命名參數(shù)。

在 3.3 版更改: 參考 上文。

winreg.QueryInfoKey(key)?

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

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

結(jié)果為3元素的元組。

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

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

winreg.QueryValue(key, sub_key)?

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

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

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

注冊(cè)表中的值包含名稱、類型和數(shù)據(jù)。本方法將讀取注冊(cè)表鍵值的第一個(gè)名稱為 NULL 的數(shù)據(jù)。可是底層的 API 調(diào)用不會(huì)返回類型，所以只要有可能就一定要使用 QueryValueEx()。

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

winreg.QueryValueEx(key, value_name)?

讀取已打開注冊(cè)表鍵指定值名稱的類型和數(shù)據(jù)。

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

value_name 是字符串，表示要查詢的值。

結(jié)果為二元組：

索引	含意
0	注冊(cè)表項(xiàng)的值。
1	整數(shù)值，給出該值的注冊(cè)表類型（請(qǐng)查看文檔中的表格了解 SetValueEx() ）。

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

winreg.SaveKey(key, file_name)?

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

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

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

如果 key 代表遠(yuǎn)程計(jì)算機(jī)的注冊(cè)表鍵，那么 file_name 所描述的路徑是相對(duì)于遠(yuǎn)程計(jì)算機(jī)的。本方法的調(diào)用者必須擁有 SeBackupPrivilege 特權(quán)。請(qǐng)注意，特權(quán)與權(quán)限是不同的 —— 更多細(xì)節(jié)請(qǐng)參見 用戶權(quán)利和權(quán)限之間的沖突文檔。

本函數(shù)將 NULL 傳給 API 的 security_attributes。

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

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

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

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

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

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

value 是設(shè)置新值的字符串。

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

值的長度受到可用內(nèi)存的限制。較長的值（超過 2048 字節(jié)）應(yīng)存為文件，并將文件名存入配置注冊(cè)表。這有助于提高注冊(cè)表的使用效率。

由 key 參數(shù)標(biāo)識(shí)的注冊(cè)表鍵，必須已用 KEY_SET_VALUE 方式打開。

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

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

將數(shù)據(jù)存入已打開的注冊(cè)表鍵的值中。

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

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

reserved 可以是任意數(shù)據(jù) —— 傳給 API 的總是 0。

type 是個(gè)整數(shù)，用于指定數(shù)據(jù)的類型。請(qǐng)參閱 Value Types 了解可用的類型。

value 是設(shè)置新值的字符串。

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

請(qǐng)用 CreateKey() 或 OpenKey() 方法打開注冊(cè)表鍵。

值的長度受到可用內(nèi)存的限制。較長的值（超過 2048 字節(jié)）應(yīng)存為文件，并將文件名存入配置注冊(cè)表。這有助于提高注冊(cè)表的使用效率。

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

winreg.DisableReflectionKey(key)?

禁用運(yùn)行于 64 位操作系統(tǒng)的 32 位進(jìn)程的注冊(cè)表重定向。

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

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

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

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

winreg.EnableReflectionKey(key)?

恢復(fù)已禁用注冊(cè)表鍵的重定向。

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

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

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

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

winreg.QueryReflectionKey(key)?

確定給定注冊(cè)表鍵的重定向狀況。

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

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

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

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

常量?

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

注冊(cè)表句柄對(duì)象?

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

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

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

注冊(cè)表句柄對(duì)象支持 __bool__() 語義 —— 因此如果當(dāng)前句柄有效（未關(guān)閉或斷開連接）：

if handle:
    print("Yes")

將會(huì)打印出 Yes 。

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

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

PyHKEY.Close()?

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

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

PyHKEY.Detach()?

斷開與 Windows 句柄的連接。

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

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

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

PyHKEY.__enter__()?

PyHKEY.__exit__(*exc_info)?

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

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

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