python内在模块之winreg --- Windows 注册表访问

winreg --- Windows 注册表访问¶

---

这些函数将 Windows 注册表 API 暴露给 Python。为了确保即便程序员忽略了显式关闭句柄，该句柄依然能够正确关闭，它使用了一个 handle 对象 而不是整数来作为注册表句柄。

在 3.3 版更改: 该模块中的几个函数被用于引发 WindowsError，该异常现在是 OSError 的别名。

函数

该模块提供了下列函数：

winreg.CloseKey( hkey ) 

关闭之前打开的注册表键。参数 hkey 指之前打开的键。

注解

 

如果没有使用该方法关闭 hkey (或者通过 hkey.Close())，在对象 hkey 被 Python 销毁时会将其关闭。

winreg.ConnectRegistry(计算机名,键) 

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

computer_name 是远程计算机的名称，以 r"\\computername" 的形式。如果是 None ，将会使用本地计算机。

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

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

在 3.3 版更改: 参考 上文。

winreg.CreateKey（键，子键）

创建或打开特定的键，返回一个 handle 对象。

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

sub_key 是用于命名该方法所打开或创建的键的字符串。

如果 key 是预定义键之一，sub_key 可能会是 None。该情况下，返回的句柄就是传入函数的句柄。

如果键已经存在，则该函数打开已经存在的该键。

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

在 3.3 版更改: 参考 上文。

winreg.CreateKeyEx( key , sub_key , reserved=0 , access=KEY_WRITE ) 

创建或打开特定的键，返回一个 handle 对象。

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

sub_key 是用于命名该方法所打开或创建的键的字符串。

reserved 是一个保留的证书，必须是零。默认值为零。

access 为一个整数，用于给键的预期安全访问指定访问掩码。默认值为 KEY_WRITE。 参阅 Access Rights 了解其它允许值。

如果 key 是预定义键之一，sub_key 可能会是 None。该情况下，返回的句柄就是传入函数的句柄。

如果键已经存在，则该函数打开已经存在的该键。

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

3.2 新版功能.

在 3.3 版更改: 参考 上文。

winreg.DeleteKey（键，子键）

删除指定的键。

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

sub_key 这个字符串必须是由 key 参数所指定键的一个子项。该值项不可以是 None，同时键也不可以有子项。

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

如果方法成功，则整个键，包括其所有值项都会被移除。如果方法失败，则引发一个 OSError 异常。

在 3.3 版更改: 参考 上文。

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

删除指定的键。

注解

 

函数 DeleteKeyEx() 通过 RegDeleteKeyEx 这个 Windows API 函数实现，该函数为 Windows 的64位版本专属。 参阅 RegDeleteKeyEx 文档。

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

sub_key 这个字符串必须是由 key 参数所指定键的一个子项。该值项不可以是 None，同时键也不可以有子项。

reserved 是一个保留的证书，必须是零。默认值为零。

access 为一个整数，用于给键的预期安全访问指定访问掩码。默认值为常量 _WOW64_64KEY 。参阅 Access Rights 了解其它允许值。

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

如果方法成功，则整个键，包括其所有值项都会被移除。如果方法失败，则引发一个 OSError 异常。

在不支持的 Windows 版本之上，将会引发 NotImplementedError 异常。

3.2 新版功能.

在 3.3 版更改: 参考 上文。

winreg.DeleteValue（键，值）

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

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

value 为标识所要删除值项的字符串。

winreg.EnumKey（键，索引）

列举某个已经打开注册表键的子项，并返回一个字符串。

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

index 为一个整数，用于标识所获取键的索引。

每次调用该函数都会获取一个子项的名字。通常它会被反复调用，直到引发 OSError 异常，这说明已经没有更多的可用值了。

在 3.3 版更改: 参考 上文。

winreg.EnumValue（键，索引）

列举某个已经打开注册表键的值项，并返回一个元组。

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

index 为一个整数，用于标识要获取值项的索引。

每次调用该函数都会获取一个子项的名字。通常它会被反复调用，直到引发 OSError 异常，这说明已经没有更多的可用值了。

结果为3元素的元组。

索引	含义
0	用于标识值项名称的字符串。
1	保存值项数据的对象，其类型取决于背后的注册表类型。
2	标识值项数据类型的整数。（请查阅 SetValueEx() 文档中的表格）

在 3.3 版更改: 参考 上文。

winreg.ExpandEnvironmentStrings( str ) 

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

>>>

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

winreg.FlushKey（关键）

将某个键的所有属性写入注册表。

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

无需调用FlushKey()即可更改密钥。注册表更改由注册表使用其惰性刷新器刷新到磁盘。注册表更改也会在系统关闭时刷新到磁盘。与 不同CloseKey()的是，该 FlushKey()方法仅在所有数据都已写入注册表时才返回。只有当应用程序FlushKey()需要绝对确定注册表更改在磁盘上时，它才应该调用。

注解

 

如果您不知道是否需要FlushKey()调用，则可能不需要。

winreg.LoadKey（键，子键，文件名）

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

keyConnectRegistry()是由常量 HKEY_USERS或其中一个返回的句柄HKEY_LOCAL_MACHINE。

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

file_name是要从中加载注册表数据的文件的名称。这个文件必须是用SaveKey()函数创建的。在文件分配表 (FAT) 文件系统下，文件名可能没有扩展名。

LoadKey()如果调用进程没有 SE_RESTORE_PRIVILEGE权限，则调用失败。请注意，权限与权限不同——有关更多详细信息，请参阅RegLoadKey 文档。

如果key是返回的句柄，则file_nameConnectRegistry()中指定的路径是相对于远程计算机的。

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

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

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

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

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

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

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

结果是指定键的新句柄。

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

在 3.2 版更改: Allow the use of named arguments.

在 3.3 版更改: 参考 上文。

winreg.QueryInfoKey（关键）

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

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

结果为3元素的元组。

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

winreg.QueryValue（键，子键）

检索键的未命名值，作为字符串。

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

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

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

winreg.QueryValueEx（键，值名称）

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

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

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

结果是 2 个项目的元组：

索引	含义
0	注册表项的值。
1	一个整数，给出该值的注册表类型（参见文档中的表格 SetValueEx()）

winreg.SaveKey（键，文件名）

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

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

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

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

此函数将security_attributesNULL传递给API。

winreg.SetValue（键，子键，类型，值）

将值与指定的键相关联。

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

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

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

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

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

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

由key参数标识的密钥必须已通过 KEY_SET_VALUE访问权限打开。

winreg.SetValueEx（键，值名称，保留，类型，值）

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

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

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

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

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

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

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

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

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

winreg.DisableReflectionKey（关键）

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

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

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

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

winreg.EnableReflectionKey（关键）

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

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

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

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

winreg.QueryReflectionKey（关键）

确定指定键的反射状态。

key 为某个已经打开的键，或者预定义的 HKEY_* 常量 之一。

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

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

常量

定义了以下常量以在许多_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_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

保留供系统使用。

64 位特定

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

winreg.KEY_WOW64_64KEY

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

winreg.KEY_WOW64_32KEY

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

值类型

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

winreg.REG_BINARY

任何形式的二进制数据。

winreg.REG_DWORD

32 位数字。

winreg.REG_DWORD_LITTLE_ENDIAN

小端格式的 32 位数字。相当于REG_DWORD。

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_QWORD_LITTLE_ENDIAN

little-endian 格式的 64 位数字。相当于REG_QWORD。

3.6 新版功能.

winreg.REG_RESOURCE_LIST

设备驱动程序资源列表。

winreg.REG_FULL_RESOURCE_DESCRIPTOR

硬件设置。

winreg.REG_RESOURCE_REQUIREMENTS_LIST

硬件资源列表。

winreg.REG_SZ

一个以 null 结尾的字符串。

注册表句柄对象

这个对象包装了一个 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