34.3. winreg — Windows注册表访问¶

34.3.1. 功能¶

该模块提供以下功能：

winreg.CloseKey(hkey)¶

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

注解

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

winreg.ConnectRegistry(computer_name, key)¶

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

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

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

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

在 3.3 版更改: 见 以上。

winreg.CreateKey(key, sub_key)¶

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

key 是已经打开的键，或者是预定义的 HKEY_ *常数 之一。

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

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

如果键已经存在，则此函数将打开现有键。

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

在 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 异常。

3.2 新版功能.

在 3.3 版更改: 见 以上。

winreg.DeleteKey(key, sub_key)¶

删除指定的键。

key 是已经打开的键，或者是预定义的 HKEY_ *常数 之一。

sub_key 是一个字符串，它必须是由 key 参数标识的键的子项。此值不能为 None，并且键可能没有子键。

此方法无法使用子项删除键。

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

在 3.3 版更改: 见 以上。

winreg.DeleteKeyEx(key, sub_key, access=KEY_WOW64_64KEY, reserved=0)¶

删除指定的键。

注解

DeleteKeyEx() 函数通过RegDeleteKeyEx Windows API函数实现，该函数特定于64位版本的Windows。见 RegDeleteKeyEx文档。

key 是已经打开的键，或者是预定义的 HKEY_ *常数 之一。

sub_key 是一个字符串，它必须是由 key 参数标识的键的子项。此值不能为 None，并且键可能没有子键。

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

access 是一个整数，指定描述密钥所需的安全访问的访问掩码。默认值为 KEY_WOW64_64KEY。其他允许值请参见 访问权。

此方法无法使用子项删除键。

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

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

3.2 新版功能.

在 3.3 版更改: 见 以上。

winreg.DeleteValue(key, value)¶

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

key 是已经打开的键，或者是预定义的 HKEY_ *常数 之一。

value 是标识要删除的值的字符串。

winreg.EnumKey(key, index)¶

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

key 是已经打开的键，或者是预定义的 HKEY_ *常数 之一。

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

该函数在每次被调用时检索一个子键的名称。它通常被重复调用，直到引发 OSError 异常，指示没有更多的值可用。

在 3.3 版更改: 见 以上。

winreg.EnumValue(key, index)¶

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

key 是已经打开的键，或者是预定义的 HKEY_ *常数 之一。

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

该函数在每次被调用时检索一个子键的名称。它通常被重复调用，直到引发 OSError 异常，指示没有更多的值。

结果是3个项目的元组：

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

在 3.3 版更改: 见 以上。

winreg.ExpandEnvironmentStrings(str)¶

在像 REG_EXPAND_SZ 的字符串中扩展环境变量占位符 %NAME%:

>>> ExpandEnvironmentStrings('%windir%')
'C:\\Windows'

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, reserved=0, access=KEY_READ)¶

winreg.OpenKeyEx(key, sub_key, reserved=0, access=KEY_READ)¶

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

key 是已经打开的键，或者是预定义的 HKEY_ *常数 之一。

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

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

access 是一个整数，指定描述密钥所需的安全访问的访问掩码。默认值为 KEY_READ。其他允许值请参见 访问权。

结果是指定键的新句柄。

如果函数失败，则引发 OSError。

在 3.2 版更改: 允许使用命名参数。

在 3.3 版更改: 见 以上。

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 是一个字符串，用于命名与该值相关联的子项。

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

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

value 是一个指定新值的字符串。

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

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

值长度受可用内存的限制。长整型值（大于2048字节）应存储为文件名，该文件名存储在配置注册表中。这有助于注册表执行效率。

winreg.DisableReflectionKey(key)¶

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

key 是已经打开的键，或者是预定义的 HKEY_ *常数 之一。

如果在32位操作系统上执行，通常会产生 NotImplemented。

如果键不在反射列表上，则函数将成功但不起作用。禁用键的反射不会影响任何子键的反映。

winreg.EnableReflectionKey(key)¶

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

key 是已经打开的键，或者是预定义的 HKEY_ *常数 之一。

如果在32位操作系统上执行，通常会产生 NotImplemented。

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

winreg.QueryReflectionKey(key)¶

确定指定键的反射状态。

key 是已经打开的键，或者是预定义的 HKEY_ *常数 之一。

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

如果在32位操作系统上执行，通常会产生 NotImplemented。

34.3.2. 常量¶

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

34.3.3. 注册表处理对象¶

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

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

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

句柄对象提供 __bool__() 的语义 - 因此

if handle:
    print("Yes")

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

对象也支持比较语义，所以句柄对象将比较真如果他们都引用相同的底层Windows句柄值。

句柄对象可以转换为整数（例如，使用内置的 int() 函数），在这种情况下返回基础Windows句柄值。您还可以使用 Detach() 方法返回整数句柄，并且还从句柄对象中断开Windows句柄。

PyHKEY.Close()¶

关闭基础Windows句柄。

如果句柄已经关闭，则不会产生错误。

PyHKEY.Detach()¶

从句柄对象分离Windows句柄。

结果是一个整数，在分离之前保存句柄的值。如果句柄已经被分离或关闭，这将返回零。

调用此函数后，句柄被有效地无效，但句柄未关闭。当您需要底层的Win32句柄存在超过句柄对象的生命周期时，您将调用此函数。

PyHKEY.__enter__()¶

PyHKEY.__exit__(*exc_info)¶

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

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

将在控制离开 with 块时自动关闭 key。