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.
34.3.2. Constants
The following constants are defined for use in many _winreg functions.
34.3.2.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.
34.3.2.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.
34.3.2.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.
34.3.2.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. 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.
-
winreg.REG_QWORD_LITTLE_ENDIAN
A 64-bit number in little-endian format. Equivalent to REG_QWORD.
-
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.
34.3.3. 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
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.
-
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.