diff options
| -rw-r--r-- | Doc/library/_winreg.rst | 334 |
1 files changed, 244 insertions, 90 deletions
diff --git a/Doc/library/_winreg.rst b/Doc/library/_winreg.rst index 957f011a2e..825ce1fb2e 100644 --- a/Doc/library/_winreg.rst +++ b/Doc/library/_winreg.rst @@ -19,10 +19,6 @@ integer as the registry handle, a :ref:`handle object <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() <PyHKEY.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 <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 <hkey-constants>`. *sub_key* is a string that names the key this method opens or creates. @@ -74,18 +70,16 @@ This module offers the following functions: Creates or opens the specified key, returning a :ref:`handle object <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 <hkey-constants>`. *sub_key* is a string that names the key this method opens or creates. *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_ALL_ACCESS`. See the - `Win32 documentation - <http://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`__ for - other allowed values. + security access for the key. Default is :const:`KEY_ALL_ACCESS`. See + :ref:`Access Rights <access-rights>` for other allowed values. If *key* is one of the predefined keys, *sub_key* may be ``None``. In that @@ -103,8 +97,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 <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. @@ -122,10 +116,11 @@ This module offers the following functions: .. note:: The :func:`DeleteKeyEx` function is implemented with the RegDeleteKeyEx Windows API function, which is specific to 64-bit versions of Windows. - See http://msdn.microsoft.com/en-us/library/ms724847%28VS.85%29.aspx + See the `RegDeleteKeyEx documentation + <http://msdn.microsoft.com/en-us/library/ms724847%28VS.85%29.aspx>`__. - *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 <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 @@ -134,10 +129,8 @@ This module offers the following functions: *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_WOW64_64KEY`. See the - `Win32 documentation - <http://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`__ for - other allowed values. + security access for the key. Default is :const:`KEY_WOW64_64KEY`. See + :ref:`Access Rights <access-rights>` for other allowed values. *This method can not delete keys with subkeys.* @@ -154,8 +147,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 <hkey-constants>`. *value* is a string that identifies the value to remove. @@ -164,8 +157,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 <hkey-constants>`. *index* is an integer that identifies the index of the key to retrieve. @@ -178,8 +171,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 <hkey-constants>`. *index* is an integer that identifies the index of the value to retrieve. @@ -219,8 +212,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 <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 @@ -241,7 +234,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. @@ -251,7 +244,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 <http://msdn.microsoft.com/en-us/library/ms724889%28v=VS.85%29.aspx>`__ for more details. @@ -263,18 +256,16 @@ This module offers the following functions: Opens the specified key, returning a :ref:`handle object <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 <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 - <http://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`__ for - other allowed values. + security access for the key. Default is :const:`KEY_READ`. See + :ref:`Access Rights <access-rights>` for other allowed values. The result is a new handle to the specified key. @@ -291,8 +282,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 <hkey-constants>`. The result is a tuple of 3 items: @@ -315,8 +306,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 <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 @@ -333,8 +324,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 <hkey-constants>`. *value_name* is a string indicating the value to query. @@ -355,8 +346,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 <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 @@ -366,8 +357,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 + <http://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`__ + for more details. This function passes NULL for *security_attributes* to the API. @@ -376,8 +369,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 <hkey-constants>`. *sub_key* is a string that names the subkey with which the value is associated. @@ -402,42 +395,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 <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 <value-types>` for the available types. *reserved* can be anything -- zero is always passed to the API. @@ -459,8 +424,8 @@ This module offers the following functions: 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 :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <hkey-constants>`. Will generally raise :exc:`NotImplemented` if executed on a 32-bit operating system. @@ -474,8 +439,8 @@ This module offers the following functions: Restores registry reflection for the specified disabled 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 <hkey-constants>`. Will generally raise :exc:`NotImplemented` if executed on a 32-bit operating system. @@ -487,8 +452,8 @@ This module offers the following functions: Determines the reflection state for the 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 <hkey-constants>`. Returns ``True`` if reflection is disabled. @@ -496,6 +461,195 @@ This module offers the following functions: 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 +<http://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`__. + +.. 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 +<http://msdn.microsoft.com/en-us/library/aa384129(v=VS.85).aspx>`__. + +.. 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 +<http://msdn.microsoft.com/en-us/library/ms724884%28v=VS.85%29.aspx>`__. + +.. 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 |