Docs4dev
Docs
python / 2.7.15 / all / library-_winreg.html

35.3. _winreg — Windows 注册表访问

Note

_winreg模块在 Python 3 中已重命名为winreg。2to3工具在将源转换为 Python 3 时将自动适应导入。

2.0 版中的新Function。

这些函数将 Windows 注册表 API 公开给 Python。 handle object用来确保正确关闭了句柄，而不是使用整数作为注册表句柄，即使程序员忽略显式关闭它们也是如此。

该模块提供以下Function：

  • _winreg. CloseKey(* hkey *)
    • 关闭以前打开的注册表项。 * hkey *参数指定先前打开的密钥。

Note

如果没有使用此方法(或passhkey.Close())关闭* hkey ，则在 Python 销毁 hkey *对象时将其关闭。

  • _winreg. ConnectRegistry(* computer_name ， key *)
    • 构建与另一台计算机上的 sched 义注册表句柄的连接，并返回handle object。

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

  • key *是要连接的 sched 义句柄。

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

  • _winreg. CreateKey(* key ， sub_key *)

  • key *是已经打开的键，或者是 sched 义的HKEY_* constants之一。

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

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

如果密钥已经存在，则此Function将打开现有密钥。

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

  • _winreg. CreateKeyEx(* key ， sub_key * [，* res * [，* sam *]])

  • key *是已经打开的键，或者是 sched 义的HKEY_* constants之一。

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

  • res *是保留的整数，必须为零。默认值为零。

  • sam *是一个整数，它指定访问掩码，该访问掩码描述了密钥的所需安全访问。默认值为KEY_ALL_ACCESS。有关其他允许的值，请参见Access Rights。

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

如果密钥已经存在，则此Function将打开现有密钥。

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

2.7 版的新Function。

  • _winreg. DeleteKey(* key ， sub_key *)
    • 删除指定的密钥。

  • key *是已经打开的键，或者是 sched 义的HKEY_* constants之一。

  • sub_key 是一个字符串，必须是 key *参数标识的密钥的子密钥。此值不能为None，并且键不能包含子键。

此方法不能删除带有子键的键.

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

  • _winreg. DeleteKeyEx(* key ， sub_key * [，* sam * [，* res *]])
    • 删除指定的密钥。

Note

DeleteKeyEx()函数pass RegDeleteKeyEx Windows API 函数实现，该函数特定于 Windows 的 64 位版本。参见RegDeleteKeyEx documentation。

  • key *是已经打开的键，或者是 sched 义的HKEY_* constants之一。

  • sub_key 是一个字符串，必须是 key *参数标识的密钥的子密钥。此值不能为None，并且键不能包含子键。

  • res *是保留的整数，必须为零。默认值为零。

  • sam *是一个整数，它指定访问掩码，该访问掩码描述了密钥的所需安全访问。默认值为KEY_WOW64_64KEY。有关其他允许的值，请参见Access Rights。

此方法不能删除带有子键的键.

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

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

2.7 版的新Function。

  • _winreg. DeleteValue(* key ， value *)
    • 从注册表项中删除命名值。

  • key *是已经打开的键，或者是 sched 义的HKEY_* constants之一。

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

  • _winreg. EnumKey(* key ， index *)
    • 枚举打开的注册表项的子项，返回一个字符串。

  • key *是已经打开的键，或者是 sched 义的HKEY_* constants之一。

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

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

  • _winreg. EnumValue(* key ， index *)
    • 枚举打开的注册表项的值，并返回一个 Tuples。

  • key *是已经打开的键，或者是 sched 义的HKEY_* constants之一。

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

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

结果是三个项目的 Tuples：

Index Meaning
0 标识值名称的字符串
1 一个保存值数据的对象，其类型取决于基础注册表类型
2 标识值数据类型的整数(请参阅 docs 中的表SetValueEx())
  • _winreg. ExpandEnvironmentStrings(* unicode *)
    • 以REG_EXPAND_SZ这样的 Unicode 字符串扩展环境变量占位符%NAME%：
>>> ExpandEnvironmentStrings(u"%windir%")
u"C:\\Windows"

2.6 版的新Function。

  • _winreg. FlushKey(* key *)
    • 将键的所有属性写入注册表。

