Functions¶

This module offers the following functions:

winreg.CloseKey(hkey)¶

Closes a previously opened registry key. Thehkey argument specifies apreviously opened key.

Note

Ifhkey is not closed using this method (or viahkey.Close()), it is closed when thehkey object is destroyed byPython.

winreg.ConnectRegistry(computer_name,key)¶

Establishes a connection to a predefined registry handle on another computer,and returns ahandle object.

computer_name is the name of the remote computer, of the formr"\\computername". IfNone, the local computer is used.

key is the predefined handle to connect to.

The return value is the handle of the opened key. If the function fails, anOSError exception is raised.

Raises anauditing eventwinreg.ConnectRegistry with argumentscomputer_name,key.

Changed in version 3.3:Seeabove.

winreg.CreateKey(key,sub_key)¶

Creates or opens the specified key, returning ahandle object.

key is an already open key, or one of the predefinedHKEY_* constants.

sub_key is a string that names the key this method opens or creates.

Ifkey is one of the predefined keys,sub_key may beNone. In thatcase, 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, anOSError exception is raised.

Raises anauditing eventwinreg.CreateKey with argumentskey,sub_key,access.

Raises anauditing eventwinreg.OpenKey/result with argumentkey.

Changed in version 3.3:Seeabove.

winreg.CreateKeyEx(key,sub_key,reserved=0,access=KEY_WRITE)¶

Creates or opens the specified key, returning ahandle object.

key is an already open key, or one of the predefinedHKEY_* constants.

sub_key is a string that names the key this method opens or creates.

reserved is a reserved integer, and must be zero. The default is zero.

access is an integer that specifies an access mask that describes the desiredsecurity access for the key. Default isKEY_WRITE. SeeAccess Rights for other allowed values.

Ifkey is one of the predefined keys,sub_key may beNone. In thatcase, 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, anOSError exception is raised.

Raises anauditing eventwinreg.CreateKey with argumentskey,sub_key,access.

Raises anauditing eventwinreg.OpenKey/result with argumentkey.

Added in version 3.2.

Changed in version 3.3:Seeabove.

winreg.DeleteKey(key,sub_key)¶

Deletes the specified key.

key is an already open key, or one of the predefinedHKEY_* constants.

sub_key is a string that must be a subkey of the key identified by thekeyparameter. This value must not beNone, and the key may not have subkeys.

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, anOSError exception is raised.

Raises anauditing eventwinreg.DeleteKey with argumentskey,sub_key,access.

Changed in version 3.3:Seeabove.

winreg.DeleteKeyEx(key,sub_key,access=KEY_WOW64_64KEY,reserved=0)¶

Deletes the specified key.

key is an already open key, or one of the predefinedHKEY_* constants.

sub_key is a string that must be a subkey of the key identified by thekey parameter. This value must not beNone, and the key may not havesubkeys.

reserved is a reserved integer, and must be zero. The default is zero.

access is an integer that specifies an access mask that describes thedesired security access for the key. Default isKEY_WOW64_64KEY.On 32-bit Windows, the WOW64 constants are ignored.SeeAccess 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, isremoved. If the method fails, anOSError exception is raised.

On unsupported Windows versions,NotImplementedError is raised.

Raises anauditing eventwinreg.DeleteKey with argumentskey,sub_key,access.

Added in version 3.2.

Changed in version 3.3:Seeabove.

winreg.DeleteValue(key,value)¶

Removes a named value from a registry key.

key is an already open key, or one of the predefinedHKEY_* constants.

value is a string that identifies the value to remove.

Raises anauditing eventwinreg.DeleteValue with argumentskey,value.

winreg.EnumKey(key,index)¶

Enumerates subkeys of an open registry key, returning a string.

key is an already open key, or one of the predefinedHKEY_* constants.

index is an integer that identifies the index of the key to retrieve.

The function retrieves the name of one subkey each time it is called. It istypically called repeatedly until anOSError exception israised, indicating, no more values are available.

Raises anauditing eventwinreg.EnumKey with argumentskey,index.

Changed in version 3.3:Seeabove.

winreg.EnumValue(key,index)¶

Enumerates values of an open registry key, returning a tuple.

key is an already open key, or one of the predefinedHKEY_* constants.

index is an integer that identifies the index of the value to retrieve.

The function retrieves the name of one subkey each time it is called. It istypically called repeatedly, until anOSError exception israised, indicating no more values.

