35.3. _winreg — Windows 注册表访问 — Python 文档

35.3. _winreg — Windows 注册表访问

笔记

_winreg 模块已在 Python 3 中重命名为 winreg。 2to3 工具将在将您的源代码转换为 Python 3 时自动调整导入。

2.0 版中的新功能。

这些函数将 Windows 注册表 API 公开给 Python。 不是使用整数作为注册表句柄，而是使用 句柄对象 来确保句柄正确关闭，即使程序员忽略了显式关闭它们。

该模块提供以下功能：

_winreg.CloseKey(hkey)

关闭以前打开的注册表项。 hkey 参数指定先前打开的密钥。

笔记

如果 hkey 未使用此方法关闭（或通过 hkey.Close()），则在 hkey 对象被 Python 销毁时关闭。

_winreg.ConnectRegistry(computer_name, key)

与另一台计算机上的预定义注册表句柄建立连接，并返回 句柄对象 。

computer_name 是远程计算机的名称，格式为 r"\\computername"。 如果是 None，则使用本地计算机。

key 是要连接的预定义句柄。

返回值是打开的键的句柄。 如果函数失败，则会引发 WindowsError 异常。

_winreg.CreateKey(key, sub_key)

创建或打开指定的键，返回 句柄对象 。

key 是一个已经打开的密钥，或者是预定义的 HKEY_* 常量 之一。

sub_key 是一个字符串，用于命名此方法打开或创建的密钥。

如果key是预定义键之一，则sub_key可以是None。 在这种情况下，返回的句柄与传递给函数的键句柄相同。

如果密钥已经存在，该函数会打开现有的密钥。

返回值是打开的键的句柄。 如果函数失败，则会引发 WindowsError 异常。

_winreg.CreateKeyEx(key, sub_key[, res[, sam]])

创建或打开指定的键，返回 句柄对象 。

key 是一个已经打开的密钥，或者是预定义的 HKEY_* 常量 之一。

sub_key 是一个字符串，用于命名此方法打开或创建的密钥。

res 是保留整数，必须为零。 默认值为零。

sam 是一个整数，它指定了一个访问掩码，该掩码描述了密钥所需的安全访问。 默认值为 KEY_ALL_ACCESS。 有关其他允许的值，请参阅 访问权限 。

如果key是预定义键之一，则sub_key可以是None。 在这种情况下，返回的句柄与传递给函数的键句柄相同。

如果密钥已经存在，该函数会打开现有的密钥。

返回值是打开的键的句柄。 如果函数失败，则会引发 WindowsError 异常。

2.7 版中的新功能。

_winreg.DeleteKey(key, sub_key)

删除指定的键。

key 是一个已经打开的密钥，或者任何一个预定义的 HKEY_* 常量。

sub_key 是一个字符串，必须是由 key 参数标识的密钥的子密钥。 这个值不能是None，并且键不能有子键。

此方法不能删除带有子键的键。

如果该方法成功，则删除整个键，包括其所有值。 如果该方法失败，则会引发 WindowsError 异常。

_winreg.DeleteKeyEx(key, sub_key[, sam[, res]])

删除指定的键。

笔记

DeleteKeyEx() 函数是使用 RegDeleteKeyEx Windows API 函数实现的，该函数特定于 64 位版本的 Windows。 请参阅 RegDeleteKeyEx 文档 。

key 是一个已经打开的密钥，或者任何一个预定义的 HKEY_* 常量。

sub_key 是一个字符串，必须是由 key 参数标识的密钥的子密钥。 这个值不能是None，并且键不能有子键。

res 是保留整数，必须为零。 默认值为零。

sam 是一个整数，它指定了一个访问掩码，该掩码描述了密钥所需的安全访问。 默认值为 KEY_WOW64_64KEY。 有关其他允许的值，请参阅 访问权限 。

此方法不能删除带有子键的键。

如果该方法成功，则删除整个键，包括其所有值。 如果该方法失败，则会引发 WindowsError 异常。

在不受支持的 Windows 版本上，会引发 NotImplementedError。

2.7 版中的新功能。

_winreg.DeleteValue(key, value)

从注册表项中删除命名值。

key 是一个已经打开的密钥，或者是预定义的 HKEY_* 常量 之一。

value 是一个字符串，用于标识要删除的值。

_winreg.EnumKey(key, index)

枚举打开的注册表项的子项，返回一个字符串。

key 是一个已经打开的密钥，或者任何一个预定义的 HKEY_* 常量。

index 是一个整数，用于标识要检索的键的索引。

