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。