mirror of https://github.com/python/cpython
Fix markup, punctuation and whitespaces in _winreg.rst.
This commit is contained in:
Ezio Melotti
parent
c0deec1839
commit
01fa86a0bd
|
|
@ -20,7 +20,7 @@ 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
|
||||
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:
|
||||
|
|
@ -38,39 +38,41 @@ This module offers the following functions:
|
|||
|
||||
.. function:: ConnectRegistry(computer_name, key)
|
||||
|
||||
Establishes a connection to a predefined registry handle on another computer,
|
||||
and returns a :dfn:`handle object`
|
||||
Establishes a connection to a predefined registry handle on another computer,
|
||||
and returns a :ref:`handle object <handle-object>`.
|
||||
|
||||
*computer_name* is the name of the remote computer, of the form
|
||||
*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, a
|
||||
:exc:`WindowsError` exception is raised.
|
||||
:exc:`WindowsError` exception is raised.
|
||||
|
||||
|
||||
.. function:: CreateKey(key, sub_key)
|
||||
|
||||
Creates or opens the specified key, returning a :dfn:`handle object`
|
||||
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_\*`
|
||||
*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.
|
||||
*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 *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, a
|
||||
:exc:`WindowsError` exception is raised.
|
||||
:exc:`WindowsError` exception is raised.
|
||||
|
||||
|
||||
.. function:: CreateKeyEx(key, sub_key[, res=0[, sam=KEY_ALL_ACCESS]])
|
||||
.. function:: CreateKeyEx(key, sub_key, res=0, sam=KEY_ALL_ACCESS)
|
||||
|
||||
Creates or opens the specified key, returning a :dfn:`handle object`
|
||||
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.
|
||||
|
|
@ -82,8 +84,8 @@ This module offers the following functions:
|
|||
*sam* is an integer that specifies an access mask that describes the desired
|
||||
security access for the key. Default is :const:`KEY_ALL_ACCESS`
|
||||
|
||||
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 *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.
|
||||
|
||||
|
|
@ -106,10 +108,10 @@ This module offers the following functions:
|
|||
*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, a :exc:`WindowsError` exception is raised.
|
||||
If the method fails, a :exc:`WindowsError` exception is raised.
|
||||
|
||||
|
||||
.. function:: DeleteKeyEx(key, sub_key[, sam=KEY_WOW64_64KEY[, res=0]])
|
||||
.. function:: DeleteKeyEx(key, sub_key, sam=KEY_WOW64_64KEY, res=0)
|
||||
|
||||
Deletes the specified key.
|
||||
|
||||
|
|
@ -144,7 +146,7 @@ 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_\*`
|
||||
*key* is an already open key, or one of the predefined :const:`HKEY_\*`
|
||||
constants.
|
||||
|
||||
*value* is a string that identifies the value to remove.
|
||||
|
|
@ -154,13 +156,13 @@ 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_\*`
|
||||
*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.
|
||||
*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 a :exc:`WindowsError` exception is
|
||||
The function retrieves the name of one subkey each time it is called. It is
|
||||
typically called repeatedly until a :exc:`WindowsError` exception is
|
||||
raised, indicating, no more values are available.
|
||||
|
||||
|
||||
|
|
@ -168,14 +170,14 @@ 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_\*`
|
||||
*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.
|
||||
*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 a :exc:`WindowsError` exception is
|
||||
raised, indicating no more values.
|
||||
The function retrieves the name of one subkey each time it is called. It is
|
||||
typically called repeatedly, until a :exc:`WindowsError` exception is
|
||||
raised, indicating no more values.
|
||||
|
||||
The result is a tuple of 3 items:
|
||||
|
||||
|
|
@ -207,25 +209,25 @@ 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_\*`
|
||||
*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
|
||||
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.
|
||||
absolute certainty that registry changes are on disk.
|
||||
|
||||
.. note::
|
||||
|
||||
If you don't know whether a :func:`FlushKey` call is required, it probably
|
||||
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
|
||||
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_\*`
|
||||
|
|
@ -239,18 +241,18 @@ 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.
|
||||
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.
|
||||
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
|
||||
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])
|
||||
.. function:: OpenKey(key, sub_key, res=0, sam=KEY_READ)
|
||||
|
||||
Opens the specified key, returning a :dfn:`handle object`
|
||||
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.
|
||||
|
|
@ -259,7 +261,7 @@ 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
|
||||
*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.
|
||||
|
|
@ -269,15 +271,15 @@ This module offers the following functions:
|
|||
|
||||
.. function:: OpenKeyEx()
|
||||
|
||||
The functionality of :func:`OpenKeyEx` is provided via :func:`OpenKey`, by the
|
||||
use of default arguments.
|
||||
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_\*`
|
||||
*key* is an already open key, or one of the predefined :const:`HKEY_\*`
|
||||
constants.
|
||||
|
||||
The result is a tuple of 3 items:
|
||||
|
|
@ -299,14 +301,14 @@ This module offers the following functions:
|
|||
|
||||
.. function:: QueryValue(key, sub_key)
|
||||
|
||||
Retrieves the unnamed value for a key, as a string
|
||||
Retrieves the unnamed value for a key, as a string.
|
||||
|
||||
*key* is an already open key, or one of the predefined :const:`HKEY_\*`
|
||||
*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*.
|
||||
*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
|
||||
|
|
@ -316,10 +318,10 @@ This module offers the following functions:
|
|||
|
||||
.. function:: QueryValueEx(key, value_name)
|
||||
|
||||
Retrieves the type and data for a specified value name associated with an open
|
||||
registry key.
|
||||
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_\*`
|
||||
*key* is an already open key, or one of the predefined :const:`HKEY_\*`
|
||||
constants.
|
||||
|
||||
*value_name* is a string indicating the value to query.
|
||||
|
|
@ -340,18 +342,18 @@ 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_\*`
|
||||
*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.
|
||||
or :meth:`RestoreKey` methods.
|
||||
|
||||
If *key* represents a key on a remote computer, the path described by
|
||||
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
|
||||
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.
|
||||
|
|
@ -361,10 +363,10 @@ 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_\*`
|
||||
*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.
|
||||
*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`
|
||||
|
|
@ -379,7 +381,7 @@ This module offers the following functions:
|
|||
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
|
||||
The key identified by the *key* parameter must have been opened with
|
||||
:const:`KEY_SET_VALUE` access.
|
||||
|
||||
|
||||
|
|
@ -387,13 +389,13 @@ 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_\*`
|
||||
*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
|
||||
*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
|
||||
*type* is an integer that specifies the type of the data. This should be one
|
||||
of the following constants defined in this module:
|
||||
|
||||
+----------------------------------+---------------------------------------------+
|
||||
|
|
@ -415,7 +417,7 @@ This module offers the following functions:
|
|||
+----------------------------------+---------------------------------------------+
|
||||
| :const:`REG_MULTI_SZ` | A sequence of null-terminated strings, |
|
||||
| | terminated by two null characters. (Python |
|
||||
| | handles this termination automatically.) |
|
||||
| | handles this termination automatically.) |
|
||||
+----------------------------------+---------------------------------------------+
|
||||
| :const:`REG_NONE` | No defined value type. |
|
||||
+----------------------------------+---------------------------------------------+
|
||||
|
|
@ -424,7 +426,7 @@ This module offers the following functions:
|
|||
| :const:`REG_SZ` | A null-terminated string. |
|
||||
+----------------------------------+---------------------------------------------+
|
||||
|
||||
*reserved* can be anything - zero is always passed to the API.
|
||||
*reserved* can be anything -- zero is always passed to the API.
|
||||
|
||||
*value* is a string that specifies the new value.
|
||||
|
||||
|
|
@ -432,7 +434,7 @@ This module offers the following functions:
|
|||
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:`CreateKey` or :func:`OpenKey` methods.
|
||||
To open the key, use the :func:`CreateKey` 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
|
||||
|
|
@ -488,14 +490,14 @@ 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.
|
||||
: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.
|
||||
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:`__nonzero__` - thus ::
|
||||
Handle objects provide semantics for :meth:`__nonzero__` -- thus::
|
||||
|
||||
if handle:
|
||||
print "Yes"
|
||||
|
|
@ -508,7 +510,7 @@ true if they both reference the same underlying Windows handle value.
|
|||
|
||||
Handle objects can be converted to an integer (e.g., using the built-in
|
||||
: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
|
||||
returned. You can also use the :meth:`Detach` method to return the integer
|
||||
handle, and also disconnect the Windows handle from the handle object.
|
||||
|
||||
|
||||
|
|
@ -528,8 +530,8 @@ handle, and also disconnect the Windows handle from the handle object.
|
|||
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.
|
||||
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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue