_winreg

_winreg - Windows注册表访问

注意

该_winreg模块已被重命名为winregPython 3. 当将源代码转换为Python 3时，2to3工具将自动适应导入。

2.0版本中的新功能。

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

该模块提供以下功能：

_winreg.CloseKey(hkey)

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

注意

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

_winreg.ConnectRegistry(computer_name, key)

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

computer_name是远程计算机的名称，形式为r“\\ computername”。 如果没有，则使用本地计算机。

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

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

_winreg.CreateKey(key, sub_key)

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

键 是一个已经打开的键，或者是一个预定义的HKEY_ *常量。

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

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

如果密钥已经存在，该功能将打开现有密钥。

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

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

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

键 是一个已经打开的键，或者是一个预定义的HKEY_ *常量。

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

res 是一个保留整数，并且必须为零。默认值为零。

sam 是一个整数，用于指定描述所需密钥安全访问的访问掩码。默认是KEY_ALL_ACCESS。请参阅访问权限获取其他允许的值。

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

如果密钥已经存在，该功能将打开现有密钥。

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

2.7版本的新功能。

_winreg.DeleteKey(key, sub_key)

删除指定的密钥。

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

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

此方法不能使用子密钥删除密钥。

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

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

删除指定的密钥。

注意

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

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

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

res 是一个保留整数，并且必须为零。默认值为零。

sam 是一个整数，用于指定描述所需密钥安全访问的访问掩码。默认是KEY_WOW64_64KEY。请参阅访问权限获取其他允许的值。

此方法不能使用子密钥删除密钥。

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

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

2.7版本的新功能。

_winreg.DeleteValue(key, value)

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

键 是一个已经打开的键，或者是一个预定义的HKEY_ *常量。

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

_winreg.EnumKey(key, index)

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

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

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

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

_winreg.EnumValue(key, index)

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

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

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

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

结果是3个元素的元组：

_winreg.ExpandEnvironmentStrings(unicode)

在REG_EXPAND_SZ之类的unicode字符串中展开环境变量占位符％NAME％：

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

2.6版本中的新功能。

_winreg.FlushKey(key)

将密钥的所有属性写入注册表。

键 是一个已经打开的键，或者是一个预定义的HKEY_ *常量。

没有必要调用FlushKey（）来更改一个键。 注册表使用其懒惰的冲洗程序将注册表更改刷新到磁盘。 在系统关闭时，注册表更改也会刷新到磁盘。 与CloseKey（）不同，FlushKey（）方法仅在所有数据写入注册表时才返回。 如果需要绝对确定注册表更改在磁盘上，则应用程序应仅调用FlushKey（）。

注意

如果您不知道是否需要FlushKey()拨打电话，那可能不是。

_winreg.LoadKey(key, sub_key, file_name)

在指定的密钥下创建一个子密钥，并将来自指定文件的注册信息存储到该子密钥中。

键是由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]])

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

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

sub_key是标识要打开的子键的字符串。

res是一个保留整数，并且必须为零。默认值为零。

sam是一个整数，用于指定描述所需密钥安全访问的访问掩码。默认是KEY_READ。请参阅访问权限获取其他允许的值。

结果是指定键的新句柄。

如果该功能失败，则引发WindowsError。

_winreg.OpenKeyEx()

OpenKeyEx（）的功能是通过使用默认参数通过OpenKey（）提供的。

_winreg.QueryInfoKey(key)

将元素的信息作为元组返回。

键 是一个已经打开的键，或者是一个预定义的HKEY_ *常量。

结果是3个元素的元组：

_winreg.QueryValue(key, sub_key)

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

键 是一个已经打开的键，或者是一个预定义的HKEY_ *常量。

sub_key是一个字符串，它保存与该值关联的子键的名称。如果此参数为None或为空，则该函数将检索由SetValue()按键标识的密钥的方法设置的值。

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

_winreg.QueryValueEx(key, value_name)

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

键 是一个已经打开的键，或者是一个预定义的HKEY_ *常量。

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

结果是2个元素的元组：

_winreg.SaveKey(key, file_name)

将指定的密钥及其所有子密钥保存到指定的文件。

键 是一个已经打开的键，或者是一个预定义的HKEY_ *常量。

file_name是保存注册表数据的文件的名称。 这个文件不可能已经存在。 如果此文件名包含扩展名，则它不能在LoadKey（）方法的文件分配表（FAT）文件系统上使用。

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

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

_winreg.SetValue(key, sub_key, type, value)

将值与指定的键关联。

键 是一个已经打开的键，或者是一个预定义的HKEY_ *常量。

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

type是一个指定数据类型的整数。 目前这必须是REG_SZ，这意味着只支持字符串。 使用SetValueEx（）函数来支持其他数据类型。

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

如果由sub_key参数指定的键不存在，则SetValue函数会创建它。

值的长度受可用内存的限制。长值（超过2048字节）应该以文件形式存储在配置注册表中。这有助于注册表高效地执行。

密钥参数标识的密钥必须已经用KEY_SET_VALUE访问权限打开。

_winreg.SetValueEx(key, value_name, reserved, type, value)

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

键 是一个已经打开的键，或者是一个预定义的HKEY_ *常量。

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

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

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

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

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

要打开该键，请使用CreateKey（）或OpenKey（）方法。

值的长度受可用内存的限制。长值（超过2048字节）应该以文件形式存储在配置注册表中。这有助于注册表高效地执行。

_winreg.DisableReflectionKey(key)

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

键 是一个已经打开的键，或者是一个预定义的HKEY_ *常量。

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

如果该键不在反射列表中，则该功能成功但不起作用。禁用键的反射不会影响任何子键的反射。

_winreg.EnableReflectionKey(key)

为指定的禁用密钥恢复注册表反射。

键是一个已经打开的键，或者是一个预定义的HKEY_ *常量。

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

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

_winreg.QueryReflectionKey(key)

确定指定键的反射状态。

键 是一个已经打开的键，或者是一个预定义的HKEY_ *常量。

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

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

1.常量

下面的常量被定义用于许多_winreg函数。

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版本。

1.2 访问权

有关更多信息，请参阅注册表项安全和访问。

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

保留供系统使用。

1.2.1 64位具体

有关更多信息，请参阅访问备用注册表视图（http://msdn.microsoft.com/zh-cn/library/aa384129（v = VS.85％29.aspx）。

_winreg.KEY_WOW64_64KEY

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

_winreg.KEY_WOW64_32KEY

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

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

以空字符结尾的字符串。

2.注册表处理对象

该对象包装Windows HKEY对象，当对象被销毁时自动关闭它。 为了保证清理，可以调用对象的Close（）方法或CloseKey（）函数。

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

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

处理对象提供语义__nonzero__()- 因此：

if handle:
    print "Yes"

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

该对象还支持比较语义，因此如果句柄对象都引用相同的基础Windows句柄值，则句柄对象将进行比较。

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

PyHKEY.Close()

关闭底层的Windows句柄。

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

PyHKEY.Detach()

从句柄对象分离Windows句柄。

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

调用此函数后，句柄实际上失效，但句柄未关闭。当需要底层Win32句柄在句柄对象的生命周期之外存在时，您可以调用此函数。

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

HKEY对象实现__enter __（）和__exit __（），因此支持with语句的上下文协议：

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

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

2.6版本中的新功能。