winreg — Windows 登錄檔訪問¶
這些函式向 Python 公開 Windows 登錄檔 API。 與使用整數作為登錄檔控制代碼不同，這裡使用 控制代碼物件 來確保控制代碼被正確關閉，即使程式設計師忽略了顯式關閉它們。
在 3.3 版本中更改: 此模組中的多個函式過去會引發 WindowsError，現在它是 OSError 的別名。
函式¶
此模組提供以下函式
- winreg.CloseKey(hkey)¶
關閉先前開啟的登錄檔項。hkey 引數指定先前開啟的項。
注意
如果未使用此方法（或透過
hkey.Close()）關閉 hkey，則當 Python 銷燬 hkey 物件時會關閉它。
- winreg.ConnectRegistry(computer_name, key)¶
建立與另一臺計算機上的預定義登錄檔控制代碼的連線，並返回一個 控制代碼物件。
computer_name 是遠端計算機的名稱，形式為
r"\\computername"。如果為None，則使用本地計算機。key 是要連線的預定義控制代碼。
返回值是已開啟項的控制代碼。如果函式失敗，則會引發
OSError異常。使用引數
computer_name,key引發 審計事件winreg.ConnectRegistry。在 3.3 版本中更改: 請參見 上面。
- winreg.CreateKey(key, sub_key)¶
建立或開啟指定的項，返回一個 控制代碼物件。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
sub_key 是一個字串，用於命名此方法開啟或建立的項。
如果 key 是預定義項之一，則 sub_key 可以為
None。在這種情況下，返回的控制代碼與傳遞給函式的同一項控制代碼相同。如果該項已經存在，此函式將開啟現有項。
返回值是已開啟項的控制代碼。如果函式失敗，則會引發
OSError異常。使用引數
key,sub_key,access引發 審計事件winreg.CreateKey。使用引數
key引發 審計事件winreg.OpenKey/result。在 3.3 版本中更改: 請參見 上面。
- winreg.CreateKeyEx(key, sub_key, reserved=0, access=KEY_WRITE)¶
建立或開啟指定的項，返回一個 控制代碼物件。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
sub_key 是一個字串，用於命名此方法開啟或建立的項。
reserved 是一個保留整數，必須為零。預設值為零。
access 是一個整數，指定一個訪問掩碼，描述該項所需的安全訪問許可權。預設值為
KEY_WRITE。有關其他允許值，請參見 訪問許可權。如果 key 是預定義項之一，則 sub_key 可以為
None。在這種情況下，返回的控制代碼與傳遞給函式的同一項控制代碼相同。如果該項已經存在，此函式將開啟現有項。
返回值是已開啟項的控制代碼。如果函式失敗，則會引發
OSError異常。使用引數
key,sub_key,access引發 審計事件winreg.CreateKey。使用引數
key引發 審計事件winreg.OpenKey/result。3.2 版本新增。
在 3.3 版本中更改: 請參見 上面。
- winreg.DeleteKey(key, sub_key)¶
刪除指定的項。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
sub_key 是一個字串，必須是由 key 引數標識的項的子項。此值不能為
None，並且該項不能有子項。此方法不能刪除具有子項的項。
如果該方法成功，則會刪除整個項，包括其所有值。如果該方法失敗，則會引發
OSError異常。使用引數
key,sub_key,access引發 審計事件winreg.DeleteKey。在 3.3 版本中更改: 請參見 上面。
- winreg.DeleteKeyEx(key, sub_key, access=KEY_WOW64_64KEY, reserved=0)¶
刪除指定的項。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
sub_key 是一個字串，必須是由 key 引數標識的項的子項。此值不能為
None，並且該項不能有子項。reserved 是一個保留整數，必須為零。預設值為零。
access 是一個整數，指定一個訪問掩碼，描述該項所需的安全訪問許可權。預設值為
KEY_WOW64_64KEY。在 32 位 Windows 上，將忽略 WOW64 常量。有關其他允許值，請參見 訪問許可權。此方法不能刪除具有子項的項。
如果該方法成功，則會刪除整個項，包括其所有值。如果該方法失敗，則會引發
OSError異常。在不支援的 Windows 版本上，會引發
NotImplementedError。使用引數
key,sub_key,access引發 審計事件winreg.DeleteKey。3.2 版本新增。
在 3.3 版本中更改: 請參見 上面。
- winreg.DeleteValue(key, value)¶
從登錄檔項中刪除一個命名的值。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
value 是一個字串，用於標識要刪除的值。
觸發一個帶有引數
key,value的 審計事件winreg.DeleteValue。
- winreg.EnumKey(key, index)¶
列舉開啟的登錄檔項的子項，返回一個字串。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
index 是一個整數，用於標識要檢索的鍵的索引。
該函式每次呼叫時檢索一個子項的名稱。它通常被重複呼叫，直到引發
OSError異常，表明沒有更多可用的值。觸發一個帶有引數
key,index的 審計事件winreg.EnumKey。在 3.3 版本中更改: 請參見 上面。
- winreg.EnumValue(key, index)¶
列舉開啟的登錄檔項的值，返回一個元組。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
index 是一個整數，用於標識要檢索的值的索引。
該函式每次呼叫時檢索一個子項的名稱。它通常被重複呼叫，直到引發
OSError異常，表明沒有更多可用的值。結果是一個包含 3 個專案的元組
索引
含義
0一個標識值名稱的字串
1一個儲存值資料的物件，其型別取決於底層登錄檔型別
2一個整數，用於標識值資料的型別（請參閱
SetValueEx()的文件中的表格）觸發一個帶有引數
key,index的 審計事件winreg.EnumValue。在 3.3 版本中更改: 請參見 上面。
- winreg.ExpandEnvironmentStrings(str)¶
展開字串中類似
REG_EXPAND_SZ的環境變數佔位符%NAME%>>> ExpandEnvironmentStrings('%windir%') 'C:\\Windows'
觸發一個帶有引數
str的 審計事件winreg.ExpandEnvironmentStrings。
- winreg.FlushKey(key)¶
將鍵的所有屬性寫入登錄檔。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
不需要呼叫
FlushKey()來更改鍵。登錄檔使用其惰性重新整理器將登錄檔更改重新整理到磁碟。登錄檔更改也會在系統關閉時重新整理到磁碟。與CloseKey()不同，只有在所有資料都寫入登錄檔後，FlushKey()方法才會返回。只有在需要絕對確定登錄檔更改已寫入磁碟時，應用程式才應呼叫FlushKey()。注意
如果您不知道是否需要呼叫
FlushKey()，那麼可能就不需要。
- winreg.LoadKey(key, sub_key, file_name)¶
在指定的鍵下建立一個子鍵，並將指定檔案中的註冊資訊儲存到該子鍵中。
key 是由
ConnectRegistry()返回的控制代碼，或者是常量HKEY_USERS或HKEY_LOCAL_MACHINE之一。sub_key 是一個字串，用於標識要載入的子鍵。
file_name 是要從中載入登錄檔資料的檔名。此檔案必須使用
SaveKey()函式建立。在檔案分配表 (FAT) 檔案系統下，檔名可能沒有副檔名。如果呼叫程序沒有
SE_RESTORE_PRIVILEGE許可權，則呼叫LoadKey()將失敗。請注意，許可權與許可不同 - 有關更多詳細資訊，請參閱 RegLoadKey 文件。如果 key 是由
ConnectRegistry()返回的控制代碼，則 file_name 中指定的路徑相對於遠端計算機。觸發一個帶有引數
key,sub_key,file_name的 審計事件winreg.LoadKey。
- winreg.OpenKey(key, sub_key, reserved=0, access=KEY_READ)¶
- winreg.OpenKeyEx(key, sub_key, reserved=0, access=KEY_READ)¶
開啟指定的鍵，返回一個 控制代碼物件。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
sub_key 是一個字串，用於標識要開啟的子鍵。
reserved 是一個保留整數，必須為零。預設值為零。
access 是一個整數，用於指定描述鍵所需安全訪問的訪問掩碼。預設值為
KEY_READ。有關其他允許的值，請參閱 訪問許可權。結果是指定鍵的新控制代碼。
如果函式失敗，則會引發
OSError。觸發一個帶有引數
key,sub_key,access的 審計事件winreg.OpenKey。使用引數
key引發 審計事件winreg.OpenKey/result。在 3.2 版本中更改: 允許使用命名引數。
在 3.3 版本中更改: 請參見 上面。
- winreg.QueryInfoKey(key)¶
以元組的形式返回有關鍵的資訊。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
結果是一個包含 3 個專案的元組
索引
含義
0一個整數，表示此鍵擁有的子鍵數。
1一個整數，表示此鍵擁有的值數。
2一個整數，表示鍵上次修改的時間（如果可用），以自 1601 年 1 月 1 日起的 100 納秒為單位。
觸發一個帶有引數
key的 審計事件winreg.QueryInfoKey。
- winreg.QueryValue(key, sub_key)¶
以字串的形式檢索鍵的未命名值。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
sub_key 是一個字串，它儲存與該值關聯的子鍵的名稱。如果此引數為
None或為空，則該函式檢索由SetValue()方法為由 key 標識的鍵設定的值。登錄檔中的值具有名稱、型別和資料組成部分。此方法檢索鍵的第一個具有
NULL名稱的值的資料。但是，底層 API 呼叫不返回型別，因此如果可能，請始終使用QueryValueEx()。引發帶有引數
key、sub_key、value_name的 審計事件winreg.QueryValue。
- winreg.QueryValueEx(key, value_name)¶
檢索與開啟的登錄檔鍵關聯的指定值的型別和資料。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
value_name 是一個字串，指示要查詢的值。
結果是一個包含 2 項的元組
索引
含義
0登錄檔項的值。
1一個整數，給出此值的登錄檔型別（請參閱
SetValueEx()的文件中的表）引發帶有引數
key、sub_key、value_name的 審計事件winreg.QueryValue。
- winreg.SaveKey(key, file_name)¶
將指定的鍵及其所有子鍵儲存到指定的檔案。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
file_name 是要將登錄檔資料儲存到的檔案的名稱。此檔案不能已存在。如果此檔名包含副檔名，則
LoadKey()方法不能在檔案分配表 (FAT) 檔案系統上使用它。如果 key 表示遠端計算機上的鍵，則 file_name 描述的路徑相對於遠端計算機。此方法的呼叫者必須擁有 SeBackupPrivilege 安全許可權。請注意，許可權與許可不同 - 有關更多詳細資訊，請參閱使用者許可權和許可之間的衝突文件。
此函式為 API 傳遞 security_attributes 的
NULL。引發帶有引數
key、file_name的 審計事件winreg.SaveKey。
- winreg.SetValue(key, sub_key, type, value)¶
將值與指定的鍵關聯。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
sub_key 是一個字串，它命名與該值關聯的子鍵。
type 是一個整數，指定資料的型別。目前，這必須是
REG_SZ，這意味著僅支援字串。對於其他資料型別的支援，請使用SetValueEx()函式。value 是一個字串，指定新值。
如果 sub_key 引數指定的鍵不存在，則 SetValue 函式會建立它。
值長度受可用記憶體的限制。長值（超過 2048 位元組）應儲存為檔案，檔名儲存在配置登錄檔中。這有助於登錄檔高效執行。
由 key 引數標識的鍵必須已使用
KEY_SET_VALUE訪問許可權開啟。引發帶有引數
key、sub_key、type、value的 審計事件winreg.SetValue。
- winreg.SetValueEx(key, value_name, reserved, type, value)¶
將資料儲存在開啟的登錄檔鍵的值欄位中。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
value_name 是一個字串，它命名與該值關聯的子鍵。
reserved 可以是任何值 - 始終向 API 傳遞零。
type 是一個整數，指定資料的型別。有關可用型別，請參閱值型別。
value 是一個字串，指定新值。
此方法還可以為指定的鍵設定其他值和型別資訊。由鍵引數標識的鍵必須已使用
KEY_SET_VALUE訪問許可權開啟。要開啟該鍵，請使用
CreateKey()或OpenKey()方法。值長度受可用記憶體的限制。長值（超過 2048 位元組）應儲存為檔案，檔名儲存在配置登錄檔中。這有助於登錄檔高效執行。
引發帶有引數
key、sub_key、type、value的 審計事件winreg.SetValue。
- winreg.DisableReflectionKey(key)¶
停用在 64 位作業系統上執行的 32 位程序的登錄檔反射。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
如果在 32 位作業系統上執行，通常會引發
NotImplementedError。如果該鍵不在反射列表中，則該函式成功，但沒有任何效果。停用某個鍵的反射不會影響任何子鍵的反射。
引發帶有引數
key的 審計事件winreg.DisableReflectionKey。
- winreg.EnableReflectionKey(key)¶
恢復指定的已停用鍵的登錄檔反射。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
如果在 32 位作業系統上執行，通常會引發
NotImplementedError。恢復某個鍵的反射不會影響任何子鍵的反射。
引發帶有引數
key的 審計事件winreg.EnableReflectionKey。
- winreg.QueryReflectionKey(key)¶
確定指定鍵的反射狀態。
key 是一個已開啟的項，或者是一個預定義的 HKEY_* 常量。
如果停用反射，則返回
True。如果在 32 位作業系統上執行，通常會引發
NotImplementedError。引發帶有引數
key的 審計事件winreg.QueryReflectionKey。
常量¶
定義以下常量以用於許多 winreg 函式中。
HKEY_* 常量¶
- winreg.HKEY_CLASSES_ROOT¶
此鍵的從屬登錄檔項定義文件的型別（或類）以及與這些型別關聯的屬性。Shell 和 COM 應用程式使用在此鍵下儲存的資訊。
- winreg.HKEY_CURRENT_USER¶
此鍵的從屬登錄檔項定義當前使用者的首選項。這些首選項包括環境變數的設定、有關程式組、顏色、印表機、網路連線和應用程式首選項的資料。
- winreg.HKEY_LOCAL_MACHINE¶
此鍵的從屬登錄檔項定義計算機的物理狀態，包括有關匯流排型別、系統記憶體和已安裝的硬體和軟體的資料。
- winreg.HKEY_USERS¶
此鍵的從屬登錄檔項定義本地計算機上新使用者的預設使用者配置以及當前使用者的使用者配置。
- winreg.HKEY_PERFORMANCE_DATA¶
此鍵的從屬登錄檔項允許您訪問效能資料。資料實際上不儲存在登錄檔中；登錄檔函式使系統從其來源收集資料。
- winreg.HKEY_CURRENT_CONFIG¶
包含有關本地計算機系統當前硬體配置檔案的資訊。
- winreg.HKEY_DYN_DATA¶
此鍵在 Windows 98 之後的版本中未使用。
訪問許可權¶
更多資訊，請參閱登錄檔項安全和訪問。
- winreg.KEY_ALL_ACCESS¶
結合了 STANDARD_RIGHTS_REQUIRED、
KEY_QUERY_VALUE、KEY_SET_VALUE、KEY_CREATE_SUB_KEY、KEY_ENUMERATE_SUB_KEYS、KEY_NOTIFY和KEY_CREATE_LINK訪問許可權。
- winreg.KEY_WRITE¶
結合了 STANDARD_RIGHTS_WRITE、
KEY_SET_VALUE和KEY_CREATE_SUB_KEY訪問許可權。
- winreg.KEY_READ¶
結合了 STANDARD_RIGHTS_READ、
KEY_QUERY_VALUE、KEY_ENUMERATE_SUB_KEYS和KEY_NOTIFY值。
- winreg.KEY_QUERY_VALUE¶
查詢登錄檔項的值所必需。
- winreg.KEY_SET_VALUE¶
建立、刪除或設定登錄檔值所必需。
- winreg.KEY_CREATE_SUB_KEY¶
建立登錄檔項的子項所必需。
- winreg.KEY_ENUMERATE_SUB_KEYS¶
列舉登錄檔項的子項所必需。
- winreg.KEY_NOTIFY¶
請求登錄檔項或登錄檔項的子項的更改通知所必需。
- winreg.KEY_CREATE_LINK¶
保留供系統使用。
64 位特定¶
更多資訊，請參閱訪問備用登錄檔檢視。
- winreg.KEY_WOW64_64KEY¶
表示 64 位 Windows 上的應用程式應在 64 位登錄檔檢視上操作。在 32 位 Windows 上，此常量將被忽略。
- winreg.KEY_WOW64_32KEY¶
表示 64 位 Windows 上的應用程式應在 32 位登錄檔檢視上操作。在 32 位 Windows 上，此常量將被忽略。
值型別¶
更多資訊，請參閱登錄檔值型別。
- winreg.REG_BINARY¶
任何形式的二進位制資料。
- winreg.REG_DWORD¶
32 位數字。
- winreg.REG_DWORD_BIG_ENDIAN¶
大端格式的 32 位數字。
- winreg.REG_EXPAND_SZ¶
包含對環境變數（
%PATH%）的引用的空終止字串。
- winreg.REG_LINK¶
一個 Unicode 符號連結。
- winreg.REG_MULTI_SZ¶
一系列空終止的字串，以兩個空字元終止。（Python 會自動處理此終止。）
- winreg.REG_NONE¶
未定義的值型別。
- winreg.REG_QWORD¶
64 位數字。
在 3.6 版本中新增。
- winreg.REG_RESOURCE_LIST¶
裝置驅動程式資源列表。
- winreg.REG_FULL_RESOURCE_DESCRIPTOR¶
硬體設定。
- winreg.REG_RESOURCE_REQUIREMENTS_LIST¶
硬體資源列表。
- winreg.REG_SZ¶
一個空終止的字串。
登錄檔控制代碼物件¶
此物件包裝 Windows HKEY 物件，在物件銷燬時自動關閉它。要保證清理，您可以呼叫物件上的 Close() 方法或 CloseKey() 函式。
此模組中的所有登錄檔函式都返回這些物件之一。
此模組中所有接受控制代碼物件的登錄檔函式也接受整數，但是，建議使用控制代碼物件。
控制代碼物件為 __bool__() 提供語義 – 因此
if handle:
print("Yes")
如果控制代碼當前有效（尚未關閉或分離），則會列印 Yes。
該物件還支援比較語義，因此如果控制代碼物件都引用相同的底層 Windows 控制代碼值，則它們將比較為 true。
控制代碼物件可以轉換為整數（例如，使用內建的 int() 函式），在這種情況下，將返回底層 Windows 控制代碼值。您還可以使用 Detach() 方法返回整數控制代碼，並將 Windows 控制代碼與控制代碼物件斷開連線。
- PyHKEY.Close()¶
關閉底層的 Windows 控制代碼。
如果控制代碼已關閉，則不會引發錯誤。
- PyHKEY.Detach()¶
將 Windows 控制代碼與控制代碼物件分離。
結果是一個整數，它儲存控制代碼在分離之前的值。如果控制代碼已分離或關閉，則將返回零。
在呼叫此函式後，控制代碼實際上將失效，但該控制代碼不會關閉。當您需要底層 Win32 控制代碼在控制代碼物件的生命週期之外存在時，您將呼叫此函式。
引發一個 審計事件
winreg.PyHKEY.Detach，引數為key。
- PyHKEY.__enter__()¶
- PyHKEY.__exit__(*exc_info)¶
HKEY 物件實現了
__enter__()和__exit__()，因此支援with語句的上下文協議with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key: ... # work with key
當控制流離開
with程式碼塊時，將自動關閉 key。