winreg
---Windows注册表访问¶
这些函数向Python公开Windows注册表API。不是使用整数作为注册表句柄,而是 handle object 用于确保句柄正确关闭,即使程序员忽略了显式关闭它们。
在 3.3 版更改: 此模块中用于引发 WindowsError
,现在是的别名 OSError
.
功能¶
本模块提供以下功能:
- winreg.CloseKey(hkey)¶
关闭以前打开的注册表项。这个 hkey 参数指定以前打开的键。
注解
如果 hkey 未使用此方法关闭(或通过
hkey.Close()
,当 hkey 对象被python销毁。
- winreg.ConnectRegistry(computer_name, key)¶
建立到另一台计算机上的预定义注册表句柄的连接,并返回 handle object .
computer_name 是远程计算机的名称,格式为
r"\\computername"
. 如果None
,使用本地计算机。key 是要连接的预定义句柄。
返回值是打开的键的句柄。如果函数失败,则
OSError
引发异常。提出一个 auditing event
winreg.ConnectRegistry
带着论据computer_name
,key
.在 3.3 版更改: 见 above .
- winreg.CreateKey(key, sub_key)¶
创建或打开指定的键,返回 handle object .
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
sub_key 为该方法打开或创建的键命名的字符串。
如果 key 是预定义的键之一, sub_key 可能是
None
. 在这种情况下,返回的句柄与传递给函数的密钥句柄相同。如果密钥已经存在,此函数将打开现有密钥。
返回值是打开的键的句柄。如果函数失败,则
OSError
引发异常。提出一个 auditing event
winreg.CreateKey
带着论据key
,sub_key
,access
.提出一个 auditing event
winreg.OpenKey/result
带着论证key
.在 3.3 版更改: 见 above .
- winreg.CreateKeyEx(key, sub_key, reserved=0, access=KEY_WRITE)¶
创建或打开指定的键,返回 handle object .
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
sub_key 为该方法打开或创建的键命名的字符串。
保留的 是保留整数,必须为零。默认值为零。
接近 是一个整数,它指定一个访问掩码,用于描述密钥所需的安全访问。默认是
KEY_WRITE
. 见 Access Rights 其他允许值。如果 key 是预定义的键之一, sub_key 可能是
None
. 在这种情况下,返回的句柄与传递给函数的密钥句柄相同。如果密钥已经存在,此函数将打开现有密钥。
返回值是打开的键的句柄。如果函数失败,则
OSError
引发异常。提出一个 auditing event
winreg.CreateKey
带着论据key
,sub_key
,access
.提出一个 auditing event
winreg.OpenKey/result
带着论证key
.3.2 新版功能.
在 3.3 版更改: 见 above .
- winreg.DeleteKey(key, sub_key)¶
删除指定的密钥。
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
sub_key 是一个字符串,该字符串必须是由 key 参数。此值不能是
None
,键可能没有子键。此方法无法删除具有子项的键。
如果方法成功,则会删除整个键,包括其所有值。如果方法失败,则
OSError
引发异常。提出一个 auditing event
winreg.DeleteKey
带着论据key
,sub_key
,access
.在 3.3 版更改: 见 above .
- winreg.DeleteKeyEx(key, sub_key, access=KEY_WOW64_64KEY, reserved=0)¶
删除指定的密钥。
注解
这个
DeleteKeyEx()
函数是用RegDeleteKeyEx Windows API函数实现的,该函数是特定于64位版本的Windows的。见 RegDeleteKeyEx documentation _.key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
sub_key 是一个字符串,该字符串必须是由 key 参数。此值不能是
None
,键可能没有子键。保留的 是保留整数,必须为零。默认值为零。
接近 是一个整数,它指定一个访问掩码,用于描述密钥所需的安全访问。默认是
KEY_WOW64_64KEY
. 见 Access Rights 其他允许值。此方法无法删除具有子项的键。
如果方法成功,则会删除整个键,包括其所有值。如果方法失败,则
OSError
引发异常。在不支持的Windows版本上,
NotImplementedError
提高了。提出一个 auditing event
winreg.DeleteKey
带着论据key
,sub_key
,access
.3.2 新版功能.
在 3.3 版更改: 见 above .
- winreg.DeleteValue(key, value)¶
从注册表项中删除命名值。
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
value 标识要删除的值的字符串。
提出一个 auditing event
winreg.DeleteValue
带着论据key
,value
.
- winreg.EnumKey(key, index)¶
枚举打开的注册表项的子项,返回字符串。
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
index 是标识要检索的键的索引的整数。
函数每次调用一个子项时都会检索它的名称。它通常重复调用,直到
OSError
引发异常,表示没有其他值可用。提出一个 auditing event
winreg.EnumKey
带着论据key
,index
.在 3.3 版更改: 见 above .
- winreg.EnumValue(key, index)¶
枚举打开的注册表项的值,返回元组。
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
index 是标识要检索值的索引的整数。
函数每次调用一个子项时都会检索它的名称。它通常重复调用,直到
OSError
引发异常,表示没有其他值。结果是一个由3个项组成的元组:
索引
意义
0
标识值名称的字符串
1
保存值数据的对象,其类型取决于基础注册表类型
2
标识值数据类型的整数(参见文档中的表
SetValueEx()
)提出一个 auditing event
winreg.EnumValue
带着论据key
,index
.在 3.3 版更改: 见 above .
- winreg.ExpandEnvironmentStrings(str)¶
扩展环境变量占位符
%NAME%
弦乐般REG_EXPAND_SZ
::>>> ExpandEnvironmentStrings('%windir%') 'C:\\Windows'
提出一个 auditing event
winreg.ExpandEnvironmentStrings
带着论证str
.
- winreg.FlushKey(key)¶
将项的所有属性写入注册表。
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
不必调用
FlushKey()
换钥匙。注册表使用其惰性刷新器将注册表更改刷新到磁盘。注册表更改也会在系统关闭时刷新到磁盘。不像CloseKey()
, theFlushKey()
方法仅在所有数据都已写入注册表时返回。应用程序只应调用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 documentation _了解更多详细信息。如果 key 句柄是否由返回
ConnectRegistry()
,然后是中指定的路径 file_name 相对于远程计算机。提出一个 auditing event
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 object .
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
sub_key 是标识要打开的子密钥的字符串。
保留的 是保留整数,必须为零。默认值为零。
接近 是一个整数,它指定一个访问掩码,用于描述密钥所需的安全访问。默认是
KEY_READ
. 见 Access Rights 其他允许值。结果是指定键的新句柄。
如果功能失效,
OSError
提高了。提出一个 auditing event
winreg.OpenKey
带着论据key
,sub_key
,access
.提出一个 auditing event
winreg.OpenKey/result
带着论证key
.在 3.2 版更改: 允许使用命名参数。
在 3.3 版更改: 见 above .
- winreg.QueryInfoKey(key)¶
以元组形式返回有关键的信息。
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
结果是一个由3个项组成的元组:
索引
意义
0
一个整数,给出该键的子键数。
1
一个整数,给出该键的值的数目。
2
自1601年1月1日起,最后一次修改密钥(如果可用)时的整数,为100纳秒。
提出一个 auditing event
winreg.QueryInfoKey
带着论证key
.
- winreg.QueryValue(key, sub_key)¶
以字符串形式检索键的未命名值。
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
sub_key 保存与值关联的子项的名称的字符串。如果此参数是
None
或为空,函数检索SetValue()
密钥的标识方法 key .注册表中的值具有名称、类型和数据组件。此方法检索具有
NULL
名字。但是底层的API调用不返回类型,所以总是使用QueryValueEx()
如果可能的话。提出一个 auditing event
winreg.QueryValue
带着论据key
,sub_key
,value_name
.
- winreg.QueryValueEx(key, value_name)¶
检索与打开的注册表项关联的指定值名称的类型和数据。
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
value_name 指示要查询的值的字符串。
结果是两个项目的元组:
索引
意义
0
注册表项的值。
1
为该值提供注册表类型的整数(请参见文档中的表
SetValueEx()
)提出一个 auditing event
winreg.QueryValue
带着论据key
,sub_key
,value_name
.
- winreg.SaveKey(key, file_name)¶
将指定的键及其所有子键保存到指定的文件中。
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
file_name 是要将注册表数据保存到的文件的名称。此文件不能已经存在。如果此文件名包含扩展名,则不能由
LoadKey()
方法。如果 key 表示远程计算机上的密钥,路径由 file_name 相对于远程计算机。此方法的调用方必须拥有
SeBackupPrivilege
安全特权。请注意,特权与权限不同--请参见 Conflicts Between User Rights and Permissions documentation _了解更多详细信息。此函数通过
NULL
对于 security_attributes 到API。提出一个 auditing event
winreg.SaveKey
带着论据key
,file_name
.
- winreg.SetValue(key, sub_key, type, value)¶
将值与指定的键关联。
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
sub_key 是一个字符串,用于命名与值关联的子项。
type 是指定数据类型的整数。目前这必须是
REG_SZ
,表示只支持字符串。使用SetValueEx()
用于支持其他数据类型的函数。value 是指定新值的字符串。
如果键由 sub_key 参数不存在,由setValue函数创建。
值长度受可用内存限制。长值(超过2048字节)应存储为文件,文件名存储在配置注册表中。这有助于注册表高效执行。
密钥由 key 参数必须已用打开
KEY_SET_VALUE
访问。提出一个 auditing event
winreg.SetValue
带着论据key
,sub_key
,type
,value
.
- winreg.SetValueEx(key, value_name, reserved, type, value)¶
在打开的注册表项的值字段中存储数据。
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
value_name 是一个字符串,用于命名与值关联的子项。
保留的 可以是任何东西——零总是传递给API。
type 是指定数据类型的整数。见 Value Types 对于可用类型。
value 是指定新值的字符串。
此方法还可以设置指定键的附加值和类型信息。密钥参数标识的密钥必须已用打开
KEY_SET_VALUE
访问。要打开钥匙,请使用
CreateKey()
或OpenKey()
方法。值长度受可用内存限制。长值(超过2048字节)应存储为文件,文件名存储在配置注册表中。这有助于注册表高效执行。
提出一个 auditing event
winreg.SetValue
带着论据key
,sub_key
,type
,value
.
- winreg.DisableReflectionKey(key)¶
为在64位操作系统上运行的32位进程禁用注册表反射。
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
一般会提高
NotImplementedError
如果在32位操作系统上执行。如果该键不在反射列表中,则函数成功,但不起作用。为键禁用反射不会影响任何子键的反射。
提出一个 auditing event
winreg.DisableReflectionKey
带着论证key
.
- winreg.EnableReflectionKey(key)¶
还原指定的禁用项的注册表反射。
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
一般会提高
NotImplementedError
如果在32位操作系统上执行。恢复键的反射不会影响任何子键的反射。
提出一个 auditing event
winreg.EnableReflectionKey
带着论证key
.
- winreg.QueryReflectionKey(key)¶
确定指定键的反射状态。
key 是一个已经打开的密钥,或者是一个预定义的 HKEY_* constants .
返回
True
如果反射被禁用。一般会提高
NotImplementedError
如果在32位操作系统上执行。提出一个 auditing event
winreg.QueryReflectionKey
带着论证key
.
常量¶
以下常量是为在许多 _winreg
功能。
hkey_ux常量¶
- 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版本中不使用此密钥。
访问权限¶
有关详细信息,请参阅 Registry Key Security and Access _.
- winreg.KEY_ALL_ACCESS¶
结合所需的标准权限,
KEY_QUERY_VALUE
,KEY_SET_VALUE
,KEY_CREATE_SUB_KEY
,KEY_ENUMERATE_SUB_KEYS
,KEY_NOTIFY
和KEY_CREATE_LINK
访问权限。
- winreg.KEY_WRITE¶
结合了标准的权限写入,
KEY_SET_VALUE
和KEY_CREATE_SUB_KEY
访问权限。
- winreg.KEY_READ¶
结合标准的读取权限,
KEY_QUERY_VALUE
,KEY_ENUMERATE_SUB_KEYS
和KEY_NOTIFY
价值观。
- 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位专用¶
有关详细信息,请参阅 Accessing an Alternate Registry View _.
- winreg.KEY_WOW64_64KEY¶
指示64位Windows上的应用程序应在64位注册表视图上操作。
- winreg.KEY_WOW64_32KEY¶
指示64位Windows上的应用程序应在32位注册表视图上操作。
价值类型¶
有关详细信息,请参阅 Registry Value Types _.
- winreg.REG_BINARY¶
任何形式的二进制数据。
- winreg.REG_DWORD¶
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_QWORD¶
64位数字。
3.6 新版功能.
- winreg.REG_RESOURCE_LIST¶
设备驱动程序资源列表。
- winreg.REG_FULL_RESOURCE_DESCRIPTOR¶
硬件设置。
- winreg.REG_RESOURCE_REQUIREMENTS_LIST¶
硬件资源列表。
- winreg.REG_SZ¶
以空结尾的字符串。
注册表句柄对象¶
此对象封装一个Windows HKEY对象,当该对象被破坏时自动将其关闭。为了保证清理,您可以调用 Close()
对象上的方法,或 CloseKey()
功能。
此模块中的所有注册表函数都返回其中一个对象。
此模块中接受handle对象的所有注册表函数也接受整数,但是鼓励使用handle对象。
handle对象为 __bool__()
-因此::
if handle:
print("Yes")
将打印 Yes
如果句柄当前有效(尚未关闭或分离)。
对象还支持比较语义,因此,如果句柄对象都引用相同的底层Windows句柄值,那么它们将比较true。
句柄对象可以转换为整数(例如,使用内置的 int()
函数),在这种情况下,将返回基础的Windows句柄值。您也可以使用 Detach()
方法返回整数句柄,同时断开Windows句柄与句柄对象的连接。
- PyHKEY.Close()¶
关闭基础窗口句柄。
如果句柄已关闭,则不会引发任何错误。
- PyHKEY.Detach()¶
从句柄对象分离Windows句柄。
结果是一个整数,它在分离句柄之前保存句柄的值。如果句柄已分离或关闭,则返回零。
调用此函数后,句柄将有效地失效,但句柄不会关闭。当需要基础的win32句柄在句柄对象的生存期之外存在时,可以调用此函数。
提出一个 auditing event
winreg.PyHKEY.Detach
带着论证key
.
- PyHKEY.__enter__()¶
- PyHKEY.__exit__(*exc_info)¶
hkey对象实现
__enter__()
和__exit__()
从而支持with
声明:with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key: ... # work with key
将自动关闭 key 当控件离开时
with
块。