winreg — Windows 注册表访问¶
这些函数将 Windows 注册表 API 公开给 Python。不使用整数作为注册表句柄，而是使用句柄对象来确保正确关闭句柄，即使程序员疏忽忘记显式关闭句柄。
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异常。引发 审核事件
winreg.ConnectRegistry，参数为computer_name、key。版本 3.3 中已更改： 请参阅 上文。
- winreg.CreateKey(key, sub_key)¶
创建或打开指定密钥，返回 句柄对象。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
sub_key 是一个字符串，用于命名此方法打开或创建的密钥。
如果 key 是预定义密钥之一，则 sub_key 可以是
None。在这种情况下，返回的句柄与传递给函数的密钥句柄相同。如果密钥已存在，此函数将打开现有密钥。
返回值是打开密钥的句柄。如果函数失败，则会引发
OSError异常。引发 审核事件
winreg.CreateKey，参数为key、sub_key、access。引发 审核事件
winreg.OpenKey/result，参数为key。版本 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异常。引发 审核事件
winreg.CreateKey，参数为key、sub_key、access。引发 审核事件
winreg.OpenKey/result，参数为key。在版本 3.2 中添加。
版本 3.3 中已更改： 请参阅 上文。
- winreg.DeleteKey(key, sub_key)¶
删除指定的密钥。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
sub_key 是一个字符串，必须是 key 参数标识的密钥的子密钥。此值不得为
None，并且密钥可能没有子密钥。此方法无法删除具有子项的项。
如果方法成功，则会删除整个项，包括其所有值。如果方法失败，则会引发
OSError异常。引发 审核事件
winreg.DeleteKey，其参数为key、sub_key、access。版本 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。引发 审核事件
winreg.DeleteKey，其参数为key、sub_key、access。在版本 3.2 中添加。
版本 3.3 中已更改： 请参阅 上文。
- winreg.DeleteValue(key, value)¶
从注册表项中删除一个已命名的值。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
value 是一个字符串，用于标识要删除的值。
引发 审核事件
winreg.DeleteValue，其参数为key、value。
- winreg.EnumKey(key, index)¶
枚举打开的注册表项的子项，并返回一个字符串。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
index 是一个整数，用于标识要检索的项的索引。
该函数每次调用时都会检索一个子项的名称。通常会重复调用它，直到引发
OSError异常，表示没有更多可用值。引发 审核事件
winreg.EnumKey，其参数为key、index。版本 3.3 中已更改： 请参阅 上文。
- winreg.EnumValue(key, index)¶
枚举打开注册表项的值，返回一个元组。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
index 是一个整数，标识要检索的值的索引。
该函数每次调用时检索一个子项的名称。它通常被重复调用，直到引发
OSError异常，表示没有更多值。结果是一个包含 3 个项的元组
索引
含义
0标识值名称的字符串
1保存值数据且类型取决于底层注册表类型的对象
2标识值数据类型的整数（请参阅
SetValueEx()文档中的表格）引发 审核事件
winreg.EnumValue，其参数为key、index。版本 3.3 中已更改： 请参阅 上文。
- winreg.ExpandEnvironmentStrings(str)¶
扩展字符串中类似
REG_EXPAND_SZ的环境变量占位符%NAME%>>> ExpandEnvironmentStrings('%windir%') 'C:\\Windows'
引发 审核事件
winreg.ExpandEnvironmentStrings，其参数为str。
- 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 中指定路径相对于远程计算机。引发 审计事件
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)¶
打开指定键，返回句柄对象。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
sub_key 是标识要打开的子键的字符串。
reserved 是保留整数，必须为零。默认值为零。
access 是指定访问掩码的整数，该掩码描述了对键的所需安全访问。默认值为
KEY_READ。有关其他允许值，请参见访问权限。结果是指定键的新句柄。
如果函数失败，则会引发
OSError。引发审核事件
winreg.OpenKey，其参数为key、sub_key、access。引发 审核事件
winreg.OpenKey/result，参数为key。在版本 3.2 中更改：允许使用命名参数。
版本 3.3 中已更改： 请参阅 上文。
- winreg.QueryInfoKey(key)¶
以元组形式返回有关键的信息。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
结果是一个包含 3 个项的元组
索引
含义
0一个整数，给出此键拥有的子键数。
1一个整数，给出此键拥有的值数。
2一个整数，给出键上次修改的时间（如果可用），单位为自 1601 年 1 月 1 日起以来的 100 纳秒。
引发审核事件
winreg.QueryInfoKey，其参数为key。
- winreg.QueryValue(key, sub_key)¶
以字符串形式检索键的未命名值。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
sub_key 是一个字符串，其中包含与该值关联的子键的名称。如果此参数为
None或为空，则该函数将检索SetValue()方法为 key 标识的键设置的值。注册表中的值具有名称、类型和数据组件。此方法检索名称为
NULL的键的第一个值的 data。但基础 API 调用不会返回类型，因此如果可能，请始终使用QueryValueEx()。引发 审计事件
winreg.QueryValue，带有参数key、sub_key、value_name。
- winreg.QueryValueEx(key, value_name)¶
检索与打开的注册表键关联的指定值名称的类型和数据。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
value_name 是一个字符串，表示要查询的值。
结果是 2 个项目的元组
索引
含义
0注册表项的值。
1一个整数，给出此值的注册表类型（请参阅
SetValueEx()文档中的表格）引发 审计事件
winreg.QueryValue，带有参数key、sub_key、value_name。
- winreg.SaveKey(key, file_name)¶
将指定的键及其所有子键保存到指定的文件中。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
file_name 是要将注册表数据保存到的文件名。此文件不能已存在。如果此文件名包含扩展名，则
LoadKey()方法无法在文件分配表 (FAT) 文件系统上使用它。如果 key 表示远程计算机上的键，则 file_name 描述的路径相对于远程计算机。此方法的调用者必须拥有 SeBackupPrivilege 安全特权。请注意，特权不同于权限 - 有关更多详细信息，请参阅 用户权限和权限之间的冲突文档。
此函数将
NULL传递给 API 的 security_attributes。引发 审计事件
winreg.SaveKey，其参数为key、file_name。
- winreg.SetValue(key, sub_key, type, value)¶
将一个值与指定键关联。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
sub_key 是一个字符串，用于命名与该值关联的子键。
type 是一个整数，用于指定数据的类型。目前，这必须是
REG_SZ，这意味着仅支持字符串。对于其他数据类型，请使用SetValueEx()函数。value 是一个字符串，用于指定新值。
如果由 sub_key 参数指定的键不存在，则 SetValue 函数会创建该键。
值长度受可用内存的限制。较长的值（超过 2048 个字节）应存储为文件，并将文件名存储在配置注册表中。这有助于注册表高效运行。
由 key 参数标识的键必须使用
KEY_SET_VALUE访问权限打开。引发 审计事件
winreg.SetValue，其参数为key、sub_key、type、value。
- winreg.SetValueEx(key, value_name, reserved, type, value)¶
将数据存储在打开的注册表键的值字段中。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
value_name 是一个字符串，用于命名与该值关联的子键。
reserved 可以是任何内容 - 始终将零传递给 API。
type 是一个整数，用于指定数据的类型。有关可用类型，请参见 值类型。
value 是一个字符串，用于指定新值。
此方法还可以为指定的键设置其他值和类型信息。由 key 参数标识的键必须使用
KEY_SET_VALUE访问权限打开。要打开键，请使用
CreateKey()或OpenKey()方法。值长度受可用内存的限制。较长的值（超过 2048 个字节）应存储为文件，并将文件名存储在配置注册表中。这有助于注册表高效运行。
引发 审计事件
winreg.SetValue，其参数为key、sub_key、type、value。
- winreg.DisableReflectionKey(key)¶
禁用在 64 位操作系统上运行的 32 位进程的注册表反射。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
如果在 32 位操作系统上执行，通常会引发
NotImplementedError。如果键不在反射列表中，则该函数会成功，但不起作用。禁用键的反射不会影响任何子键的反射。
引发 审核事件
winreg.DisableReflectionKey，其参数为key。
- winreg.EnableReflectionKey(key)¶
恢复已禁用键的注册表反射。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
如果在 32 位操作系统上执行，通常会引发
NotImplementedError。恢复键的反射不会影响任何子键的反射。
引发 审核事件
winreg.EnableReflectionKey，其参数为key。
- winreg.QueryReflectionKey(key)¶
确定指定键的反射状态。
key 是已打开的密钥，或预定义 HKEY_* 常量 之一。
如果已禁用反射，则返回
True。如果在 32 位操作系统上执行，通常会引发
NotImplementedError。引发 审核事件
winreg.QueryReflectionKey，其参数为key。
常量¶
定义以下常量，以便在许多 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¶
此键在 98 之后的 Windows 版本中未使用。
访问权限¶
有关更多信息，请参阅 注册表项安全和访问。
- 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%）引用的以 null 结尾的字符串。
- winreg.REG_LINK¶
Unicode 符号链接。
- winreg.REG_MULTI_SZ¶
以两个 null 字符结尾的 null 结尾字符串序列。（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块时，将自动关闭键。