2 :mod:`_winreg` -- Windows registry access
3 =========================================
7 :synopsis: Routines and objects for manipulating the Windows registry.
8 .. sectionauthor:: Mark Hammond <MarkH@ActiveState.com>
13 These functions expose the Windows registry API to Python. Instead of using an
14 integer as the registry handle, a handle object is used to ensure that the
15 handles are closed correctly, even if the programmer neglects to explicitly
18 This module exposes a very low-level interface to the Windows registry; it is
19 expected that in the future a new ``winreg`` module will be created offering a
20 higher-level interface to the registry API.
22 This module offers the following functions:
25 .. function:: CloseKey(hkey)
27 Closes a previously opened registry key. The hkey argument specifies a
28 previously opened key.
30 Note that if *hkey* is not closed using this method (or via
31 :meth:`handle.Close`), it is closed when the *hkey* object is destroyed by
35 .. function:: ConnectRegistry(computer_name, key)
37 Establishes a connection to a predefined registry handle on another computer,
38 and returns a :dfn:`handle object`
40 *computer_name* is the name of the remote computer, of the form
41 ``r"\\computername"``. If ``None``, the local computer is used.
43 *key* is the predefined handle to connect to.
45 The return value is the handle of the opened key. If the function fails, an
46 :exc:`EnvironmentError` exception is raised.
49 .. function:: CreateKey(key, sub_key)
51 Creates or opens the specified key, returning a :dfn:`handle object`
53 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
56 *sub_key* is a string that names the key this method opens or creates.
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.
61 If the key already exists, this function opens the existing key.
63 The return value is the handle of the opened key. If the function fails, an
64 :exc:`EnvironmentError` exception is raised.
67 .. function:: DeleteKey(key, sub_key)
69 Deletes the specified key.
71 *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
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.
77 *This method can not delete keys with subkeys.*
79 If the method succeeds, the entire key, including all of its values, is removed.
80 If the method fails, an :exc:`EnvironmentError` exception is raised.
83 .. function:: DeleteValue(key, value)
85 Removes a named value from a registry key.
87 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
90 *value* is a string that identifies the value to remove.
93 .. function:: EnumKey(key, index)
95 Enumerates subkeys of an open registry key, returning a string.
97 *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
100 *index* is an integer that identifies the index of the key to retrieve.
102 The function retrieves the name of one subkey each time it is called. It is
103 typically called repeatedly until an :exc:`EnvironmentError` exception is
104 raised, indicating, no more values are available.
107 .. function:: EnumValue(key, index)
109 Enumerates values of an open registry key, returning a tuple.
111 *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
114 *index* is an integer that identifies the index of the value to retrieve.
116 The function retrieves the name of one subkey each time it is called. It is
117 typically called repeatedly, until an :exc:`EnvironmentError` exception is
118 raised, indicating no more values.
120 The result is a tuple of 3 items:
122 +-------+--------------------------------------------+
124 +=======+============================================+
125 | ``0`` | A string that identifies the value name |
126 +-------+--------------------------------------------+
127 | ``1`` | An object that holds the value data, and |
128 | | whose type depends on the underlying |
130 +-------+--------------------------------------------+
131 | ``2`` | An integer that identifies the type of the |
133 +-------+--------------------------------------------+
136 .. function:: ExpandEnvironmentStrings(unicode)
138 Expands environment strings %NAME% in unicode string like const:`REG_EXPAND_SZ`::
140 >>> ExpandEnvironmentStrings(u"%windir%")
143 .. versionadded:: 2.6
146 .. function:: FlushKey(key)
148 Writes all the attributes of a key to the registry.
150 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
153 It is not necessary to call RegFlushKey to change a key. Registry changes are
154 flushed to disk by the registry using its lazy flusher. Registry changes are
155 also flushed to disk at system shutdown. Unlike :func:`CloseKey`, the
156 :func:`FlushKey` method returns only when all the data has been written to the
157 registry. An application should only call :func:`FlushKey` if it requires
158 absolute certainty that registry changes are on disk.
162 If you don't know whether a :func:`FlushKey` call is required, it probably
166 .. function:: RegLoadKey(key, sub_key, file_name)
168 Creates a subkey under the specified key and stores registration information
169 from a specified file into that subkey.
171 *key* is an already open key, or any of the predefined :const:`HKEY_\*`
174 *sub_key* is a string that identifies the sub_key to load.
176 *file_name* is the name of the file to load registry data from. This file must
177 have been created with the :func:`SaveKey` function. Under the file allocation
178 table (FAT) file system, the filename may not have an extension.
180 A call to LoadKey() fails if the calling process does not have the
181 :const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different than
182 permissions - see the Win32 documentation for more details.
184 If *key* is a handle returned by :func:`ConnectRegistry`, then the path
185 specified in *fileName* is relative to the remote computer.
187 The Win32 documentation implies *key* must be in the :const:`HKEY_USER` or
188 :const:`HKEY_LOCAL_MACHINE` tree. This may or may not be true.
191 .. function:: OpenKey(key, sub_key[, res=0][, sam=KEY_READ])
193 Opens the specified key, returning a :dfn:`handle object`
195 *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
198 *sub_key* is a string that identifies the sub_key to open.
200 *res* is a reserved integer, and must be zero. The default is zero.
202 *sam* is an integer that specifies an access mask that describes the desired
203 security access for the key. Default is :const:`KEY_READ`
205 The result is a new handle to the specified key.
207 If the function fails, :exc:`EnvironmentError` is raised.
210 .. function:: OpenKeyEx()
212 The functionality of :func:`OpenKeyEx` is provided via :func:`OpenKey`, by the
213 use of default arguments.
216 .. function:: QueryInfoKey(key)
218 Returns information about a key, as a tuple.
220 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
223 The result is a tuple of 3 items:
225 +-------+---------------------------------------------+
227 +=======+=============================================+
228 | ``0`` | An integer giving the number of sub keys |
230 +-------+---------------------------------------------+
231 | ``1`` | An integer giving the number of values this |
233 +-------+---------------------------------------------+
234 | ``2`` | A long integer giving when the key was last |
235 | | modified (if available) as 100's of |
236 | | nanoseconds since Jan 1, 1600. |
237 +-------+---------------------------------------------+
240 .. function:: QueryValue(key, sub_key)
242 Retrieves the unnamed value for a key, as a string
244 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
247 *sub_key* is a string that holds the name of the subkey with which the value is
248 associated. If this parameter is ``None`` or empty, the function retrieves the
249 value set by the :func:`SetValue` method for the key identified by *key*.
251 Values in the registry have name, type, and data components. This method
252 retrieves the data for a key's first value that has a NULL name. But the
253 underlying API call doesn't return the type, Lame Lame Lame, DO NOT USE THIS!!!
256 .. function:: QueryValueEx(key, value_name)
258 Retrieves the type and data for a specified value name associated with an open
261 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
264 *value_name* is a string indicating the value to query.
266 The result is a tuple of 2 items:
268 +-------+-----------------------------------------+
270 +=======+=========================================+
271 | ``0`` | The value of the registry item. |
272 +-------+-----------------------------------------+
273 | ``1`` | An integer giving the registry type for |
275 +-------+-----------------------------------------+
278 .. function:: SaveKey(key, file_name)
280 Saves the specified key, and all its subkeys to the specified file.
282 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
285 *file_name* is the name of the file to save registry data to. This file cannot
286 already exist. If this filename includes an extension, it cannot be used on file
287 allocation table (FAT) file systems by the :meth:`LoadKey`, :meth:`ReplaceKey`
288 or :meth:`RestoreKey` methods.
290 If *key* represents a key on a remote computer, the path described by
291 *file_name* is relative to the remote computer. The caller of this method must
292 possess the :const:`SeBackupPrivilege` security privilege. Note that
293 privileges are different than permissions - see the Win32 documentation for
296 This function passes NULL for *security_attributes* to the API.
299 .. function:: SetValue(key, sub_key, type, value)
301 Associates a value with a specified key.
303 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
306 *sub_key* is a string that names the subkey with which the value is associated.
308 *type* is an integer that specifies the type of the data. Currently this must be
309 :const:`REG_SZ`, meaning only strings are supported. Use the :func:`SetValueEx`
310 function for support for other data types.
312 *value* is a string that specifies the new value.
314 If the key specified by the *sub_key* parameter does not exist, the SetValue
317 Value lengths are limited by available memory. Long values (more than 2048
318 bytes) should be stored as files with the filenames stored in the configuration
319 registry. This helps the registry perform efficiently.
321 The key identified by the *key* parameter must have been opened with
322 :const:`KEY_SET_VALUE` access.
325 .. function:: SetValueEx(key, value_name, reserved, type, value)
327 Stores data in the value field of an open registry key.
329 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
332 *value_name* is a string that names the subkey with which the value is
335 *type* is an integer that specifies the type of the data. This should be one
336 of the following constants defined in this module:
338 +----------------------------------+---------------------------------------------+
339 | Constant | Meaning |
340 +==================================+=============================================+
341 | :const:`REG_BINARY` | Binary data in any form. |
342 +----------------------------------+---------------------------------------------+
343 | :const:`REG_DWORD` | A 32-bit number. |
344 +----------------------------------+---------------------------------------------+
345 | :const:`REG_DWORD_LITTLE_ENDIAN` | A 32-bit number in little-endian format. |
346 +----------------------------------+---------------------------------------------+
347 | :const:`REG_DWORD_BIG_ENDIAN` | A 32-bit number in big-endian format. |
348 +----------------------------------+---------------------------------------------+
349 | :const:`REG_EXPAND_SZ` | Null-terminated string containing |
350 | | references to environment variables |
352 +----------------------------------+---------------------------------------------+
353 | :const:`REG_LINK` | A Unicode symbolic link. |
354 +----------------------------------+---------------------------------------------+
355 | :const:`REG_MULTI_SZ` | A sequence of null-terminated strings, |
356 | | terminated by two null characters. (Python |
357 | | handles this termination automatically.) |
358 +----------------------------------+---------------------------------------------+
359 | :const:`REG_NONE` | No defined value type. |
360 +----------------------------------+---------------------------------------------+
361 | :const:`REG_RESOURCE_LIST` | A device-driver resource list. |
362 +----------------------------------+---------------------------------------------+
363 | :const:`REG_SZ` | A null-terminated string. |
364 +----------------------------------+---------------------------------------------+
366 *reserved* can be anything - zero is always passed to the API.
368 *value* is a string that specifies the new value.
370 This method can also set additional value and type information for the specified
371 key. The key identified by the key parameter must have been opened with
372 :const:`KEY_SET_VALUE` access.
374 To open the key, use the :func:`CreateKeyEx` or :func:`OpenKey` methods.
376 Value lengths are limited by available memory. Long values (more than 2048
377 bytes) should be stored as files with the filenames stored in the configuration
378 registry. This helps the registry perform efficiently.
383 Registry Handle Objects
384 -----------------------
386 This object wraps a Windows HKEY object, automatically closing it when the
387 object is destroyed. To guarantee cleanup, you can call either the
388 :meth:`Close` method on the object, or the :func:`CloseKey` function.
390 All registry functions in this module return one of these objects.
392 All registry functions in this module which accept a handle object also accept
393 an integer, however, use of the handle object is encouraged.
395 Handle objects provide semantics for :meth:`__nonzero__` - thus ::
400 will print ``Yes`` if the handle is currently valid (has not been closed or
403 The object also support comparison semantics, so handle objects will compare
404 true if they both reference the same underlying Windows handle value.
406 Handle objects can be converted to an integer (e.g., using the builtin
407 :func:`int` function), in which case the underlying Windows handle value is
408 returned. You can also use the :meth:`Detach` method to return the integer
409 handle, and also disconnect the Windows handle from the handle object.
412 .. method:: PyHKEY.Close()
414 Closes the underlying Windows handle.
416 If the handle is already closed, no error is raised.
419 .. method:: PyHKEY.Detach()
421 Detaches the Windows handle from the handle object.
423 The result is an integer (or long on 64 bit Windows) that holds the value of the
424 handle before it is detached. If the handle is already detached or closed, this
427 After calling this function, the handle is effectively invalidated, but the
428 handle is not closed. You would call this function when you need the
429 underlying Win32 handle to exist beyond the lifetime of the handle object.
431 .. method:: PyHKEY.__enter__()
432 PyHKEY.__exit__(\*exc_info)
434 The HKEY object implements :meth:`__enter__` and :meth:`__exit__` and thus
435 supports the context protocol for the :keyword:`with` statement::
437 with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
438 # ... work with key ...
440 will automatically close *key* when control leaves the :keyword:`with` block.
442 .. versionadded:: 2.6