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。