rest25/library/_winreg.rst => rest262/library/_winreg.rst
n1- 
2:mod:`_winreg` -- Windows registry access
3=========================================
4
5.. module:: _winreg
6   :platform: Windows
7   :synopsis: Routines and objects for manipulating the Windows registry.
8.. sectionauthor:: Mark Hammond <MarkH@ActiveState.com>
9
n9+.. note::
10+   The :mod:`_winreg` module has been renamed to :mod:`winreg` in Python 3.0.
11+   The :term:`2to3` tool will automatically adapt imports when converting your
12+   sources to 3.0.
13+ 
10
11.. versionadded:: 2.0
12
13These functions expose the Windows registry API to Python.  Instead of using an
14integer as the registry handle, a handle object is used to ensure that the
15handles are closed correctly, even if the programmer neglects to explicitly
16close them.
17
37   Establishes a connection to a predefined registry handle on  another computer,
38   and returns a :dfn:`handle object`
39
40   *computer_name* is the name of the remote computer, of the  form
41   ``r"\\computername"``.  If ``None``, the local computer is used.
42
43   *key* is the predefined handle to connect to.
44
n45-   The return value is the handle of the opened key. If the function fails, an
n49+   The return value is the handle of the opened key. If the function fails, a
46-   :exc:`EnvironmentError` exception is  raised.
50+   :exc:`WindowsError` exception is  raised.
47
48
49.. function:: CreateKey(key, sub_key)
50
51   Creates or opens the specified key, returning a :dfn:`handle object`
52
53   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
54   constants.
55
56   *sub_key* is a string that names the key this method opens  or creates.
57
58   If *key* is one of the predefined keys, *sub_key* may  be ``None``. In that
59   case, the handle returned is the same key handle  passed in to the function.
60
61   If the key already exists, this function opens the existing key.
62
n63-   The return value is the handle of the opened key. If the function fails, an
n67+   The return value is the handle of the opened key. If the function fails, a
64-   :exc:`EnvironmentError` exception is  raised.
68+   :exc:`WindowsError` exception is  raised.
65
66
67.. function:: DeleteKey(key, sub_key)
68
69   Deletes the specified key.
70
71   *key* is an already open key, or any one of the predefined  :const:`HKEY_\*`
72   constants.
73
74   *sub_key* is a string that must be a subkey of the key  identified by the *key*
75   parameter.  This value must not be  ``None``, and the key may not have subkeys.
76
77   *This method can not delete keys with subkeys.*
78
79   If the method succeeds, the entire key, including all of its values, is removed.
n80-   If the method fails, an :exc:`EnvironmentError`  exception is raised.
n84+   If the method fails, a :exc:`WindowsError`  exception is raised.
81
82
83.. function:: DeleteValue(key, value)
84
85   Removes a named value from a registry key.
86
87   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
88   constants.
95   Enumerates subkeys of an open registry key, returning a string.
96
97   *key* is an already open key, or any one of the predefined  :const:`HKEY_\*`
98   constants.
99
100   *index* is an integer that identifies the index of the key to  retrieve.
101
102   The function retrieves the name of one subkey each time it  is called.  It is
n103-   typically called repeatedly until an  :exc:`EnvironmentError` exception  is
n107+   typically called repeatedly until a  :exc:`WindowsError` exception  is
104   raised, indicating, no more values are available.
105
106
107.. function:: EnumValue(key, index)
108
109   Enumerates values of an open registry key, returning a tuple.
110
111   *key* is an already open key, or any one of the predefined  :const:`HKEY_\*`
112   constants.
113
114   *index* is an integer that identifies the index of the value  to retrieve.
115
116   The function retrieves the name of one subkey each time it is  called. It is
n117-   typically called repeatedly, until an  :exc:`EnvironmentError` exception is
n121+   typically called repeatedly, until a  :exc:`WindowsError` exception is
118   raised, indicating  no more values.
119
120   The result is a tuple of 3 items:
121
122   +-------+--------------------------------------------+
123   | Index | Meaning                                    |
124   +=======+============================================+
125   | ``0`` | A string that identifies the value name    |
128   |       | whose type depends on the underlying       |
129   |       | registry type                              |
130   +-------+--------------------------------------------+
131   | ``2`` | An integer that identifies the type of the |
132   |       | value data                                 |
133   +-------+--------------------------------------------+
134
135
n140+.. function:: ExpandEnvironmentStrings(unicode)
141+ 
142+   Expands environment strings %NAME% in unicode string like const:`REG_EXPAND_SZ`::
143+ 
144+      >>> ExpandEnvironmentStrings(u"%windir%")
145+      u"C:\\Windows"
146+ 
147+   .. versionadded:: 2.6
148+ 
149+ 
136.. function:: FlushKey(key)
137
138   Writes all the attributes of a key to the registry.
139
140   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
141   constants.
142
n143-   It is not necessary to call RegFlushKey to change a key. Registry changes are
n157+   It is not necessary to call :func:`FlushKey` to change a key. Registry changes are
144   flushed to disk by the registry using its lazy  flusher.  Registry changes are
145   also flushed to disk at system  shutdown.  Unlike :func:`CloseKey`, the
146   :func:`FlushKey` method  returns only when all the data has been written to the
147   registry. An application should only call :func:`FlushKey` if it requires
148   absolute  certainty that registry changes are on disk.
149
n164+   .. note::
165+ 
150-   *If you don't know whether a FlushKey() call is required, it  probably isn't.*
166+      If you don't know whether a :func:`FlushKey` call is required, it  probably
167+      isn't.
151
152
n153-.. function:: RegLoadKey(key, sub_key, file_name)
n170+.. function:: LoadKey(key, sub_key, file_name)
154
155   Creates a subkey under the specified key and stores registration  information
156   from a specified file into that subkey.
157
158   *key* is an already open key, or any of the predefined :const:`HKEY_\*`
159   constants.
160
161   *sub_key* is a string that identifies the sub_key to load.
170
171   If *key* is a handle returned by :func:`ConnectRegistry`,  then the path
172   specified in *fileName* is relative to the  remote computer.
173
174   The Win32 documentation implies *key* must be in the  :const:`HKEY_USER` or
175   :const:`HKEY_LOCAL_MACHINE` tree. This may or may not be true.
176
177
n178-.. function:: OpenKey(key, sub_key[, res\ ``= 0``][, sam\ ``= KEY_READ``])
n195+.. function:: OpenKey(key, sub_key[, res=0][, sam=KEY_READ])
179
180   Opens the specified key, returning a :dfn:`handle object`
181
182   *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
183   constants.
184
185   *sub_key* is a string that identifies the sub_key to open.
186
187   *res* is a reserved integer, and must be zero.  The default is zero.
188
189   *sam* is an integer that specifies an access mask that describes  the desired
190   security access for the key.  Default is :const:`KEY_READ`
191
192   The result is a new handle to the specified key.
193
n194-   If the function fails, :exc:`EnvironmentError` is raised.
n211+   If the function fails, :exc:`WindowsError` is raised.
195
196
197.. function:: OpenKeyEx()
198
199   The functionality of :func:`OpenKeyEx` is provided via :func:`OpenKey`, by the
200   use of default arguments.
201
202
230
231   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
232   constants.
233
234   *sub_key* is a string that holds the name of the subkey with which  the value is
235   associated.  If this parameter is ``None`` or empty, the  function retrieves the
236   value set by the :func:`SetValue` method  for the key identified by *key*.
237
n238-   Values in the registry have name, type, and data components. This  method
n255+   Values in the registry have name, type, and data components. This method
239   retrieves the data for a key's first value that has a NULL name. But the
n240-   underlying API call doesn't return the type, Lame Lame Lame, DO NOT USE THIS!!!
n257+   underlying API call doesn't return the type, so always use
258+   :func:`QueryValueEx` if possible.
241
242
243.. function:: QueryValueEx(key, value_name)
244
245   Retrieves the type and data for a specified value name associated with  an open
246   registry key.
247
248   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
311
312.. function:: SetValueEx(key, value_name, reserved, type, value)
313
314   Stores data in the value field of an open registry key.
315
316   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
317   constants.
318
n319-   *sub_key* is a string that names the subkey with which the  value is associated.
n337+   *value_name* is a string that names the subkey with which the  value is
338+   associated.
320
321   *type* is an integer that specifies the type of the data.   This should be one
322   of the following constants defined in this module:
323
324   +----------------------------------+---------------------------------------------+
325   | Constant                         | Meaning                                     |
326   +==================================+=============================================+
327   | :const:`REG_BINARY`              | Binary data in any form.                    |
390true if they both reference the same underlying Windows handle value.
391
392Handle objects can be converted to an integer (e.g., using the builtin
393:func:`int` function), in which case the underlying Windows handle value is
394returned.  You can also use the  :meth:`Detach` method to return the integer
395handle, and also disconnect the Windows handle from the handle object.
396
397
n398-.. method:: XXX Class.Close()
n417+.. method:: PyHKEY.Close()
399
400   Closes the underlying Windows handle.
401
402   If the handle is already closed, no error is raised.
403
404
n405-.. method:: XXX Class.Detach()
n424+.. method:: PyHKEY.Detach()
406
407   Detaches the Windows handle from the handle object.
408
409   The result is an integer (or long on 64 bit Windows) that holds the value of the
410   handle before it is detached.  If the handle is already detached or closed, this
411   will return zero.
412
413   After calling this function, the handle is effectively invalidated, but the
414   handle is not closed.  You would call this function when  you need the
415   underlying Win32 handle to exist beyond the lifetime  of the handle object.
416
t436+.. method:: PyHKEY.__enter__()
437+            PyHKEY.__exit__(\*exc_info)
438+ 
439+   The HKEY object implements :meth:`__enter__` and :meth:`__exit__` and thus
440+   supports the context protocol for the :keyword:`with` statement::
441+ 
442+      with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
443+          # ... work with key ...
444+ 
445+   will automatically close *key* when control leaves the :keyword:`with` block.
446+ 
447+   .. versionadded:: 2.6
448+ 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op