winreg —- 访问 Windows 注册表

这些函数将 Windows 注册表 API 暴露给 Python。为了确保即便程序员忘机显式关闭时也能够正确关闭，这里没有用整数作为注册表句柄，而是采用了 handle 对象 。

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

函数

该模块提供了下列函数：

winreg.CloseKey(hkey)

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

注解

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

winreg.ConnectRegistry(computer_name, key)

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

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

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

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

引发一个 审计事件 winreg.ConnectRegistry，附带参数 computer_name, key。

在 3.3 版更改: 参考 上文。

winreg.CreateKey(key, sub_key)

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

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)

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

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

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

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

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

如果 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)

删除指定的键。

注解

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

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

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

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

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

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

如果方法成功，则整个键，包括其所有值项都会被移除。如果方法失败，则引发一个 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元素的元组。

引发一个 审计事件 winreg.EnumValue，附带参数 key, index。

在 3.3 版更改: 参考 上文。

winreg.ExpandEnvironmentStrings(str)

Expands environment variable placeholders %NAME% in strings like REG_EXPAND_SZ:

>>> 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）文件系统中，文件名可能不带扩展名。

如果调用 LoadKey() 的进程没有 SE_RESTORE_PRIVILEGE 权限，则调用会失败。请注意，特权与权限不同 —— 更多细节请参阅 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)

打开指定的注册表键，返回 handle对象。

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元素的元组。

触发 审计事件 winreg.QueryInfoKey，附带参数为 key。

winreg.QueryValue(key, sub_key)

读取某键的未命名值，形式为字符串。

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

sub_key 是个字符串，用于保存与某个值相关的子键名称。如果本参数为 None 或空，函数将读取由 SetValue() 方法为 key 键设置的值。

注册表中的值包含名称、类型和数据。本方法将读取注册表键值的第一个名称为 NULL 的数据。可是底层的 API 调用不会返回类型，所以只要有可能就一定要使用 QueryValueEx()。

触发 审计事件 winreg.QueryValue，附带参数为 key、 sub_key 、 value_name。

winreg.QueryValueEx(key, value_name)

读取已打开注册表键指定值名称的类型和数据。

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

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

结果为二元组：

触发 审计事件 winreg.QueryValue，附带参数为 key、 sub_key 、 value_name。

winreg.SaveKey(key, file_name)

将指定注册表键及其所有子键存入指定的文件。

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

file_name 是要保存注册表数据的文件名。该文件不能已存在。如果文件名包括扩展名，也不能在文件分配表（FAT）文件系统中用于 LoadKey() 方法。

如果 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 的总是 0。

type 是个整数，用于指定数据的类型。请参阅 Value Types 了解可用的类型。

value 是设置新值的字符串。

本方法也可为指定的注册表键设置额外的值和类型信息。注册表键必须已用 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

Contains information about the current hardware profile of the local computer system.

winreg.HKEY_DYN_DATA

This key is not used in versions of Windows after 98.

Access Rights

For more information, see Registry Key Security and Access.

winreg.KEY_ALL_ACCESS

Combines the STANDARD_RIGHTS_REQUIRED, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, and KEY_CREATE_LINK access rights.

winreg.KEY_WRITE

Combines the STANDARD_RIGHTS_WRITE, KEY_SET_VALUE, and KEY_CREATE_SUB_KEY access rights.

winreg.KEY_READ

Combines the STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY values.

winreg.KEY_EXECUTE

Equivalent to KEY_READ.

winreg.KEY_QUERY_VALUE

Required to query the values of a registry key.

winreg.KEY_SET_VALUE

Required to create, delete, or set a registry value.

winreg.KEY_CREATE_SUB_KEY

Required to create a subkey of a registry key.

winreg.KEY_ENUMERATE_SUB_KEYS

Required to enumerate the subkeys of a registry key.

winreg.KEY_NOTIFY

Required to request change notifications for a registry key or for subkeys of a registry key.

winreg.KEY_CREATE_LINK

Reserved for system use.

64-bit Specific

For more information, see Accessing an Alternate Registry View.aspx).

winreg.KEY_WOW64_64KEY

Indicates that an application on 64-bit Windows should operate on the 64-bit registry view.

winreg.KEY_WOW64_32KEY

Indicates that an application on 64-bit Windows should operate on the 32-bit registry view.

Value Types

For more information, see Registry Value Types.

winreg.REG_BINARY

Binary data in any form.

winreg.REG_DWORD

32-bit number.

winreg.REG_DWORD_LITTLE_ENDIAN

A 32-bit number in little-endian format. Equivalent to REG_DWORD.

winreg.REG_DWORD_BIG_ENDIAN

A 32-bit number in big-endian format.

winreg.REG_EXPAND_SZ

Null-terminated string containing references to environment variables (%PATH%).

winreg.REG_LINK

A Unicode symbolic link.

winreg.REG_MULTI_SZ

A sequence of null-terminated strings, terminated by two null characters. (Python handles this termination automatically.)

winreg.REG_NONE

No defined value type.

winreg.REG_QWORD

A 64-bit number.

3.6 新版功能.

winreg.REG_QWORD_LITTLE_ENDIAN

A 64-bit number in little-endian format. Equivalent to REG_QWORD.

3.6 新版功能.

winreg.REG_RESOURCE_LIST

A device-driver resource list.

winreg.REG_FULL_RESOURCE_DESCRIPTOR

A hardware setting.

winreg.REG_RESOURCE_REQUIREMENTS_LIST

A hardware resource list.

winreg.REG_SZ

A null-terminated string.

Registry Handle Objects

This object wraps a Windows HKEY object, automatically closing it when the object is destroyed. To guarantee cleanup, you can call either the Close() method on the object, or the CloseKey() function.

All registry functions in this module return one of these objects.

All registry functions in this module which accept a handle object also accept an integer, however, use of the handle object is encouraged.

Handle objects provide semantics for __bool__() — thus

if handle:
    print("Yes")

will print Yes if the handle is currently valid (has not been closed or detached).

The object also support comparison semantics, so handle objects will compare true if they both reference the same underlying Windows handle value.

Handle objects can be converted to an integer (e.g., using the built-in int() function), in which case the underlying Windows handle value is returned. You can also use the Detach() method to return the integer handle, and also disconnect the Windows handle from the handle object.

PyHKEY.Close()

Closes the underlying Windows handle.

If the handle is already closed, no error is raised.

PyHKEY.Detach()

Detaches the Windows handle from the handle object.

The result is an integer that holds the value of the handle before it is detached. If the handle is already detached or closed, this will return zero.

After calling this function, the handle is effectively invalidated, but the handle is not closed. You would call this function when you need the underlying Win32 handle to exist beyond the lifetime of the handle object.

引发一个 审计事件 winreg.PyHKEY.Detach，附带参数 key。

PyHKEY.__enter__()

PyHKEY.__exit__(*exc_info)

The HKEY object implements __enter__() and __exit__() and thus supports the context protocol for the with statement:

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

will automatically close key when control leaves the with block.