无需致电FlushKey()即可更改密钥。注册表更改pass注册表使用其惰性刷新程序刷新到磁盘。注册表更改还会在系统关闭时刷新到磁盘。与CloseKey()不同，FlushKey()方法仅在所有数据都已写入注册表后才返回。如果应用程序需要绝对确定注册表更改在磁盘上，则应仅调用FlushKey()。

Note

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

  • _winreg. LoadKey(* key ， sub_key ， file_name *)
    • 在指定键下创建一个子键，并将注册信息从指定文件存储到该子键中。

  • key *是由ConnectRegistry()或常量HKEY_USERS或HKEY_LOCAL_MACHINE返回的句柄。

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

  • file_name *是从中加载注册表数据的文件的名称。必须使用SaveKey()函数创建此文件。在文件分配表(FAT)文件系统下，文件名可能没有 extensions。

如果调用进程没有SE_RESTORE_PRIVILEGE特权，则对LoadKey()的调用将失败。请注意，权限与权限不同–请参阅RegLoadKey documentation了解更多详细信息。

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

  • _winreg. OpenKey(* key ， sub_key * [，* res * [，* sam *]])

  • key *是已经打开的键，或者是 sched 义的HKEY_* constants之一。

  • sub_key *是标识要打开的 sub_key 的字符串。

  • res *是保留的整数，必须为零。默认值为零。

  • sam *是一个整数，它指定访问掩码，该访问掩码描述了密钥的所需安全访问。默认值为KEY_READ。有关其他允许的值，请参见Access Rights。

结果是指定键的新句柄。

如果Function失败，则引发WindowsError。

  • _winreg. OpenKeyEx ( )

  • _winreg. QueryInfoKey(* key *)

    • 以 Tuples 的形式返回有关键的信息。

结果是三个项目的 Tuples：

Index Meaning
0 一个整数，给出此键具有的子键的数量。
1 一个整数，给出此键具有的值的数量。
2 自 1601 年 1 月 1 日以来，最后一次修改密钥(如果有)时给出的长整数，为 100 纳秒。
  • _winreg. QueryValue(* key ， sub_key *)
    • 以字符串形式检索键的未命名值。

  • key *是已经打开的键，或者是 sched 义的HKEY_* constants之一。

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

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

  • _winreg. QueryValueEx(* key ， value_name *)
    • 检索与打开的注册表项关联的指定值名称的类型和数据。

  • key *是已经打开的键，或者是 sched 义的HKEY_* constants之一。

  • value_name *是指示要查询的值的字符串。

结果是两个项目的 Tuples：

Index Meaning
0 注册表项的值。
1 给出此值的注册表类型的整数(请参阅 docs 中的表SetValueEx())
  • _winreg. SaveKey(* key ， file_name *)
    • 将指定的键及其所有子键保存到指定的文件中。

  • key *是已经打开的键，或者是 sched 义的HKEY_* constants之一。

  • file_name *是要将注册表数据保存到的文件的名称。该文件不能已经存在。如果此文件名包含 extensions，则无法passLoadKey()方法在文件分配表(FAT)文件系统上使用。

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

此函数将* security_attributes *的 NULL 传递给 API。

  • _winreg. SetValue(* key ， sub_key ， type ， value *)
    • 将值与指定的键关联。

  • key *是已经打开的键，或者是 sched 义的HKEY_* constants之一。

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

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

  • value *是指定新值的字符串。

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

值的长度受可用内存的限制。长值(大于 2048 个字节)应作为文件名存储在配置注册表中。这有助于注册表有效地执行。

  • key *参数标识的密钥必须已passKEY_SET_VALUE访问权限打开。
  • _winreg. SetValueEx(* key ， value_name ， reserved ， type ， value *)
    • 将数据存储在打开的注册表项的 value 字段中。

  • key *是已经打开的键，或者是 sched 义的HKEY_* constants之一。

  • value_name *是一个字符串，用于命名与值关联的子项。

  • type *是一个整数，用于指定数据的类型。有关可用的类型，请参见Value Types。

  • reserved *可以是任何值–始终将零传递给 API。

  • value *是指定新值的字符串。

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

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

