Georg Brandl | 38feaf0 | 2008-05-25 07:45:51 +0000 | [diff] [blame] | 1 | :mod:`winreg` -- Windows registry access |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 2 | ========================================= |
| 3 | |
Georg Brandl | 38feaf0 | 2008-05-25 07:45:51 +0000 | [diff] [blame] | 4 | .. module:: winreg |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 5 | :platform: Windows |
| 6 | :synopsis: Routines and objects for manipulating the Windows registry. |
| 7 | .. sectionauthor:: Mark Hammond <MarkH@ActiveState.com> |
| 8 | |
| 9 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | These functions expose the Windows registry API to Python. Instead of using an |
| 11 | integer as the registry handle, a handle object is used to ensure that the |
| 12 | handles are closed correctly, even if the programmer neglects to explicitly |
| 13 | close them. |
| 14 | |
| 15 | This module exposes a very low-level interface to the Windows registry; it is |
| 16 | expected that in the future a new ``winreg`` module will be created offering a |
| 17 | higher-level interface to the registry API. |
| 18 | |
| 19 | This module offers the following functions: |
| 20 | |
| 21 | |
| 22 | .. function:: CloseKey(hkey) |
| 23 | |
| 24 | Closes a previously opened registry key. The hkey argument specifies a |
| 25 | previously opened key. |
| 26 | |
| 27 | Note that if *hkey* is not closed using this method (or via |
| 28 | :meth:`handle.Close`), it is closed when the *hkey* object is destroyed by |
| 29 | Python. |
| 30 | |
| 31 | |
| 32 | .. function:: ConnectRegistry(computer_name, key) |
| 33 | |
| 34 | Establishes a connection to a predefined registry handle on another computer, |
| 35 | and returns a :dfn:`handle object` |
| 36 | |
| 37 | *computer_name* is the name of the remote computer, of the form |
| 38 | ``r"\\computername"``. If ``None``, the local computer is used. |
| 39 | |
| 40 | *key* is the predefined handle to connect to. |
| 41 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 42 | The return value is the handle of the opened key. If the function fails, a |
| 43 | :exc:`WindowsError` exception is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 44 | |
| 45 | |
| 46 | .. function:: CreateKey(key, sub_key) |
| 47 | |
| 48 | Creates or opens the specified key, returning a :dfn:`handle object` |
| 49 | |
| 50 | *key* is an already open key, or one of the predefined :const:`HKEY_\*` |
| 51 | constants. |
| 52 | |
| 53 | *sub_key* is a string that names the key this method opens or creates. |
| 54 | |
| 55 | If *key* is one of the predefined keys, *sub_key* may be ``None``. In that |
| 56 | case, the handle returned is the same key handle passed in to the function. |
| 57 | |
| 58 | If the key already exists, this function opens the existing key. |
| 59 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 60 | The return value is the handle of the opened key. If the function fails, a |
| 61 | :exc:`WindowsError` exception is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 62 | |
| 63 | |
| 64 | .. function:: DeleteKey(key, sub_key) |
| 65 | |
| 66 | Deletes the specified key. |
| 67 | |
| 68 | *key* is an already open key, or any one of the predefined :const:`HKEY_\*` |
| 69 | constants. |
| 70 | |
| 71 | *sub_key* is a string that must be a subkey of the key identified by the *key* |
| 72 | parameter. This value must not be ``None``, and the key may not have subkeys. |
| 73 | |
| 74 | *This method can not delete keys with subkeys.* |
| 75 | |
| 76 | If the method succeeds, the entire key, including all of its values, is removed. |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 77 | If the method fails, a :exc:`WindowsError` exception is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | |
| 79 | |
| 80 | .. function:: DeleteValue(key, value) |
| 81 | |
| 82 | Removes a named value from a registry key. |
| 83 | |
| 84 | *key* is an already open key, or one of the predefined :const:`HKEY_\*` |
| 85 | constants. |
| 86 | |
| 87 | *value* is a string that identifies the value to remove. |
| 88 | |
| 89 | |
| 90 | .. function:: EnumKey(key, index) |
| 91 | |
| 92 | Enumerates subkeys of an open registry key, returning a string. |
| 93 | |
| 94 | *key* is an already open key, or any one of the predefined :const:`HKEY_\*` |
| 95 | constants. |
| 96 | |
| 97 | *index* is an integer that identifies the index of the key to retrieve. |
| 98 | |
| 99 | The function retrieves the name of one subkey each time it is called. It is |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 100 | typically called repeatedly until a :exc:`WindowsError` exception is |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 101 | raised, indicating, no more values are available. |
| 102 | |
| 103 | |
| 104 | .. function:: EnumValue(key, index) |
| 105 | |
| 106 | Enumerates values of an open registry key, returning a tuple. |
| 107 | |
| 108 | *key* is an already open key, or any one of the predefined :const:`HKEY_\*` |
| 109 | constants. |
| 110 | |
| 111 | *index* is an integer that identifies the index of the value to retrieve. |
| 112 | |
| 113 | The function retrieves the name of one subkey each time it is called. It is |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 114 | typically called repeatedly, until a :exc:`WindowsError` exception is |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | raised, indicating no more values. |
| 116 | |
| 117 | The result is a tuple of 3 items: |
| 118 | |
| 119 | +-------+--------------------------------------------+ |
| 120 | | Index | Meaning | |
| 121 | +=======+============================================+ |
| 122 | | ``0`` | A string that identifies the value name | |
| 123 | +-------+--------------------------------------------+ |
| 124 | | ``1`` | An object that holds the value data, and | |
| 125 | | | whose type depends on the underlying | |
| 126 | | | registry type | |
| 127 | +-------+--------------------------------------------+ |
| 128 | | ``2`` | An integer that identifies the type of the | |
| 129 | | | value data | |
| 130 | +-------+--------------------------------------------+ |
| 131 | |
| 132 | |
Christian Heimes | 2380ac7 | 2008-01-09 00:17:24 +0000 | [diff] [blame] | 133 | .. function:: ExpandEnvironmentStrings(unicode) |
| 134 | |
| 135 | Expands environment strings %NAME% in unicode string like const:`REG_EXPAND_SZ`:: |
| 136 | |
| 137 | >>> ExpandEnvironmentStrings(u"%windir%") |
| 138 | u"C:\\Windows" |
| 139 | |
Christian Heimes | 2380ac7 | 2008-01-09 00:17:24 +0000 | [diff] [blame] | 140 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 141 | .. function:: FlushKey(key) |
| 142 | |
| 143 | Writes all the attributes of a key to the registry. |
| 144 | |
| 145 | *key* is an already open key, or one of the predefined :const:`HKEY_\*` |
| 146 | constants. |
| 147 | |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 148 | It is not necessary to call :func:`FlushKey` to change a key. Registry changes are |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 149 | flushed to disk by the registry using its lazy flusher. Registry changes are |
| 150 | also flushed to disk at system shutdown. Unlike :func:`CloseKey`, the |
| 151 | :func:`FlushKey` method returns only when all the data has been written to the |
| 152 | registry. An application should only call :func:`FlushKey` if it requires |
| 153 | absolute certainty that registry changes are on disk. |
| 154 | |
| 155 | .. note:: |
| 156 | |
| 157 | If you don't know whether a :func:`FlushKey` call is required, it probably |
| 158 | isn't. |
| 159 | |
| 160 | |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 161 | .. function:: LoadKey(key, sub_key, file_name) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 162 | |
| 163 | Creates a subkey under the specified key and stores registration information |
| 164 | from a specified file into that subkey. |
| 165 | |
| 166 | *key* is an already open key, or any of the predefined :const:`HKEY_\*` |
| 167 | constants. |
| 168 | |
| 169 | *sub_key* is a string that identifies the sub_key to load. |
| 170 | |
| 171 | *file_name* is the name of the file to load registry data from. This file must |
| 172 | have been created with the :func:`SaveKey` function. Under the file allocation |
| 173 | table (FAT) file system, the filename may not have an extension. |
| 174 | |
| 175 | A call to LoadKey() fails if the calling process does not have the |
| 176 | :const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different than |
| 177 | permissions - see the Win32 documentation for more details. |
| 178 | |
| 179 | If *key* is a handle returned by :func:`ConnectRegistry`, then the path |
| 180 | specified in *fileName* is relative to the remote computer. |
| 181 | |
| 182 | The Win32 documentation implies *key* must be in the :const:`HKEY_USER` or |
| 183 | :const:`HKEY_LOCAL_MACHINE` tree. This may or may not be true. |
| 184 | |
| 185 | |
| 186 | .. function:: OpenKey(key, sub_key[, res=0][, sam=KEY_READ]) |
| 187 | |
| 188 | Opens the specified key, returning a :dfn:`handle object` |
| 189 | |
| 190 | *key* is an already open key, or any one of the predefined :const:`HKEY_\*` |
| 191 | constants. |
| 192 | |
| 193 | *sub_key* is a string that identifies the sub_key to open. |
| 194 | |
| 195 | *res* is a reserved integer, and must be zero. The default is zero. |
| 196 | |
| 197 | *sam* is an integer that specifies an access mask that describes the desired |
| 198 | security access for the key. Default is :const:`KEY_READ` |
| 199 | |
| 200 | The result is a new handle to the specified key. |
| 201 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 202 | If the function fails, :exc:`WindowsError` is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 203 | |
| 204 | |
| 205 | .. function:: OpenKeyEx() |
| 206 | |
| 207 | The functionality of :func:`OpenKeyEx` is provided via :func:`OpenKey`, by the |
| 208 | use of default arguments. |
| 209 | |
| 210 | |
| 211 | .. function:: QueryInfoKey(key) |
| 212 | |
| 213 | Returns information about a key, as a tuple. |
| 214 | |
| 215 | *key* is an already open key, or one of the predefined :const:`HKEY_\*` |
| 216 | constants. |
| 217 | |
| 218 | The result is a tuple of 3 items: |
| 219 | |
| 220 | +-------+---------------------------------------------+ |
| 221 | | Index | Meaning | |
| 222 | +=======+=============================================+ |
| 223 | | ``0`` | An integer giving the number of sub keys | |
| 224 | | | this key has. | |
| 225 | +-------+---------------------------------------------+ |
| 226 | | ``1`` | An integer giving the number of values this | |
| 227 | | | key has. | |
| 228 | +-------+---------------------------------------------+ |
Georg Brandl | ba956ae | 2007-11-29 17:24:34 +0000 | [diff] [blame] | 229 | | ``2`` | An integer giving when the key was last | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 230 | | | modified (if available) as 100's of | |
| 231 | | | nanoseconds since Jan 1, 1600. | |
| 232 | +-------+---------------------------------------------+ |
| 233 | |
| 234 | |
| 235 | .. function:: QueryValue(key, sub_key) |
| 236 | |
| 237 | Retrieves the unnamed value for a key, as a string |
| 238 | |
| 239 | *key* is an already open key, or one of the predefined :const:`HKEY_\*` |
| 240 | constants. |
| 241 | |
| 242 | *sub_key* is a string that holds the name of the subkey with which the value is |
| 243 | associated. If this parameter is ``None`` or empty, the function retrieves the |
| 244 | value set by the :func:`SetValue` method for the key identified by *key*. |
| 245 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 246 | Values in the registry have name, type, and data components. This method |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 247 | retrieves the data for a key's first value that has a NULL name. But the |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 248 | underlying API call doesn't return the type, so always use |
| 249 | :func:`QueryValueEx` if possible. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 250 | |
| 251 | |
| 252 | .. function:: QueryValueEx(key, value_name) |
| 253 | |
| 254 | Retrieves the type and data for a specified value name associated with an open |
| 255 | registry key. |
| 256 | |
| 257 | *key* is an already open key, or one of the predefined :const:`HKEY_\*` |
| 258 | constants. |
| 259 | |
| 260 | *value_name* is a string indicating the value to query. |
| 261 | |
| 262 | The result is a tuple of 2 items: |
| 263 | |
| 264 | +-------+-----------------------------------------+ |
| 265 | | Index | Meaning | |
| 266 | +=======+=========================================+ |
| 267 | | ``0`` | The value of the registry item. | |
| 268 | +-------+-----------------------------------------+ |
| 269 | | ``1`` | An integer giving the registry type for | |
| 270 | | | this value. | |
| 271 | +-------+-----------------------------------------+ |
| 272 | |
| 273 | |
| 274 | .. function:: SaveKey(key, file_name) |
| 275 | |
| 276 | Saves the specified key, and all its subkeys to the specified file. |
| 277 | |
| 278 | *key* is an already open key, or one of the predefined :const:`HKEY_\*` |
| 279 | constants. |
| 280 | |
| 281 | *file_name* is the name of the file to save registry data to. This file cannot |
| 282 | already exist. If this filename includes an extension, it cannot be used on file |
| 283 | allocation table (FAT) file systems by the :meth:`LoadKey`, :meth:`ReplaceKey` |
| 284 | or :meth:`RestoreKey` methods. |
| 285 | |
| 286 | If *key* represents a key on a remote computer, the path described by |
| 287 | *file_name* is relative to the remote computer. The caller of this method must |
| 288 | possess the :const:`SeBackupPrivilege` security privilege. Note that |
| 289 | privileges are different than permissions - see the Win32 documentation for |
| 290 | more details. |
| 291 | |
| 292 | This function passes NULL for *security_attributes* to the API. |
| 293 | |
| 294 | |
| 295 | .. function:: SetValue(key, sub_key, type, value) |
| 296 | |
| 297 | Associates a value with a specified key. |
| 298 | |
| 299 | *key* is an already open key, or one of the predefined :const:`HKEY_\*` |
| 300 | constants. |
| 301 | |
| 302 | *sub_key* is a string that names the subkey with which the value is associated. |
| 303 | |
| 304 | *type* is an integer that specifies the type of the data. Currently this must be |
| 305 | :const:`REG_SZ`, meaning only strings are supported. Use the :func:`SetValueEx` |
| 306 | function for support for other data types. |
| 307 | |
| 308 | *value* is a string that specifies the new value. |
| 309 | |
| 310 | If the key specified by the *sub_key* parameter does not exist, the SetValue |
| 311 | function creates it. |
| 312 | |
| 313 | Value lengths are limited by available memory. Long values (more than 2048 |
| 314 | bytes) should be stored as files with the filenames stored in the configuration |
| 315 | registry. This helps the registry perform efficiently. |
| 316 | |
| 317 | The key identified by the *key* parameter must have been opened with |
| 318 | :const:`KEY_SET_VALUE` access. |
| 319 | |
| 320 | |
| 321 | .. function:: SetValueEx(key, value_name, reserved, type, value) |
| 322 | |
| 323 | Stores data in the value field of an open registry key. |
| 324 | |
| 325 | *key* is an already open key, or one of the predefined :const:`HKEY_\*` |
| 326 | constants. |
| 327 | |
| 328 | *value_name* is a string that names the subkey with which the value is |
| 329 | associated. |
| 330 | |
| 331 | *type* is an integer that specifies the type of the data. This should be one |
| 332 | of the following constants defined in this module: |
| 333 | |
| 334 | +----------------------------------+---------------------------------------------+ |
| 335 | | Constant | Meaning | |
| 336 | +==================================+=============================================+ |
| 337 | | :const:`REG_BINARY` | Binary data in any form. | |
| 338 | +----------------------------------+---------------------------------------------+ |
| 339 | | :const:`REG_DWORD` | A 32-bit number. | |
| 340 | +----------------------------------+---------------------------------------------+ |
| 341 | | :const:`REG_DWORD_LITTLE_ENDIAN` | A 32-bit number in little-endian format. | |
| 342 | +----------------------------------+---------------------------------------------+ |
| 343 | | :const:`REG_DWORD_BIG_ENDIAN` | A 32-bit number in big-endian format. | |
| 344 | +----------------------------------+---------------------------------------------+ |
| 345 | | :const:`REG_EXPAND_SZ` | Null-terminated string containing | |
| 346 | | | references to environment variables | |
| 347 | | | (``%PATH%``). | |
| 348 | +----------------------------------+---------------------------------------------+ |
| 349 | | :const:`REG_LINK` | A Unicode symbolic link. | |
| 350 | +----------------------------------+---------------------------------------------+ |
| 351 | | :const:`REG_MULTI_SZ` | A sequence of null-terminated strings, | |
| 352 | | | terminated by two null characters. (Python | |
| 353 | | | handles this termination automatically.) | |
| 354 | +----------------------------------+---------------------------------------------+ |
| 355 | | :const:`REG_NONE` | No defined value type. | |
| 356 | +----------------------------------+---------------------------------------------+ |
| 357 | | :const:`REG_RESOURCE_LIST` | A device-driver resource list. | |
| 358 | +----------------------------------+---------------------------------------------+ |
| 359 | | :const:`REG_SZ` | A null-terminated string. | |
| 360 | +----------------------------------+---------------------------------------------+ |
| 361 | |
| 362 | *reserved* can be anything - zero is always passed to the API. |
| 363 | |
| 364 | *value* is a string that specifies the new value. |
| 365 | |
| 366 | This method can also set additional value and type information for the specified |
| 367 | key. The key identified by the key parameter must have been opened with |
| 368 | :const:`KEY_SET_VALUE` access. |
| 369 | |
| 370 | To open the key, use the :func:`CreateKeyEx` or :func:`OpenKey` methods. |
| 371 | |
| 372 | Value lengths are limited by available memory. Long values (more than 2048 |
| 373 | bytes) should be stored as files with the filenames stored in the configuration |
| 374 | registry. This helps the registry perform efficiently. |
| 375 | |
| 376 | |
| 377 | .. _handle-object: |
| 378 | |
| 379 | Registry Handle Objects |
| 380 | ----------------------- |
| 381 | |
| 382 | This object wraps a Windows HKEY object, automatically closing it when the |
| 383 | object is destroyed. To guarantee cleanup, you can call either the |
| 384 | :meth:`Close` method on the object, or the :func:`CloseKey` function. |
| 385 | |
| 386 | All registry functions in this module return one of these objects. |
| 387 | |
| 388 | All registry functions in this module which accept a handle object also accept |
| 389 | an integer, however, use of the handle object is encouraged. |
| 390 | |
| 391 | Handle objects provide semantics for :meth:`__bool__` - thus :: |
| 392 | |
| 393 | if handle: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 394 | print("Yes") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 395 | |
| 396 | will print ``Yes`` if the handle is currently valid (has not been closed or |
| 397 | detached). |
| 398 | |
| 399 | The object also support comparison semantics, so handle objects will compare |
| 400 | true if they both reference the same underlying Windows handle value. |
| 401 | |
| 402 | Handle objects can be converted to an integer (e.g., using the builtin |
| 403 | :func:`int` function), in which case the underlying Windows handle value is |
| 404 | returned. You can also use the :meth:`Detach` method to return the integer |
| 405 | handle, and also disconnect the Windows handle from the handle object. |
| 406 | |
| 407 | |
| 408 | .. method:: PyHKEY.Close() |
| 409 | |
| 410 | Closes the underlying Windows handle. |
| 411 | |
| 412 | If the handle is already closed, no error is raised. |
| 413 | |
| 414 | |
| 415 | .. method:: PyHKEY.Detach() |
| 416 | |
| 417 | Detaches the Windows handle from the handle object. |
| 418 | |
Georg Brandl | 5c10664 | 2007-11-29 17:41:05 +0000 | [diff] [blame] | 419 | The result is an integer that holds the value of the handle before it is |
| 420 | detached. If the handle is already detached or closed, this will return |
| 421 | zero. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 422 | |
| 423 | After calling this function, the handle is effectively invalidated, but the |
| 424 | handle is not closed. You would call this function when you need the |
| 425 | underlying Win32 handle to exist beyond the lifetime of the handle object. |
| 426 | |
Christian Heimes | 2380ac7 | 2008-01-09 00:17:24 +0000 | [diff] [blame] | 427 | .. method:: PyHKEY.__enter__() |
| 428 | PyHKEY.__exit__(\*exc_info) |
| 429 | |
| 430 | The HKEY object implements :meth:`__enter__` and :meth:`__exit__` and thus |
| 431 | supports the context protocol for the :keyword:`with` statement:: |
| 432 | |
| 433 | with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key: |
| 434 | # ... work with key ... |
| 435 | |
| 436 | will automatically close *key* when control leaves the :keyword:`with` block. |
| 437 | |
Christian Heimes | 2380ac7 | 2008-01-09 00:17:24 +0000 | [diff] [blame] | 438 | |