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 版改变： 见 above .

winreg. CreateKey ( key , sub_key ) ¶

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

key 是已打开键，或某一预定义 HKEY_* 常量 .

sub_key 是由此方法打开或创建的键名称字符串。

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

若键已存在，此函数打开现有键。

返回值是打开键的句柄。若函数失败， OSError 异常被引发。

3.3 版改变： 见 above .

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 版改变： 见 above .

winreg. DeleteKey ( key , sub_key ) ¶

删除指定键。

key 是已打开键，或某一预定义 HKEY_* 常量 .

sub_key 是必须为键子键的字符串，标识通过 key 参数。此值不得为 None ，且键可能没有子键。

此方法无法删除带子键的键。

若方法成功，整个键 (包括其所有值) 被移除。若方法失败， OSError 异常被引发。

3.3 版改变： 见 above .

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 版改变： 见 above .

winreg. DeleteValue ( key , value ) ¶

从注册表键移除命名值。

key 是已打开键，或某一预定义 HKEY_* 常量 .

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

winreg. EnumKey ( key , index ) ¶

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

key 是已打开键，或某一预定义 HKEY_* 常量 .

index 是要检索的键索引标识整数。

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

3.3 版改变： 见 above .

winreg. EnumValue ( key , index ) ¶

枚举打开注册表键的值，返回元组。

key 是已打开键，或某一预定义 HKEY_* 常量 .

index 是要检索的值索引标识整数。

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

结果是 3 项元组：

索引	含义
0	标识值名称的字符串
1	保持值数据的对象，且其类型取决于底层注册表类型
2	标识值数据类型的整数 (见文档表格为 SetValueEx() )

3.3 版改变： 见 above .

winreg. ExpandEnvironmentStrings ( str ) ¶

展开环境变量占位符 %NAME% 以字符串像 REG_EXPAND_SZ :

>>> 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 or HKEY_LOCAL_MACHINE .

sub_key 是要加载的子键标识字符串。

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

调用 LoadKey() 失败若调用进程不拥有 SE_RESTORE_PRIVILEGE 特权。注意：特权不同于权限 – 见 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 是要打开的 sub_key 的标识字符串。

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

access 是指定访问掩码 (描述键期望的安全访问) 的整数。默认为 KEY_READ 。见 访问权限 了解其它允许值。

结果是指定键的新句柄。

若函数失败， OSError 被引发。

3.2 版改变： 允许使用命名自变量。

3.3 版改变： 见 above .

winreg. QueryInfoKey ( key ) ¶

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

key 是已打开键，或某一预定义 HKEY_* 常量 .

结果是 3 项元组：

索引	含义
0	给出此键拥有的子键数的整数。
1	给出此键拥有值数量的整数。
2	按 100 纳秒给出从 1601 年 1 月 1 日起最后修改键的时间 (若有的话) 的整数。

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 是要保存注册表数据的文件名。文件不能已存在。若文件名包含扩展名，它不能用于 FAT (文件分配表) 文件系统中通过 LoadKey() 方法。

若 key 表示远程计算机中的键，路径供述通过 file_name 相对远程计算机。此方法的调用者必须具备 SeBackupPrivilege 安全特权。注意：特权不同于权限 – 见 用户权利和权限之间冲突的文档编制 了解更多细节。

此函数传递 NULL 为 security_attributes 到 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 参数必须已打开采用 KEY_SET_VALUE 访问。

要打开键，使用 CreateKey() or OpenKey() 方法。

值长度受限于可用内存。长值 (超过 2048 字节) 应采用存储于配置注册表中的文件名按文件存储。这有助于注册表高效履行。

winreg. DisableReflectionKey ( key ) ¶

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

key 是已打开键，或某一预定义 HKEY_* 常量 .

一般来说会引发 NotImplemented 若执行在 32 位操作系统。

若键不在反射列表中，函数会成功但没有效果。禁用键的反射不会影响任何子键的反射。

winreg. EnableReflectionKey ( key ) ¶

还原指定禁用键的注册表反射。

key 是已打开键，或某一预定义 HKEY_* 常量 .

一般来说会引发 NotImplemented 若执行在 32 位操作系统。

还原键的反射不会影响任何子键的反射。

winreg. QueryReflectionKey ( key ) ¶

确定指定键的反射状态。

key 是已打开键，或某一预定义 HKEY_* 常量 .

返回 True 若反射被禁用。

一般来说会引发 NotImplemented 若执行在 32 位操作系统。

34.3.2. 常量 ¶

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

34.3.3. 注册表句柄对象 ¶

此对象包裹 Windows HKEY 对象，被自动关闭当对象被销毁时。要保证清理，可以调用 Close() 方法在对象，或 CloseKey() 函数。

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

此模块中接受句柄对象的所有注册表函数还接受整数，不管怎样，鼓励使用句柄对象。

句柄对象提供语义为 __bool__() – 因此

if handle:
    print("Yes")
								

将打印 Yes 若句柄目前有效 (尚未被关闭或分离)。

对象还支持比较语义，因此，若句柄对象引用相同的底层 Windows 句柄值，那么比较它们将为 True。

可以将句柄对象转换为整数 (如：使用内置 int() 函数)，在此情况下，返回底层 Windows 句柄值。还可以使用 Detach() 方法以返回整数句柄，及断开 Windows 句柄和句柄对象之间的连接。

PyHKEY. Close ( ) ¶

关闭底层 Windows 句柄。

若句柄已经关闭，不会引发错误。

PyHKEY. Detach ( ) ¶

从句柄对象分离 Windows 句柄。

结果是在分离之前保存句柄值的整数。若句柄已分离或被关闭，这将返回 0。

在调用此函数后，句柄实际上无效，但句柄尚未关闭。将调用此函数，当需要底层 Win32 句柄存在于句柄对象生命周期之外时。

PyHKEY. __enter__ ( ) ¶

PyHKEY. __exit__ ( *exc_info ) ¶

HKEY 对象实现 __enter__() and __exit__() 因此支持上下文协议对于 with 语句：

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

将自动关闭 key 当控件离开 with 块。