Navigation

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.

Changed in version 3.3: Several functions in this module used to raise a
WindowsError, which is now an alias of OSError.

It is not necessary to call FlushKey() to change a key. Registry changes are
flushed to disk by the registry using its lazy flusher. Registry changes are
also flushed to disk at system shutdown. Unlike CloseKey(), the
FlushKey() method returns only when all the data has been written to the
registry. An application should only call FlushKey() if it requires
absolute certainty that registry changes are on disk.

Note

If you don’t know whether a FlushKey() call is required, it probably
isn’t.

file_name is the name of the file to load registry data from. This file must
have been created with the SaveKey() function. Under the file allocation
table (FAT) file system, the filename may not have an extension.

A call to LoadKey() fails if the calling process does not have the
SE_RESTORE_PRIVILEGE privilege. Note that privileges are different
from permissions – see the RegLoadKey documentation for
more details.

If key is a handle returned by ConnectRegistry(), then the path
specified in file_name is relative to the remote computer.

sub_key is a string that holds the name of the subkey with which the value is
associated. If this parameter is None or empty, the function retrieves the
value set by the SetValue() method for the key identified by key.

Values in the registry have name, type, and data components. This method
retrieves the data for a key’s first value that has a NULL name. But the
underlying API call doesn’t return the type, so always use
QueryValueEx() if possible.

file_name is the name of the file to save registry data to. This file
cannot already exist. If this filename includes an extension, it cannot be
used on file allocation table (FAT) file systems by the LoadKey()
method.

If key represents a key on a remote computer, the path described by
file_name is relative to the remote computer. The caller of this method must
possess the SeBackupPrivilege security privilege. Note that
privileges are different than permissions – see the
Conflicts Between User Rights and Permissions documentation
for more details.

sub_key is a string that names the subkey with which the value is associated.

type is an integer that specifies the type of the data. Currently this must be
REG_SZ, meaning only strings are supported. Use the SetValueEx()
function for support for other data types.

value is a string that specifies the new value.

If the key specified by the sub_key parameter does not exist, the SetValue
function creates it.

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.

The key identified by the key parameter must have been opened with
KEY_SET_VALUE access.

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.

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.

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.

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.

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.