The result is a tuple of 3 items:

Index	Meaning
0	A string that identifies the value name
1	An object that holds the value data, andwhose type depends on the underlyingregistry type
2	An integer that identifies the type of thevalue data (see table in docs forSetValueEx())

Raises anauditing eventwinreg.EnumValue with argumentskey,index.

Changed in version 3.3:Seeabove.

winreg.ExpandEnvironmentStrings(str)¶

Expands environment variable placeholders%NAME% in strings likeREG_EXPAND_SZ:

>>>ExpandEnvironmentStrings('%windir%')'C:\\Windows'

Raises anauditing eventwinreg.ExpandEnvironmentStrings with argumentstr.

winreg.FlushKey(key)¶

Writes all the attributes of a key to the registry.

key is an already open key, or one of the predefinedHKEY_* constants.

It is not necessary to callFlushKey() to change a key. Registry changes areflushed to disk by the registry using its lazy flusher. Registry changes arealso flushed to disk at system shutdown. UnlikeCloseKey(), theFlushKey() method returns only when all the data has been written to theregistry. An application should only callFlushKey() if it requiresabsolute certainty that registry changes are on disk.

Note

If you don’t know whether aFlushKey() call is required, it probablyisn’t.

winreg.LoadKey(key,sub_key,file_name)¶

Creates a subkey under the specified key and stores registration informationfrom a specified file into that subkey.

key is a handle returned byConnectRegistry() or one of the constantsHKEY_USERS orHKEY_LOCAL_MACHINE.

sub_key is a string that identifies the subkey to load.

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

A call toLoadKey() fails if the calling process does not have theSE_RESTORE_PRIVILEGE privilege. Note that privileges are differentfrom permissions – see theRegLoadKey documentation formore details.

Ifkey is a handle returned byConnectRegistry(), then the pathspecified infile_name is relative to the remote computer.

Raises anauditing eventwinreg.LoadKey with argumentskey,sub_key,file_name.

winreg.OpenKey(key,sub_key,reserved=0,access=KEY_READ)¶

winreg.OpenKeyEx(key,sub_key,reserved=0,access=KEY_READ)¶

Opens the specified key, returning ahandle object.

key is an already open key, or one of the predefinedHKEY_* constants.

sub_key is a string that identifies the sub_key to open.

reserved is a reserved integer, and must be zero. The default is zero.

access is an integer that specifies an access mask that describes the desiredsecurity access for the key. Default isKEY_READ. SeeAccessRights for other allowed values.

The result is a new handle to the specified key.

If the function fails,OSError is raised.

Raises anauditing eventwinreg.OpenKey with argumentskey,sub_key,access.

Raises anauditing eventwinreg.OpenKey/result with argumentkey.

Changed in version 3.2:Allow the use of named arguments.

Changed in version 3.3:Seeabove.

winreg.QueryInfoKey(key)¶

Returns information about a key, as a tuple.

key is an already open key, or one of the predefinedHKEY_* constants.

The result is a tuple of 3 items:

Index	Meaning
0	An integer giving the number of sub keysthis key has.
1	An integer giving the number of values thiskey has.
2	An integer giving when the key was lastmodified (if available) as 100’s ofnanoseconds since Jan 1, 1601.

Raises anauditing eventwinreg.QueryInfoKey with argumentkey.

winreg.QueryValue(key,sub_key)¶

Retrieves the unnamed value for a key, as a string.

key is an already open key, or one of the predefinedHKEY_* constants.

sub_key is a string that holds the name of the subkey with which the value isassociated. If this parameter isNone or empty, the function retrieves thevalue set by theSetValue() method for the key identified bykey.

Values in the registry have name, type, and data components. This methodretrieves the data for a key’s first value that has aNULL name. But theunderlying API call doesn’t return the type, so always useQueryValueEx() if possible.

Raises anauditing eventwinreg.QueryValue with argumentskey,sub_key,value_name.

winreg.QueryValueEx(key,value_name)¶

Retrieves the type and data for a specified value name associated withan open registry key.

key is an already open key, or one of the predefinedHKEY_* constants.

value_name is a string indicating the value to query.

The result is a tuple of 2 items:

Index	Meaning
0	The value of the registry item.
1	An integer giving the registry type forthis value (see table in docs forSetValueEx())

Raises anauditing eventwinreg.QueryValue with argumentskey,sub_key,value_name.

winreg.SaveKey(key,file_name)¶

Saves the specified key, and all its subkeys to the specified file.

key is an already open key, or one of the predefinedHKEY_* constants.

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

Ifkey represents a key on a remote computer, the path described byfile_name is relative to the remote computer. The caller of this method mustpossess theSeBackupPrivilege security privilege. Note thatprivileges are different than permissions – see theConflicts Between User Rights and Permissions documentationfor more details.

This function passesNULL forsecurity_attributes to the API.

Raises anauditing eventwinreg.SaveKey with argumentskey,file_name.

winreg.SetValue(key,sub_key,type,value)¶

Associates a value with a specified key.

key is an already open key, or one of the predefinedHKEY_* constants.

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 beREG_SZ, meaning only strings are supported. Use theSetValueEx()function for support for other data types.

value is a string that specifies the new value.

If the key specified by thesub_key parameter does not exist, the SetValuefunction creates it.

Value lengths are limited by available memory. Long values (more than 2048bytes) should be stored as files with the filenames stored in the configurationregistry. This helps the registry perform efficiently.

The key identified by thekey parameter must have been opened withKEY_SET_VALUE access.

Raises anauditing eventwinreg.SetValue with argumentskey,sub_key,type,value.

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 predefinedHKEY_* constants.

value_name is a string that names the subkey with which the value isassociated.

reserved can be anything – zero is always passed to the API.

type is an integer that specifies the type of the data. SeeValue Types for the available types.

value is a string that specifies the new value.

This method can also set additional value and type information for the specifiedkey. The key identified by the key parameter must have been opened withKEY_SET_VALUE access.

To open the key, use theCreateKey() orOpenKey() methods.

Value lengths are limited by available memory. Long values (more than 2048bytes) should be stored as files with the filenames stored in the configurationregistry. This helps the registry perform efficiently.

Raises anauditing eventwinreg.SetValue with argumentskey,sub_key,type,value.

winreg.DisableReflectionKey(key)¶

Disables registry reflection for 32-bit processes running on a 64-bitoperating system.

key is an already open key, or one of the predefinedHKEY_* constants.

Will generally raiseNotImplementedError if executed on a 32-bit operatingsystem.

If the key is not on the reflection list, the function succeeds but has noeffect. Disabling reflection for a key does not affect reflection of anysubkeys.

Raises anauditing eventwinreg.DisableReflectionKey with argumentkey.

winreg.EnableReflectionKey(key)¶

Restores registry reflection for the specified disabled key.

key is an already open key, or one of the predefinedHKEY_* constants.

Will generally raiseNotImplementedError if executed on a 32-bit operatingsystem.

Restoring reflection for a key does not affect reflection of any subkeys.

Raises anauditing eventwinreg.EnableReflectionKey with argumentkey.

winreg.QueryReflectionKey(key)¶

Determines the reflection state for the specified key.

key is an already open key, or one of the predefinedHKEY_* constants.

ReturnsTrue if reflection is disabled.

Will generally raiseNotImplementedError if executed on a 32-bitoperating system.

Raises anauditing eventwinreg.QueryReflectionKey with argumentkey.

Constants¶

The following constants are defined for use in manywinreg functions.

Registry Handle Objects¶

This object wraps a Windows HKEY object, automatically closing it when theobject is destroyed. To guarantee cleanup, you can call either theClose() method on the object, or theCloseKey() function.

All registry functions in this module return one of these objects.

All registry functions in this module which accept a handle object also acceptan integer, however, use of the handle object is encouraged.

Handle objects provide semantics for__bool__() – thus

ifhandle:print("Yes")

will printYes if the handle is currently valid (has not been closed ordetached).

Handle objects can be converted to an integer (e.g., using the built-inint() function), in which case the underlying Windows handle value isreturned. You can also use theDetach() method to return theinteger 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 isdetached. If the handle is already detached or closed, this will returnzero.

After calling this function, the handle is effectively invalidated, but thehandle is not closed. You would call this function when you need theunderlying Win32 handle to exist beyond the lifetime of the handle object.

Raises anauditing eventwinreg.PyHKEY.Detach with argumentkey.

PyHKEY.__enter__()¶

PyHKEY.__exit__(*exc_info)¶

The HKEY object implements__enter__() and__exit__() and thus supports the context protocol for thewith statement:

withOpenKey(HKEY_LOCAL_MACHINE,"foo")askey:...# work with key

will automatically closekey when control leaves thewith block.