值的长度受可用内存的限制。长值(大于 2048 个字节)应作为文件名存储在配置注册表中。这有助于注册表有效地执行。

  • _winreg. DisableReflectionKey(* key *)
    • 对在 64 位 os 上运行的 32 位进程禁用注册表反射。

如果在 32 位 os 上执行，通常会引发NotImplementedError。

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

  • _winreg. EnableReflectionKey(* key *)
    • 恢复指定禁用键的注册表反射。

如果在 32 位 os 上执行，通常会引发NotImplementedError。

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

  • _winreg. QueryReflectionKey(* key *)
    • 确定指定键的反射状态。

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

如果在 32 位 os 上执行，通常会引发NotImplementedError。

35.3.1. Constants

定义了以下常量，以供许多_winreg函数使用。

35.3.1.1. HKEY_ *常数

  • _winreg. HKEY_CLASSES_ROOT

    • 从属于此键的注册表项定义了文档的类型(或类)以及与这些类型关联的属性。 Shell 和 COM 应用程序使用此密钥下存储的信息。

  • _winreg. HKEY_CURRENT_USER

    • 从属于此注册表项的注册表项定义了当前用户的首选项。这些首选项包括环境变量的设置，有关程序组，颜色，打印机，网络连接和应用程序首选项的数据。

  • _winreg. HKEY_LOCAL_MACHINE

    • 属于该键的注册表项定义了计算机的物理状态，包括有关总线类型，系统内存以及已安装的硬件和软件的数据。

  • _winreg. HKEY_USERS

    • 从属于此注册表项的注册表项定义本地计算机上新用户的默认用户配置以及当前用户的用户配置。

  • _winreg. HKEY_PERFORMANCE_DATA

    • 从属于此注册表项的注册表项允许您访问性能数据。数据实际上没有存储在注册表中；注册表Function使系统从其源收集数据。

  • _winreg. HKEY_CURRENT_CONFIG

    • 包含有关本地计算机系统的当前硬件配置文件的信息。

  • _winreg. HKEY_DYN_DATA

    • 98 之后的 Windows 版本不使用此密钥。

35.3.1.2. 访问权限

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

35.3.1.2.1. 特定于 64 位

有关更多信息，请参见访问备用注册表视图。

  • _winreg. KEY_WOW64_64KEY

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

  • _winreg. KEY_WOW64_32KEY

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

35.3.1.3. 值类型

有关更多信息，请参见注册表值类型。

  • _winreg. REG_BINARY

    • 任何形式的二进制数据。

  • _winreg. REG_DWORD

    • 32-bit number.

  • _winreg. REG_DWORD_LITTLE_ENDIAN

    • 小尾数格式的 32 位数字。

  • _winreg. REG_DWORD_BIG_ENDIAN

    • 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

    • 空终止的字符串。

35.3.2. 注册表句柄对象

该对象包装 Windows HKEY 对象，在销毁该对象时自动将其关闭。为了保证清理，您可以在对象上调用Close()方法，也可以调用CloseKey()函数。

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

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

处理对象为nonzero()提供了语义-因此：

if handle:
    print "Yes"

如果手柄当前有效(尚未关闭或分离)，将打印Yes。

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

可以将句柄对象转换为整数(例如，使用内置的int()函数)，在这种情况下，将返回基础 Windows 句柄值。您还可以使用Detach()方法返回整数句柄，也可以将 Windows 句柄与句柄对象断开连接。

  • PyHKEY. Close ( )
    • 关闭基础的 Windows 句柄。

如果句柄已经关闭，则不会引发任何错误。

  • PyHKEY. Detach ( )
    • 从句柄对象分离 Windows 句柄。

结果是一个整数(在 64 位 Windows 上为 long)，在分离之前保存该句柄的值。如果手柄已经分离或关闭，它将返回零。

调用此函数后，该句柄实际上无效，但该句柄未关闭。当需要基础 Win32 句柄在句柄对象的生存期之外存在时，可以调用此函数。

  • PyHKEY. __enter__ ( )
  • PyHKEY. __exit__(** exc_info *) 
with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
    ...  # work with key

当控件离开with块时，它将自动关闭* key *。

2.6 版的新Function。