函式¶

This module offers the following functions:

winreg.CloseKey(hkey)¶

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

備註

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.

引發一個附帶引數computer_name、key 的稽核事件winreg.ConnectRegistry。

在 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.

引發一個附帶引數key、sub_key、access 的稽核事件winreg.CreateKey。

引發一個附帶引數key 的稽核事件winreg.OpenKey/result。

在 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.

引發一個附帶引數key、sub_key、access 的稽核事件winreg.CreateKey。

引發一個附帶引數key 的稽核事件winreg.OpenKey/result。

在 3.2 版被加入.

在 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.

引發一個附帶引數key、sub_key、access 的稽核事件winreg.DeleteKey。

在 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.

引發一個附帶引數key、sub_key、access 的稽核事件winreg.DeleteKey。

在 3.2 版被加入.

在 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.

引發一個附帶引數key、value 的稽核事件winreg.DeleteValue。

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.

引發一個附帶引數key、index 的稽核事件winreg.EnumKey。

在 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	含義
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())

引發一個附帶引數key、index 的稽核事件winreg.EnumValue。

在 3.3 版的變更:Seeabove.

winreg.ExpandEnvironmentStrings(str)¶

Expands environment variable placeholders%NAME% in strings likeREG_EXPAND_SZ:

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

引發一個附帶引數str 的稽核事件winreg.ExpandEnvironmentStrings。

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.

備註

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.

引發一個附帶引數key、sub_key、file_name 的稽核事件winreg.LoadKey。

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.

引發一個附帶引數key、sub_key、access 的稽核事件winreg.OpenKey。

引發一個附帶引數key 的稽核事件winreg.OpenKey/result。

在 3.2 版的變更:Allow the use of named arguments.

在 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	含義
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.

引發一個附帶引數key 的稽核事件winreg.QueryInfoKey。

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.

引發一個附帶引數key、sub_key、value_name 的稽核事件winreg.QueryKey。

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	含義
0	The value of the registry item.
1	An integer giving the registry type forthis value (see table in docs forSetValueEx())

引發一個附帶引數key、sub_key、value_name 的稽核事件winreg.QueryKey。

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.

引發一個附帶引數key、file_name 的稽核事件winreg.SaveKey。

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.

引發一個附帶引數key、sub_key、type、value 的稽核事件winreg.SetValue。

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.

引發一個附帶引數key、sub_key、type、value 的稽核事件winreg.SetValue。

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.

引發一個附帶引數key 的稽核事件winreg.DsiableReflectionKey。

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.

引發一個附帶引數key 的稽核事件winreg.EnableReflectionKey。

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.

引發一個附帶引數key 的稽核事件winreg.QueryReflectionKey。

常數¶

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).

The object also support comparison semantics, so handle objects will comparetrue if they both reference the same underlying Windows handle value.

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.

引發一個附帶引數key 的稽核事件winreg.PyHKEY.Detach。

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.