winreg --- 訪問 Windows 注冊表?

函數(shù)?

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

winreg.CloseKey(hkey)?

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

備注

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

winreg.ConnectRegistry(computer_name, key)?

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

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

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

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

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

在 3.3 版更改: 參考 上文。

winreg.CreateKey(key, sub_key)?

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

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

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

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

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

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

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

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

在 3.3 版更改: 參考 上文。

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

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

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

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

reserved 是一個保留的證書，必須是零。默認值為零。

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

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

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

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

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

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

3.2 新版功能.

在 3.3 版更改: 參考 上文。

winreg.DeleteKey(key, sub_key)?

刪除指定的鍵。

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

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

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

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

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

在 3.3 版更改: 參考 上文。

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

刪除指定的鍵。

備注

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

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

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

reserved 是一個保留的證書，必須是零。默認值為零。

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

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

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

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

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

3.2 新版功能.

在 3.3 版更改: 參考 上文。

winreg.DeleteValue(key, value)?

從某個注冊鍵中刪除一個命名值項。

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

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

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

winreg.EnumKey(key, index)?

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

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

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

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

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

在 3.3 版更改: 參考 上文。

winreg.EnumValue(key, index)?

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

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

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

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

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

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

引發(fā)一個 審計事件 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ā)一個 審計事件 winreg.ExpandEnvironmentStrings，附帶參數(shù) str。

winreg.FlushKey(key)?

將某個鍵的所有屬性寫入注冊表。

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

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

備注

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

winreg.LoadKey(key, sub_key, file_name)?

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

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

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

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

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

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

引發(fā)一個 審計事件 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)?

打開指定的注冊表鍵，返回 handle對象。

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

sub_key 是個字符串，標識了需要打開的子鍵。

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

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

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

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

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

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

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

在 3.3 版更改: 參考 上文。

winreg.QueryInfoKey(key)?

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

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

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

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

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

winreg.QueryValue(key, sub_key)?

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

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

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

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

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

winreg.QueryValueEx(key, value_name)?

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

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

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

結(jié)果為二元組：

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

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

winreg.SaveKey(key, file_name)?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

winreg.DisableReflectionKey(key)?

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

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

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

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

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

winreg.EnableReflectionKey(key)?

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

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

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

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

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

winreg.QueryReflectionKey(key)?

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

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

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

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

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

常量?

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

注冊表句柄對象?

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

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

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

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

if handle:
    print("Yes")

將會打印出 Yes 。

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

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

PyHKEY.Close()?

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

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

PyHKEY.Detach()?

斷開與 Windows 句柄的連接。

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

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

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

PyHKEY.__enter__()?

PyHKEY.__exit__(*exc_info)?

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

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

在離開 with 語句塊時，key 會自動關(guān)閉。