These functions expose the Windows registry API to Python. Instead of using an
integer as the registry handle, a handle object is used
to ensure that the handles are closed correctly, even if the programmer neglects
to explicitly close them.
-
_winreg.CreateKeyEx(key, sub_key[, res[, sam]])
Creates or opens the specified key, returning a
handle object.
key is an already open key, or one of the predefined
HKEY_* constants.
sub_key is a string that names the key this method opens or creates.
res is a reserved integer, and must be zero. The default is zero.
sam is an integer that specifies an access mask that describes the desired
security access for the key. Default is KEY_ALL_ACCESS. See
Access Rights for other allowed values.
If key is one of the predefined keys, sub_key may be None. In that
case, the handle returned is the same key handle passed in to the function.
If the key already exists, this function opens the existing key.
The return value is the handle of the opened key. If the function fails, a
WindowsError exception is raised.
-
_winreg.DeleteKeyEx(key, sub_key[, sam[, res]])
Deletes the specified key.
key is an already open key, or any one of the predefined
HKEY_* constants.
sub_key is a string that must be a subkey of the key identified by the
key parameter. This value must not be None, and the key may not have
subkeys.
res is a reserved integer, and must be zero. The default is zero.
sam is an integer that specifies an access mask that describes the desired
security access for the key. Default is KEY_WOW64_64KEY. See
Access Rights for other allowed values.
This method can not delete keys with subkeys.
If the method succeeds, the entire key, including all of its values, is
removed. If the method fails, a WindowsError exception is raised.
On unsupported Windows versions, NotImplementedError is raised.
-
_winreg.SetValueEx(key, value_name, reserved, type, value)
Stores data in the value field of an open registry key.
key is an already open key, or one of the predefined
HKEY_* constants.
value_name is a string that names the subkey with which the value is
associated.
type is an integer that specifies the type of the data. See
Value Types for the available types.
reserved can be anything – zero is always passed to the API.
value is a string that specifies the new value.
This method can also set additional value and type information for the specified
key. The key identified by the key parameter must have been opened with
KEY_SET_VALUE access.
To open the key, use the CreateKey() or OpenKey() methods.
Value lengths are limited by available memory. Long values (more than 2048
bytes) should be stored as files with the filenames stored in the configuration
registry. This helps the registry perform efficiently.
35.3.1. Constants
The following constants are defined for use in many _winreg functions.
35.3.1.1. HKEY_* Constants
-
_winreg.HKEY_CLASSES_ROOT
Registry entries subordinate to this key define types (or classes) of
documents and the properties associated with those types. Shell and
COM applications use the information stored under this key.
-
_winreg.HKEY_CURRENT_USER
Registry entries subordinate to this key define the preferences of
the current user. These preferences include the settings of
environment variables, data about program groups, colors, printers,
network connections, and application preferences.
-
_winreg.HKEY_LOCAL_MACHINE
Registry entries subordinate to this key define the physical state
of the computer, including data about the bus type, system memory,
and installed hardware and software.
-
_winreg.HKEY_USERS
Registry entries subordinate to this key define the default user
configuration for new users on the local computer and the user
configuration for the current user.
-
_winreg.HKEY_PERFORMANCE_DATA
Registry entries subordinate to this key allow you to access
performance data. The data is not actually stored in the registry;
the registry functions cause the system to collect the data from
its source.
-
_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.
35.3.1.2. 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.
35.3.1.2.1. 64-bit Specific
For more information, see Accessing an Alternate Registry View.
-
_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.
35.3.1.3. 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.
-
_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_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.
35.3.2. 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 __nonzero__() – thus:
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 (or long on 64 bit Windows) 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.
-
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.