winreg --- 訪問 Windows 注冊表?

函數?

該模塊提供了下列函數：

winreg.CloseKey(hkey)?

關閉之前打開的注冊表鍵。參數 hkey 指之前打開的鍵。

備注

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

winreg.ConnectRegistry(computer_name, key)?

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

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

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

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

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

在 3.3 版更改: 參考 上文。

winreg.CreateKey(key, sub_key)?

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

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

如果鍵已經存在，則該函數打開已經存在的該鍵。

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

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

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

在 3.3 版更改: 參考 上文。

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

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

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

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

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

如果鍵已經存在，則該函數打開已經存在的該鍵。

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

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

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

3.2 新版功能.

在 3.3 版更改: 參考 上文。

winreg.DeleteKey(key, sub_key)?

刪除指定的鍵。

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

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

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

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

在 3.3 版更改: 參考 上文。

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

刪除指定的鍵。

備注

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

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

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

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

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

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

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

3.2 新版功能.

在 3.3 版更改: 參考 上文。

winreg.DeleteValue(key, value)?

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

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

winreg.EnumKey(key, index)?

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

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

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

在 3.3 版更改: 參考 上文。

winreg.EnumValue(key, index)?

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

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

結果為3元素的元組。

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

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

winreg.FlushKey(key)?

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

備注

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

winreg.LoadKey(key, sub_key, file_name)?

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

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

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

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

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

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

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

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

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

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

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

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

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

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

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

在 3.3 版更改: 參考 上文。

winreg.QueryInfoKey(key)?

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

結果為3元素的元組。

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

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

winreg.QueryValue(key, sub_key)?

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

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

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

winreg.QueryValueEx(key, value_name)?

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

結果為二元組：

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

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

winreg.SaveKey(key, file_name)?

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

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

本函數將 NULL 傳給 API 的 security_attributes。

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

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

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

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

value 是設置新值的字符串。

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

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

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

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

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

將數據存入已打開的注冊表鍵的值中。

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

value_name 是個字符串，用于命名與值相關的子鍵。

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

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

value 是設置新值的字符串。

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

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

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

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

winreg.DisableReflectionKey(key)?

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

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

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

winreg.EnableReflectionKey(key)?

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

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

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

winreg.QueryReflectionKey(key)?

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

key 為某個已經打開的鍵，或者預定義的 HKEY_* 常量 之一。

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

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

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

常量?

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

注冊表句柄對象?

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

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

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

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

if handle:
    print("Yes")

將會打印出 Yes 。

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

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

PyHKEY.Close()?

關閉底層的 Windows 句柄。

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

PyHKEY.Detach()?

斷開與 Windows 句柄的連接。

結果為一個整數，存有被斷開連接之前的句柄值。如果該句柄已斷開連接或關閉，則返回 0。

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

引發(fā)一條 審計事件 winreg.PyHKEY.Detach，附帶參數 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 會自動關閉。