diff --git a/Doc/library/_winreg.rst b/Doc/library/_winreg.rst index e14ca9994f4..36271300cd7 100644 --- a/Doc/library/_winreg.rst +++ b/Doc/library/_winreg.rst @@ -19,10 +19,6 @@ integer as the registry handle, a :ref:`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 module will be created offering a higher-level -interface to the registry API. - This module offers the following functions: @@ -31,9 +27,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) @@ -55,8 +51,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. @@ -73,8 +69,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 any 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. @@ -89,8 +85,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. @@ -99,8 +95,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 any one of the predefined + :ref:`HKEY_* constants `. *index* is an integer that identifies the index of the key to retrieve. @@ -113,8 +109,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 any one of the predefined + :ref:`HKEY_* constants `. *index* is an integer that identifies the index of the value to retrieve. @@ -154,8 +150,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 @@ -176,7 +172,7 @@ This module offers the following functions: from a specified file into that subkey. *key* is a handle returned by :func:`ConnectRegistry` or one of the constants - :const:`HKEY_USER` or :const:`HKEY_LOCAL_MACHINE`. + :const:`HKEY_USERS` or :const:`HKEY_LOCAL_MACHINE`. *sub_key* is a string that identifies the subkey to load. @@ -186,7 +182,7 @@ This module offers the following functions: A call to :func:`LoadKey` fails if the calling process does not have the :const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different - from permissions -- see the `Win32 documentation + from permissions -- see the `RegLoadKey documentation `_ for more details. @@ -198,18 +194,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 any 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`. See the `Win32 - documentation - `_ for - other allowed values. + 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. @@ -226,8 +220,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: @@ -250,8 +244,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 @@ -268,8 +262,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. @@ -290,8 +284,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 @@ -301,8 +295,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. @@ -311,8 +307,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. @@ -337,42 +333,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. @@ -389,6 +357,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