diff --git a/Doc/library/winreg.rst b/Doc/library/winreg.rst index 0ab24105636..cc0313fb2b3 100644 --- a/Doc/library/winreg.rst +++ b/Doc/library/winreg.rst @@ -12,10 +12,6 @@ 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: @@ -24,9 +20,9 @@ This module offers the following functions: 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. + .. note:: + If *hkey* is not closed using this method (or via :meth:`hkey.Close() `), + it is closed when the *hkey* object is destroyed by Python. .. function:: ConnectRegistry(computer_name, key) @@ -48,8 +44,8 @@ This module offers the following functions: Creates or opens the specified key, returning a :ref:`handle object `. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants `. *sub_key* is a string that names the key this method opens or creates. @@ -66,8 +62,8 @@ This module offers the following functions: Deletes the specified key. - *key* is an already open key, or any one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`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. @@ -82,8 +78,8 @@ This module offers the following functions: Removes a named value from a registry key. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants `. *value* is a string that identifies the value to remove. @@ -92,8 +88,8 @@ This module offers the following functions: 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. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants `. *index* is an integer that identifies the index of the key to retrieve. @@ -106,8 +102,8 @@ This module offers the following functions: 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. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants `. *index* is an integer that identifies the index of the value to retrieve. @@ -143,8 +139,8 @@ This module offers the following functions: Writes all the attributes of a key to the registry. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`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 @@ -164,8 +160,8 @@ This module offers the following functions: 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. + *key* is a handle returned by :func:`ConnectRegistry` or one of the constants + :const:`HKEY_USERS` or :const:`HKEY_LOCAL_MACHINE`. *sub_key* is a string that identifies the sub_key to load. @@ -175,7 +171,9 @@ This module offers the following functions: 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. + from permissions -- see the `RegLoadKey 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. @@ -188,15 +186,16 @@ This module offers the following functions: Opens the specified key, returning a :ref:`handle object `. - *key* is an already open key, or any one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`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`. + security access for the key. Default is :const:`KEY_READ`. See + :ref:`Access Rights ` for other allowed values. The result is a new handle to the specified key. @@ -213,8 +212,8 @@ This module offers the following functions: Returns information about a key, as a tuple. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants `. The result is a tuple of 3 items: @@ -237,8 +236,8 @@ This module offers the following functions: Retrieves the unnamed value for a key, as a string. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`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 @@ -255,8 +254,8 @@ This module offers the following functions: 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. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants `. *value_name* is a string indicating the value to query. @@ -276,8 +275,8 @@ This module offers the following functions: 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. + *key* is an already open key, or one of the predefined + :ref:`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 @@ -287,8 +286,10 @@ This module offers the following functions: 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. + privileges are different than permissions -- see the + `Conflicts Between User Rights and Permissions documentation + `__ + for more details. This function passes NULL for *security_attributes* to the API. @@ -297,8 +298,8 @@ This module offers the following functions: Associates a value with a specified key. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants `. *sub_key* is a string that names the subkey with which the value is associated. @@ -323,42 +324,14 @@ This module offers the following functions: 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. + *key* is an already open key, or one of the predefined + :ref:`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. | - +----------------------------------+---------------------------------------------+ + *type* is an integer that specifies the type of the data. See + :ref:`Value Types ` for the available types. *reserved* can be anything -- zero is always passed to the API. @@ -375,6 +348,237 @@ This module offers the following functions: registry. This helps the registry perform efficiently. +.. function:: DisableReflectionKey(key) + + Disables registry reflection for 32-bit processes running on a 64-bit + Operating System. + + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants `. + + Will generally raise :exc:`NotImplemented` if executed on a 32-bit + Operating System. + + If the key is not on the reflection list, the function succeeds but has no + effect. Disabling reflection for a key does not affect reflection of any + subkeys. + + +.. function:: EnableReflectionKey(key) + + Restores registry reflection for the specified disabled key. + + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants `. + + Will generally raise :exc:`NotImplemented` if executed on a 32-bit + Operating System. + + Restoring reflection for a key does not affect reflection of any subkeys. + + +.. function:: QueryReflectionKey(key) + + Determines the reflection state for the specified key. + + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants `. + + Returns ``True`` if reflection is disabled. + + Will generally raise :exc:`NotImplemented` if executed on a 32-bit + Operating System. + + +.. _constants: + +Constants +------------------ + +The following constants are defined for use in many :mod:`_winreg` functions. + +.. _hkey-constants: + +HKEY_* Constants +++++++++++++++++ + +.. data:: 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. + + +.. data:: 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. + +.. data:: 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. + +.. data:: 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. + +.. data:: 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. + + +.. data:: HKEY_CURRENT_CONFIG + + Contains information about the current hardware profile of the + local computer system. + +.. data:: HKEY_DYN_DATA + + This key is not used in versions of Windows after 98. + + +.. _access-rights: + +Access Rights ++++++++++++++ + +For more information, see `Registry Key Security and Access +`__. + +.. data:: KEY_ALL_ACCESS + + Combines the STANDARD_RIGHTS_REQUIRED, :const:`KEY_QUERY_VALUE`, + :const:`KEY_SET_VALUE`, :const:`KEY_CREATE_SUB_KEY`, + :const:`KEY_ENUMERATE_SUB_KEYS`, :const:`KEY_NOTIFY`, + and :const:`KEY_CREATE_LINK` access rights. + +.. data:: KEY_WRITE + + Combines the STANDARD_RIGHTS_WRITE, :const:`KEY_SET_VALUE`, and + :const:`KEY_CREATE_SUB_KEY` access rights. + +.. data:: KEY_READ + + Combines the STANDARD_RIGHTS_READ, :const:`KEY_QUERY_VALUE`, + :const:`KEY_ENUMERATE_SUB_KEYS`, and :const:`KEY_NOTIFY` values. + +.. data:: KEY_EXECUTE + + Equivalent to :const:`KEY_READ`. + +.. data:: KEY_QUERY_VALUE + + Required to query the values of a registry key. + +.. data:: KEY_SET_VALUE + + Required to create, delete, or set a registry value. + +.. data:: KEY_CREATE_SUB_KEY + + Required to create a subkey of a registry key. + +.. data:: KEY_ENUMERATE_SUB_KEYS + + Required to enumerate the subkeys of a registry key. + +.. data:: KEY_NOTIFY + + Required to request change notifications for a registry key or for + subkeys of a registry key. + +.. data:: KEY_CREATE_LINK + + Reserved for system use. + + +.. _64-bit-access-rights: + +64-bit Specific +*************** + +For more information, see `Accesing an Alternate Registry View +`__. + +.. data:: KEY_WOW64_64KEY + + Indicates that an application on 64-bit Windows should operate on + the 64-bit registry view. + +.. data:: KEY_WOW64_32KEY + + Indicates that an application on 64-bit Windows should operate on + the 32-bit registry view. + + +.. _value-types: + +Value Types ++++++++++++ + +For more information, see `Registry Value Types +`__. + +.. data:: REG_BINARY + + Binary data in any form. + +.. data:: REG_DWORD + + 32-bit number. + +.. data:: REG_DWORD_LITTLE_ENDIAN + + A 32-bit number in little-endian format. + +.. data:: REG_DWORD_BIG_ENDIAN + + A 32-bit number in big-endian format. + +.. data:: REG_EXPAND_SZ + + Null-terminated string containing references to environment + variables (``%PATH%``). + +.. data:: REG_LINK + + A Unicode symbolic link. + +.. data:: REG_MULTI_SZ + + A sequence of null-terminated strings, terminated by two null characters. + (Python handles this termination automatically.) + +.. data:: REG_NONE + + No defined value type. + +.. data:: REG_RESOURCE_LIST + + A device-driver resource list. + +.. data:: REG_FULL_RESOURCE_DESCRIPTOR + + A hardware setting. + +.. data:: REG_RESOURCE_REQUIREMENTS_LIST + + A hardware resource list. + +.. data:: REG_SZ + + A null-terminated string. + + .. _handle-object: Registry Handle Objects