mirror of
https://github.com/python/cpython.git
synced 2024-11-28 20:33:54 +08:00
438 lines
17 KiB
ReStructuredText
438 lines
17 KiB
ReStructuredText
:mod:`winreg` -- Windows registry access
|
|
=========================================
|
|
|
|
.. module:: winreg
|
|
:platform: Windows
|
|
:synopsis: Routines and objects for manipulating the Windows registry.
|
|
.. sectionauthor:: Mark Hammond <MarkH@ActiveState.com>
|
|
|
|
|
|
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.
|
|
|
|
This module exposes a very low-level interface to the Windows registry; it is
|
|
expected that in the future a new ``winreg`` module will be created offering a
|
|
higher-level interface to the registry API.
|
|
|
|
This module offers the following functions:
|
|
|
|
|
|
.. function:: CloseKey(hkey)
|
|
|
|
Closes a previously opened registry key. The hkey argument specifies a
|
|
previously opened key.
|
|
|
|
Note that if *hkey* is not closed using this method (or via
|
|
:meth:`handle.Close`), it is closed when the *hkey* object is destroyed by
|
|
Python.
|
|
|
|
|
|
.. function:: ConnectRegistry(computer_name, key)
|
|
|
|
Establishes a connection to a predefined registry handle on another computer,
|
|
and returns a :dfn:`handle object`
|
|
|
|
*computer_name* is the name of the remote computer, of the form
|
|
``r"\\computername"``. If ``None``, 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, an
|
|
:exc:`EnvironmentError` exception is raised.
|
|
|
|
|
|
.. function:: CreateKey(key, sub_key)
|
|
|
|
Creates or opens the specified key, returning a :dfn:`handle object`
|
|
|
|
*key* is an already open key, or one of the predefined :const:`HKEY_\*`
|
|
constants.
|
|
|
|
*sub_key* is a string that names the key this method opens or creates.
|
|
|
|
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, an
|
|
:exc:`EnvironmentError` exception is raised.
|
|
|
|
|
|
.. function:: DeleteKey(key, sub_key)
|
|
|
|
Deletes the specified key.
|
|
|
|
*key* is an already open key, or any one of the predefined :const:`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.
|
|
|
|
*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, an :exc:`EnvironmentError` exception is raised.
|
|
|
|
|
|
.. function:: DeleteValue(key, value)
|
|
|
|
Removes a named value from a registry key.
|
|
|
|
*key* is an already open key, or one of the predefined :const:`HKEY_\*`
|
|
constants.
|
|
|
|
*value* is a string that identifies the value to remove.
|
|
|
|
|
|
.. function:: EnumKey(key, index)
|
|
|
|
Enumerates subkeys of an open registry key, returning a string.
|
|
|
|
*key* is an already open key, or any one of the predefined :const:`HKEY_\*`
|
|
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 is
|
|
typically called repeatedly until an :exc:`EnvironmentError` exception is
|
|
raised, indicating, no more values are available.
|
|
|
|
|
|
.. function:: EnumValue(key, index)
|
|
|
|
Enumerates values of an open registry key, returning a tuple.
|
|
|
|
*key* is an already open key, or any one of the predefined :const:`HKEY_\*`
|
|
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 is
|
|
typically called repeatedly, until an :exc:`EnvironmentError` exception is
|
|
raised, 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, and |
|
|
| | whose type depends on the underlying |
|
|
| | registry type |
|
|
+-------+--------------------------------------------+
|
|
| ``2`` | An integer that identifies the type of the |
|
|
| | value data |
|
|
+-------+--------------------------------------------+
|
|
|
|
|
|
.. function:: ExpandEnvironmentStrings(unicode)
|
|
|
|
Expands environment strings %NAME% in unicode string like const:`REG_EXPAND_SZ`::
|
|
|
|
>>> ExpandEnvironmentStrings(u"%windir%")
|
|
u"C:\\Windows"
|
|
|
|
|
|
.. function:: FlushKey(key)
|
|
|
|
Writes all the attributes of a key to the registry.
|
|
|
|
*key* is an already open key, or one of the predefined :const:`HKEY_\*`
|
|
constants.
|
|
|
|
It is not necessary to call :func:`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 :func:`CloseKey`, the
|
|
:func:`FlushKey` method returns only when all the data has been written to the
|
|
registry. An application should only call :func:`FlushKey` if it requires
|
|
absolute certainty that registry changes are on disk.
|
|
|
|
.. note::
|
|
|
|
If you don't know whether a :func:`FlushKey` call is required, it probably
|
|
isn't.
|
|
|
|
|
|
.. function:: LoadKey(key, sub_key, file_name)
|
|
|
|
Creates a subkey under the specified key and stores registration information
|
|
from a specified file into that subkey.
|
|
|
|
*key* is an already open key, or any of the predefined :const:`HKEY_\*`
|
|
constants.
|
|
|
|
*sub_key* is a string that identifies the sub_key to load.
|
|
|
|
*file_name* is the name of the file to load registry data from. This file must
|
|
have been created with the :func:`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
|
|
:const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different than
|
|
permissions - see the Win32 documentation for more details.
|
|
|
|
If *key* is a handle returned by :func:`ConnectRegistry`, then the path
|
|
specified in *fileName* is relative to the remote computer.
|
|
|
|
The Win32 documentation implies *key* must be in the :const:`HKEY_USER` or
|
|
:const:`HKEY_LOCAL_MACHINE` tree. This may or may not be true.
|
|
|
|
|
|
.. function:: OpenKey(key, sub_key[, res=0][, sam=KEY_READ])
|
|
|
|
Opens the specified key, returning a :dfn:`handle object`
|
|
|
|
*key* is an already open key, or any one of the predefined :const:`HKEY_\*`
|
|
constants.
|
|
|
|
*sub_key* is a string that identifies the sub_key to open.
|
|
|
|
*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 :const:`KEY_READ`
|
|
|
|
The result is a new handle to the specified key.
|
|
|
|
If the function fails, :exc:`EnvironmentError` is raised.
|
|
|
|
|
|
.. function:: OpenKeyEx()
|
|
|
|
The functionality of :func:`OpenKeyEx` is provided via :func:`OpenKey`, by the
|
|
use of default arguments.
|
|
|
|
|
|
.. function:: QueryInfoKey(key)
|
|
|
|
Returns information about a key, as a tuple.
|
|
|
|
*key* is an already open key, or one of the predefined :const:`HKEY_\*`
|
|
constants.
|
|
|
|
The result is a tuple of 3 items:
|
|
|
|
+-------+---------------------------------------------+
|
|
| Index | Meaning |
|
|
+=======+=============================================+
|
|
| ``0`` | An integer giving the number of sub keys |
|
|
| | this key has. |
|
|
+-------+---------------------------------------------+
|
|
| ``1`` | An integer giving the number of values this |
|
|
| | key has. |
|
|
+-------+---------------------------------------------+
|
|
| ``2`` | An integer giving when the key was last |
|
|
| | modified (if available) as 100's of |
|
|
| | nanoseconds since Jan 1, 1600. |
|
|
+-------+---------------------------------------------+
|
|
|
|
|
|
.. function:: QueryValue(key, sub_key)
|
|
|
|
Retrieves the unnamed value for a key, as a string
|
|
|
|
*key* is an already open key, or one of the predefined :const:`HKEY_\*`
|
|
constants.
|
|
|
|
*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 :func:`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, Lame Lame Lame, DO NOT USE THIS!!!
|
|
|
|
|
|
.. function:: QueryValueEx(key, value_name)
|
|
|
|
Retrieves the type and data for a specified value name associated with an open
|
|
registry key.
|
|
|
|
*key* is an already open key, or one of the predefined :const:`HKEY_\*`
|
|
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 for |
|
|
| | this value. |
|
|
+-------+-----------------------------------------+
|
|
|
|
|
|
.. function:: 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 predefined :const:`HKEY_\*`
|
|
constants.
|
|
|
|
*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 :meth:`LoadKey`, :meth:`ReplaceKey`
|
|
or :meth:`RestoreKey` methods.
|
|
|
|
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 :const:`SeBackupPrivilege` security privilege. Note that
|
|
privileges are different than permissions - see the Win32 documentation for
|
|
more details.
|
|
|
|
This function passes NULL for *security_attributes* to the API.
|
|
|
|
|
|
.. function:: SetValue(key, sub_key, type, value)
|
|
|
|
Associates a value with a specified key.
|
|
|
|
*key* is an already open key, or one of the predefined :const:`HKEY_\*`
|
|
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 be
|
|
:const:`REG_SZ`, meaning only strings are supported. Use the :func:`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
|
|
:const:`KEY_SET_VALUE` access.
|
|
|
|
|
|
.. function:: 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 :const:`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. This should be one
|
|
of the following constants defined in this module:
|
|
|
|
+----------------------------------+---------------------------------------------+
|
|
| Constant | Meaning |
|
|
+==================================+=============================================+
|
|
| :const:`REG_BINARY` | Binary data in any form. |
|
|
+----------------------------------+---------------------------------------------+
|
|
| :const:`REG_DWORD` | A 32-bit number. |
|
|
+----------------------------------+---------------------------------------------+
|
|
| :const:`REG_DWORD_LITTLE_ENDIAN` | A 32-bit number in little-endian format. |
|
|
+----------------------------------+---------------------------------------------+
|
|
| :const:`REG_DWORD_BIG_ENDIAN` | A 32-bit number in big-endian format. |
|
|
+----------------------------------+---------------------------------------------+
|
|
| :const:`REG_EXPAND_SZ` | Null-terminated string containing |
|
|
| | references to environment variables |
|
|
| | (``%PATH%``). |
|
|
+----------------------------------+---------------------------------------------+
|
|
| :const:`REG_LINK` | A Unicode symbolic link. |
|
|
+----------------------------------+---------------------------------------------+
|
|
| :const:`REG_MULTI_SZ` | A sequence of null-terminated strings, |
|
|
| | terminated by two null characters. (Python |
|
|
| | handles this termination automatically.) |
|
|
+----------------------------------+---------------------------------------------+
|
|
| :const:`REG_NONE` | No defined value type. |
|
|
+----------------------------------+---------------------------------------------+
|
|
| :const:`REG_RESOURCE_LIST` | A device-driver resource list. |
|
|
+----------------------------------+---------------------------------------------+
|
|
| :const:`REG_SZ` | A null-terminated string. |
|
|
+----------------------------------+---------------------------------------------+
|
|
|
|
*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
|
|
:const:`KEY_SET_VALUE` access.
|
|
|
|
To open the key, use the :func:`CreateKeyEx` or :func:`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.
|
|
|
|
|
|
.. _handle-object:
|
|
|
|
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
|
|
:meth:`Close` method on the object, or the :func:`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 :meth:`__bool__` - thus ::
|
|
|
|
if handle:
|
|
print("Yes")
|
|
|
|
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 builtin
|
|
:func:`int` function), in which case the underlying Windows handle value is
|
|
returned. You can also use the :meth:`Detach` method to return the integer
|
|
handle, and also disconnect the Windows handle from the handle object.
|
|
|
|
|
|
.. method:: PyHKEY.Close()
|
|
|
|
Closes the underlying Windows handle.
|
|
|
|
If the handle is already closed, no error is raised.
|
|
|
|
|
|
.. method:: 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.
|
|
|
|
.. method:: PyHKEY.__enter__()
|
|
PyHKEY.__exit__(\*exc_info)
|
|
|
|
The HKEY object implements :meth:`__enter__` and :meth:`__exit__` and thus
|
|
supports the context protocol for the :keyword:`with` statement::
|
|
|
|
with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
|
|
# ... work with key ...
|
|
|
|
will automatically close *key* when control leaves the :keyword:`with` block.
|
|
|
|
|