winreg — Windows 登錄檔訪問¶
這些函式將 Windows 登錄檔 API 暴露給 Python。不是使用整數作為登錄檔控制代碼，而是使用控制代碼物件來確保即使程式設計師疏忽未明確關閉控制代碼，控制代碼也能正確關閉。
3.3 版更改: 此模組中的一些函式過去會引發 WindowsError，現在它是 OSError 的別名。
函式¶
此模組提供以下函式
- winreg.CloseKey(hkey)¶
關閉之前開啟的登錄檔項。hkey 引數指定一個之前開啟的鍵。
備註
如果 hkey 未使用此方法（或透過
hkey.Close()）關閉，則當 hkey 物件被 Python 銷燬時，它會自動關閉。
- 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或為空，則函式會檢索由 key 標識的鍵的SetValue()方法設定的值。登錄檔中的值包含名稱、型別和資料元件。此方法檢索鍵的第一個具有
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 安全許可權。請注意，許可權與許可不同——有關更多詳細資訊，請參閱 使用者許可權和許可權之間的衝突文件。
此函式將
NULL傳遞給 API 的 security_attributes。使用引數
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 控制代碼值，它們將比較為真。
控制代碼物件可以轉換為整數（例如，使用內建的 int() 函式），在這種情況下，將返回底層的 Windows 控制代碼值。您也可以使用 Detach() 方法返回整數控制代碼，並同時將 Windows 控制代碼與控制代碼物件分離。
- PyHKEY.Close()¶
關閉底層的 Windows 控制代碼。
如果控制代碼已關閉，則不引發錯誤。
- PyHKEY.Detach()¶
將 Windows 控制代碼與控制代碼物件分離。
結果是一個整數，它儲存了控制代碼分離之前的值。如果控制代碼已分離或關閉，則返回零。
呼叫此函式後，控制代碼實際上會失效，但控制代碼不會關閉。當您需要底層 Win32 控制代碼在控制代碼物件的生命週期之外存在時，您將呼叫此函式。
使用引數
key引發審計事件winreg.PyHKEY.Detach。
- PyHKEY.__enter__()¶
- PyHKEY.__exit__(*exc_info)¶
HKEY 物件實現了
__enter__()和__exit__()，因此支援with語句的上下文協議with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key: ... # work with key
當控制離開
with塊時，將自動關閉 key。