每次调用该函数时，它都会检索一个子项的名称。 它通常会重复调用，直到引发 WindowsError 异常，表明没有更多值可用。

_winreg.EnumValue(key, index)

枚举打开的注册表项的值，返回一个元组。

key 是一个已经打开的密钥，或者任何一个预定义的 HKEY_* 常量。

index 是一个整数，用于标识要检索的值的索引。

每次调用该函数时，它都会检索一个子项的名称。 它通常被重复调用，直到引发 WindowsError 异常，表明没有更多值。

结果是一个包含 3 个项目的元组：

指数	意义
0	标识值名称的字符串
1	保存值数据的对象，其类型取决于基础注册表类型
2	标识值数据类型的整数（请参阅 SetValueEx() 文档中的表格）

_winreg.ExpandEnvironmentStrings(unicode)

在 unicode 字符串中扩展环境变量占位符 %NAME%，如 REG_EXPAND_SZ：

>>> ExpandEnvironmentStrings(u"%windir%")
u"C:\\Windows"

2.6 版中的新功能。

_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.OpenKey(key, sub_key[, res[, sam]])

打开指定的键，返回 句柄对象 。

key 是一个已经打开的密钥，或者任何一个预定义的 HKEY_* 常量。

sub_key 是一个字符串，用于标识要打开的 sub_key。

res 是保留整数，必须为零。 默认值为零。

sam 是一个整数，它指定了一个访问掩码，该掩码描述了密钥所需的安全访问。 默认值为 KEY_READ。 有关其他允许的值，请参阅 访问权限 。

结果是指定键的新句柄。

如果该函数失败，则会引发 WindowsError。

_winreg.OpenKeyEx()

OpenKeyEx() 的功能是通过 OpenKey() 提供的，使用默认参数。

_winreg.QueryInfoKey(key)

以元组形式返回有关键的信息。

key 是一个已经打开的密钥，或者是预定义的 HKEY_* 常量 之一。

结果是一个包含 3 个项目的元组：

指数	意义
0	一个整数，给出此键具有的子键数。
1	一个整数，给出此键具有的值的数量。
2	一个长整数，表示自 1601 年 1 月 1 日以来最后一次修改密钥的时间（如果可用）为 100 纳秒。

_winreg.QueryValue(key, sub_key)

以字符串形式检索键的未命名值。

key 是一个已经打开的密钥，或者是预定义的 HKEY_* 常量 之一。

sub_key 是一个字符串，其中包含与该值关联的子键的名称。 如果此参数为 None 或为空，则该函数检索由 SetValue() 方法为由 key 标识的键设置的值。

注册表中的值具有名称、类型和数据组件。 此方法检索具有 NULL 名称的键的第一个值的数据。 但是底层 API 调用不返回类型，因此如果可能，请始终使用 QueryValueEx()。

_winreg.QueryValueEx(key, value_name)

检索与打开的注册表项关联的指定值名称的类型和数据。

key 是一个已经打开的密钥，或者是预定义的 HKEY_* 常量 之一。

value_name 是一个字符串，表示要查询的值。

结果是一个包含 2 个项目的元组：

指数	意义
0	注册表项的值。
1	给出此值的注册表类型的整数（请参阅 SetValueEx() 文档中的表格）

_winreg.SaveKey(key, file_name)

将指定的键及其所有子键保存到指定的文件中。

key 是一个已经打开的密钥，或者是预定义的 HKEY_* 常量 之一。

file_name 是保存注册表数据的文件名。 该文件不能已经存在。 如果此文件名包含扩展名，则无法通过 LoadKey() 方法在文件分配表 (FAT) 文件系统上使用它。

如果 key 代表远程计算机上的密钥，则 file_name 描述的路径是相对于远程计算机的。 此方法的调用者必须拥有 SeBackupPrivilege 安全权限。 请注意，特权与权限不同——有关详细信息，请参阅 用户权限和权限之间的冲突文档。

此函数将 security_attributes 的 NULL 传递给 API。

_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.SetValueEx(key, value_name, reserved, type, value)

将数据存储在打开的注册表项的值字段中。

key 是一个已经打开的密钥，或者是预定义的 HKEY_* 常量 之一。

value_name 是一个字符串，用于命名与值关联的子键。

type 是指定数据类型的整数。 有关可用类型，请参阅 值类型 。

reserved 可以是任何东西——零总是传递给 API。

value 是指定新值的字符串。

此方法还可以为指定的键设置附加值和类型信息。 由 key 参数标识的密钥必须已使用 KEY_SET_VALUE 访问权限打开。

要打开密钥，请使用 CreateKey() 或 OpenKey() 方法。

值长度受可用内存限制。 长值（超过 2048 字节）应作为文件存储，文件名存储在配置注册表中。 这有助于注册表有效地执行。

_winreg.DisableReflectionKey(key)

禁用在 64 位操作系统上运行的 32 位进程的注册表反射。

key 是一个已经打开的密钥，或者是预定义的 HKEY_* 常量 之一。

如果在 32 位操作系统上执行，通常会引发 NotImplementedError。

如果键不在反射列表中，则该函数成功但无效。 禁用键的反射不会影响任何子键的反射。

_winreg.EnableReflectionKey(key)

恢复指定禁用键的注册表反射。

key 是一个已经打开的密钥，或者是预定义的 HKEY_* 常量 之一。

如果在 32 位操作系统上执行，通常会引发 NotImplementedError。

恢复键的反射不会影响任何子键的反射。

_winreg.QueryReflectionKey(key)

确定指定键的反射状态。

key 是一个已经打开的密钥，或者是预定义的 HKEY_* 常量 之一。

如果禁用反射，则返回 True。

如果在 32 位操作系统上执行，通常会引发 NotImplementedError。

35.3.1. 常数

以下常量定义用于许多 _winreg 函数。

35.3.1.1. 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 版本中不使用此密钥。

35.3.1.2. 访问权限

有关详细信息，请参阅 注册表密钥安全和访问 。

_winreg.KEY_ALL_ACCESS

结合 STANDARD_RIGHTS_REQUIRED, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEY1X], KEY_ENUMERATE_SUB_KEY1X], [YRENUMERATE_SUB_KEY1X],[YRENUMERATE_SUB_KEY1X1X],[YRENUMERATE_SUB_KEY1X1X],[YR_ENUMERATE_SUB_KEY1X], KEY_SET_VALUE X195X] 访问权限。

_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_EXECUTE

相当于 KEY_READ。

_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

保留供系统使用。

35.3.1.2.1。 64 位专用

有关详细信息，请参阅 访问备用注册表视图 。

_winreg.KEY_WOW64_64KEY

指示 64 位 Windows 上的应用程序应在 64 位注册表视图上运行。

_winreg.KEY_WOW64_32KEY

指示 64 位 Windows 上的应用程序应在 32 位注册表视图上运行。

35.3.1.3. 值类型

有关详细信息，请参阅 注册表值类型 。

_winreg.REG_BINARY

任何形式的二进制数据。

_winreg.REG_DWORD

32 位数字。

_winreg.REG_DWORD_LITTLE_ENDIAN

小端格式的 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_RESOURCE_LIST

设备驱动程序资源列表。

_winreg.REG_FULL_RESOURCE_DESCRIPTOR

一个硬件设置。

_winreg.REG_RESOURCE_REQUIREMENTS_LIST

硬件资源列表。

_winreg.REG_SZ

以空字符结尾的字符串。

35.3.2. 注册表句柄对象

这个对象包装了一个 Windows HKEY 对象，当对象被销毁时自动关闭它。 为了保证清理，您可以调用对象上的 Close() 方法或 CloseKey() 函数。

此模块中的所有注册表函数都返回这些对象之一。

该模块中接受句柄对象的所有注册表函数也接受整数，但是，鼓励使用句柄对象。

句柄对象为 __nonzero__() 提供语义——因此：

if handle:
    print "Yes"

如果手柄当前有效（尚未关闭或分离），将打印 Yes。

该对象还支持比较语义，因此如果句柄对象都引用相同的底层 Windows 句柄值，它们将比较为真。

句柄对象可以转换为整数（例如，使用内置的 int() 函数），在这种情况下，将返回底层 Windows 句柄值。 您还可以使用 Detach() 方法返回整数句柄，也可以断开 Windows 句柄与句柄对象的连接。

PyHKEY.Close()

关闭底层 Windows 句柄。

如果句柄已经关闭，则不会引发错误。

PyHKEY.Detach()

从句柄对象中分离 Windows 句柄。

结果是一个整数（或在 64 位 Windows 上为 long），它在分离之前保存句柄的值。 如果手柄已经分离或关闭，这将返回零。

调用此函数后，句柄有效失效，但句柄并未关闭。 当您需要基础 Win32 句柄存在于句柄对象的生命周期之外时，您将调用此函数。

PyHKEY.__enter__()
PyHKEY.__exit__(\*exc_info)

HKEY 对象实现了 __enter__() 和 __exit__()，因此支持 with 语句的上下文协议：

with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
    ...  # work with key

当控制离开和块时，将自动关闭键。

2.6 版中的新功能。