| 1 |
:mod:`!winreg` --- Windows registry access |
| 2 |
========================================== |
| 3 |
|
| 4 |
.. module:: winreg |
| 5 |
:synopsis: Routines and objects for manipulating the Windows registry. |
| 6 |
|
| 7 |
.. sectionauthor:: Mark Hammond <[email protected]> |
| 8 |
|
| 9 |
-------------- |
| 10 |
|
| 11 |
These functions expose the Windows registry API to Python. Instead of using an |
| 12 |
integer as the registry handle, a :ref:`handle object <handle-object>` is used |
| 13 |
to ensure that the handles are closed correctly, even if the programmer neglects |
| 14 |
to explicitly close them. |
| 15 |
|
| 16 |
.. availability:: Windows. |
| 17 |
|
| 18 |
.. _exception-changed: |
| 19 |
|
| 20 |
.. versionchanged:: 3.3 |
| 21 |
Several functions in this module used to raise a |
| 22 |
:exc:`WindowsError`, which is now an alias of :exc:`OSError`. |
| 23 |
|
| 24 |
.. _functions: |
| 25 |
|
| 26 |
Functions |
| 27 |
------------------ |
| 28 |
|
| 29 |
This module offers the following functions: |
| 30 |
|
| 31 |
|
| 32 |
.. function:: CloseKey(hkey) |
| 33 |
|
| 34 |
Closes a previously opened registry key. The *hkey* argument specifies a |
| 35 |
previously opened key. |
| 36 |
|
| 37 |
.. note:: |
| 38 |
|
| 39 |
If *hkey* is not closed using this method (or via :meth:`hkey.Close() |
| 40 |
<PyHKEY.Close>`), it is closed when the *hkey* object is destroyed by |
| 41 |
Python. |
| 42 |
|
| 43 |
|
| 44 |
.. function:: ConnectRegistry(computer_name, key) |
| 45 |
|
| 46 |
Establishes a connection to a predefined registry handle on another computer, |
| 47 |
and returns a :ref:`handle object <handle-object>`. |
| 48 |
|
| 49 |
*computer_name* is the name of the remote computer, of the form |
| 50 |
``r"\\computername"``. If ``None``, the local computer is used. |
| 51 |
|
| 52 |
*key* is the predefined handle to connect to. |
| 53 |
|
| 54 |
The return value is the handle of the opened key. If the function fails, an |
| 55 |
:exc:`OSError` exception is raised. |
| 56 |
|
| 57 |
.. audit-event:: winreg.ConnectRegistry computer_name,key winreg.ConnectRegistry |
| 58 |
|
| 59 |
.. versionchanged:: 3.3 |
| 60 |
See :ref:`above <exception-changed>`. |
| 61 |
|
| 62 |
|
| 63 |
.. function:: CreateKey(key, sub_key) |
| 64 |
|
| 65 |
Creates or opens the specified key, returning a |
| 66 |
:ref:`handle object <handle-object>`. |
| 67 |
|
| 68 |
*key* is an already open key, or one of the predefined |
| 69 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 70 |
|
| 71 |
*sub_key* is a string that names the key this method opens or creates. |
| 72 |
|
| 73 |
If *key* is one of the predefined keys, *sub_key* may be ``None``. In that |
| 74 |
case, the handle returned is the same key handle passed in to the function. |
| 75 |
|
| 76 |
If the key already exists, this function opens the existing key. |
| 77 |
|
| 78 |
The return value is the handle of the opened key. If the function fails, an |
| 79 |
:exc:`OSError` exception is raised. |
| 80 |
|
| 81 |
.. audit-event:: winreg.CreateKey key,sub_key,access winreg.CreateKey |
| 82 |
|
| 83 |
.. audit-event:: winreg.OpenKey/result key winreg.CreateKey |
| 84 |
|
| 85 |
.. versionchanged:: 3.3 |
| 86 |
See :ref:`above <exception-changed>`. |
| 87 |
|
| 88 |
|
| 89 |
.. function:: CreateKeyEx(key, sub_key, reserved=0, access=KEY_WRITE) |
| 90 |
|
| 91 |
Creates or opens the specified key, returning a |
| 92 |
:ref:`handle object <handle-object>`. |
| 93 |
|
| 94 |
*key* is an already open key, or one of the predefined |
| 95 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 96 |
|
| 97 |
*sub_key* is a string that names the key this method opens or creates. |
| 98 |
|
| 99 |
*reserved* is a reserved integer, and must be zero. The default is zero. |
| 100 |
|
| 101 |
*access* is an integer that specifies an access mask that describes the desired |
| 102 |
security access for the key. Default is :const:`KEY_WRITE`. See |
| 103 |
:ref:`Access Rights <access-rights>` for other allowed values. |
| 104 |
|
| 105 |
If *key* is one of the predefined keys, *sub_key* may be ``None``. In that |
| 106 |
case, the handle returned is the same key handle passed in to the function. |
| 107 |
|
| 108 |
If the key already exists, this function opens the existing key. |
| 109 |
|
| 110 |
The return value is the handle of the opened key. If the function fails, an |
| 111 |
:exc:`OSError` exception is raised. |
| 112 |
|
| 113 |
.. audit-event:: winreg.CreateKey key,sub_key,access winreg.CreateKeyEx |
| 114 |
|
| 115 |
.. audit-event:: winreg.OpenKey/result key winreg.CreateKeyEx |
| 116 |
|
| 117 |
.. versionadded:: 3.2 |
| 118 |
|
| 119 |
.. versionchanged:: 3.3 |
| 120 |
See :ref:`above <exception-changed>`. |
| 121 |
|
| 122 |
|
| 123 |
.. function:: DeleteKey(key, sub_key) |
| 124 |
|
| 125 |
Deletes the specified key. |
| 126 |
|
| 127 |
*key* is an already open key, or one of the predefined |
| 128 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 129 |
|
| 130 |
*sub_key* is a string that must be a subkey of the key identified by the *key* |
| 131 |
parameter. This value must not be ``None``, and the key may not have subkeys. |
| 132 |
|
| 133 |
*This method can not delete keys with subkeys.* |
| 134 |
|
| 135 |
If the method succeeds, the entire key, including all of its values, is removed. |
| 136 |
If the method fails, an :exc:`OSError` exception is raised. |
| 137 |
|
| 138 |
.. audit-event:: winreg.DeleteKey key,sub_key,access winreg.DeleteKey |
| 139 |
|
| 140 |
.. versionchanged:: 3.3 |
| 141 |
See :ref:`above <exception-changed>`. |
| 142 |
|
| 143 |
|
| 144 |
.. function:: DeleteKeyEx(key, sub_key, access=KEY_WOW64_64KEY, reserved=0) |
| 145 |
|
| 146 |
Deletes the specified key. |
| 147 |
|
| 148 |
*key* is an already open key, or one of the predefined |
| 149 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 150 |
|
| 151 |
*sub_key* is a string that must be a subkey of the key identified by the |
| 152 |
*key* parameter. This value must not be ``None``, and the key may not have |
| 153 |
subkeys. |
| 154 |
|
| 155 |
*reserved* is a reserved integer, and must be zero. The default is zero. |
| 156 |
|
| 157 |
*access* is an integer that specifies an access mask that describes the |
| 158 |
desired security access for the key. Default is :const:`KEY_WOW64_64KEY`. |
| 159 |
On 32-bit Windows, the WOW64 constants are ignored. |
| 160 |
See :ref:`Access Rights <access-rights>` for other allowed values. |
| 161 |
|
| 162 |
*This method can not delete keys with subkeys.* |
| 163 |
|
| 164 |
If the method succeeds, the entire key, including all of its values, is |
| 165 |
removed. If the method fails, an :exc:`OSError` exception is raised. |
| 166 |
|
| 167 |
On unsupported Windows versions, :exc:`NotImplementedError` is raised. |
| 168 |
|
| 169 |
.. audit-event:: winreg.DeleteKey key,sub_key,access winreg.DeleteKeyEx |
| 170 |
|
| 171 |
.. versionadded:: 3.2 |
| 172 |
|
| 173 |
.. versionchanged:: 3.3 |
| 174 |
See :ref:`above <exception-changed>`. |
| 175 |
|
| 176 |
|
| 177 |
.. function:: DeleteValue(key, value) |
| 178 |
|
| 179 |
Removes a named value from a registry key. |
| 180 |
|
| 181 |
*key* is an already open key, or one of the predefined |
| 182 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 183 |
|
| 184 |
*value* is a string that identifies the value to remove. |
| 185 |
|
| 186 |
.. audit-event:: winreg.DeleteValue key,value winreg.DeleteValue |
| 187 |
|
| 188 |
|
| 189 |
.. function:: EnumKey(key, index) |
| 190 |
|
| 191 |
Enumerates subkeys of an open registry key, returning a string. |
| 192 |
|
| 193 |
*key* is an already open key, or one of the predefined |
| 194 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 195 |
|
| 196 |
*index* is an integer that identifies the index of the key to retrieve. |
| 197 |
|
| 198 |
The function retrieves the name of one subkey each time it is called. It is |
| 199 |
typically called repeatedly until an :exc:`OSError` exception is |
| 200 |
raised, indicating, no more values are available. |
| 201 |
|
| 202 |
.. audit-event:: winreg.EnumKey key,index winreg.EnumKey |
| 203 |
|
| 204 |
.. versionchanged:: 3.3 |
| 205 |
See :ref:`above <exception-changed>`. |
| 206 |
|
| 207 |
|
| 208 |
.. function:: EnumValue(key, index) |
| 209 |
|
| 210 |
Enumerates values of an open registry key, returning a tuple. |
| 211 |
|
| 212 |
*key* is an already open key, or one of the predefined |
| 213 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 214 |
|
| 215 |
*index* is an integer that identifies the index of the value to retrieve. |
| 216 |
|
| 217 |
The function retrieves the name of one subkey each time it is called. It is |
| 218 |
typically called repeatedly, until an :exc:`OSError` exception is |
| 219 |
raised, indicating no more values. |
| 220 |
|
| 221 |
The result is a tuple of 3 items: |
| 222 |
|
| 223 |
+-------+--------------------------------------------+ |
| 224 |
| Index | Meaning | |
| 225 |
+=======+============================================+ |
| 226 |
| ``0`` | A string that identifies the value name | |
| 227 |
+-------+--------------------------------------------+ |
| 228 |
| ``1`` | An object that holds the value data, and | |
| 229 |
| | whose type depends on the underlying | |
| 230 |
| | registry type | |
| 231 |
+-------+--------------------------------------------+ |
| 232 |
| ``2`` | An integer that identifies the type of the | |
| 233 |
| | value data (see table in docs for | |
| 234 |
| | :meth:`SetValueEx`) | |
| 235 |
+-------+--------------------------------------------+ |
| 236 |
|
| 237 |
.. audit-event:: winreg.EnumValue key,index winreg.EnumValue |
| 238 |
|
| 239 |
.. versionchanged:: 3.3 |
| 240 |
See :ref:`above <exception-changed>`. |
| 241 |
|
| 242 |
|
| 243 |
.. index:: |
| 244 |
single: % (percent); environment variables expansion (Windows) |
| 245 |
|
| 246 |
.. function:: ExpandEnvironmentStrings(str) |
| 247 |
|
| 248 |
Expands environment variable placeholders ``%NAME%`` in strings like |
| 249 |
:const:`REG_EXPAND_SZ`:: |
| 250 |
|
| 251 |
>>> ExpandEnvironmentStrings('%windir%') |
| 252 |
'C:\\Windows' |
| 253 |
|
| 254 |
.. audit-event:: winreg.ExpandEnvironmentStrings str winreg.ExpandEnvironmentStrings |
| 255 |
|
| 256 |
|
| 257 |
.. function:: FlushKey(key) |
| 258 |
|
| 259 |
Writes all the attributes of a key to the registry. |
| 260 |
|
| 261 |
*key* is an already open key, or one of the predefined |
| 262 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 263 |
|
| 264 |
It is not necessary to call :func:`FlushKey` to change a key. Registry changes are |
| 265 |
flushed to disk by the registry using its lazy flusher. Registry changes are |
| 266 |
also flushed to disk at system shutdown. Unlike :func:`CloseKey`, the |
| 267 |
:func:`FlushKey` method returns only when all the data has been written to the |
| 268 |
registry. An application should only call :func:`FlushKey` if it requires |
| 269 |
absolute certainty that registry changes are on disk. |
| 270 |
|
| 271 |
.. note:: |
| 272 |
|
| 273 |
If you don't know whether a :func:`FlushKey` call is required, it probably |
| 274 |
isn't. |
| 275 |
|
| 276 |
|
| 277 |
.. function:: LoadKey(key, sub_key, file_name) |
| 278 |
|
| 279 |
Creates a subkey under the specified key and stores registration information |
| 280 |
from a specified file into that subkey. |
| 281 |
|
| 282 |
*key* is a handle returned by :func:`ConnectRegistry` or one of the constants |
| 283 |
:const:`HKEY_USERS` or :const:`HKEY_LOCAL_MACHINE`. |
| 284 |
|
| 285 |
*sub_key* is a string that identifies the subkey to load. |
| 286 |
|
| 287 |
*file_name* is the name of the file to load registry data from. This file must |
| 288 |
have been created with the :func:`SaveKey` function. Under the file allocation |
| 289 |
table (FAT) file system, the filename may not have an extension. |
| 290 |
|
| 291 |
A call to :func:`LoadKey` fails if the calling process does not have the |
| 292 |
:c:data:`!SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different |
| 293 |
from permissions -- see the `RegLoadKey documentation |
| 294 |
<https://msdn.microsoft.com/en-us/library/ms724889%28v=VS.85%29.aspx>`__ for |
| 295 |
more details. |
| 296 |
|
| 297 |
If *key* is a handle returned by :func:`ConnectRegistry`, then the path |
| 298 |
specified in *file_name* is relative to the remote computer. |
| 299 |
|
| 300 |
.. audit-event:: winreg.LoadKey key,sub_key,file_name winreg.LoadKey |
| 301 |
|
| 302 |
|
| 303 |
.. function:: OpenKey(key, sub_key, reserved=0, access=KEY_READ) |
| 304 |
OpenKeyEx(key, sub_key, reserved=0, access=KEY_READ) |
| 305 |
|
| 306 |
Opens the specified key, returning a :ref:`handle object <handle-object>`. |
| 307 |
|
| 308 |
*key* is an already open key, or one of the predefined |
| 309 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 310 |
|
| 311 |
*sub_key* is a string that identifies the sub_key to open. |
| 312 |
|
| 313 |
*reserved* is a reserved integer, and must be zero. The default is zero. |
| 314 |
|
| 315 |
*access* is an integer that specifies an access mask that describes the desired |
| 316 |
security access for the key. Default is :const:`KEY_READ`. See :ref:`Access |
| 317 |
Rights <access-rights>` for other allowed values. |
| 318 |
|
| 319 |
The result is a new handle to the specified key. |
| 320 |
|
| 321 |
If the function fails, :exc:`OSError` is raised. |
| 322 |
|
| 323 |
.. audit-event:: winreg.OpenKey key,sub_key,access winreg.OpenKey |
| 324 |
|
| 325 |
.. audit-event:: winreg.OpenKey/result key winreg.OpenKey |
| 326 |
|
| 327 |
.. versionchanged:: 3.2 |
| 328 |
Allow the use of named arguments. |
| 329 |
|
| 330 |
.. versionchanged:: 3.3 |
| 331 |
See :ref:`above <exception-changed>`. |
| 332 |
|
| 333 |
|
| 334 |
.. function:: QueryInfoKey(key) |
| 335 |
|
| 336 |
Returns information about a key, as a tuple. |
| 337 |
|
| 338 |
*key* is an already open key, or one of the predefined |
| 339 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 340 |
|
| 341 |
The result is a tuple of 3 items: |
| 342 |
|
| 343 |
+-------+---------------------------------------------+ |
| 344 |
| Index | Meaning | |
| 345 |
+=======+=============================================+ |
| 346 |
| ``0`` | An integer giving the number of sub keys | |
| 347 |
| | this key has. | |
| 348 |
+-------+---------------------------------------------+ |
| 349 |
| ``1`` | An integer giving the number of values this | |
| 350 |
| | key has. | |
| 351 |
+-------+---------------------------------------------+ |
| 352 |
| ``2`` | An integer giving when the key was last | |
| 353 |
| | modified (if available) as 100's of | |
| 354 |
| | nanoseconds since Jan 1, 1601. | |
| 355 |
+-------+---------------------------------------------+ |
| 356 |
|
| 357 |
.. audit-event:: winreg.QueryInfoKey key winreg.QueryInfoKey |
| 358 |
|
| 359 |
|
| 360 |
.. function:: QueryValue(key, sub_key) |
| 361 |
|
| 362 |
Retrieves the unnamed value for a key, as a string. |
| 363 |
|
| 364 |
*key* is an already open key, or one of the predefined |
| 365 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 366 |
|
| 367 |
*sub_key* is a string that holds the name of the subkey with which the value is |
| 368 |
associated. If this parameter is ``None`` or empty, the function retrieves the |
| 369 |
value set by the :func:`SetValue` method for the key identified by *key*. |
| 370 |
|
| 371 |
Values in the registry have name, type, and data components. This method |
| 372 |
retrieves the data for a key's first value that has a ``NULL`` name. But the |
| 373 |
underlying API call doesn't return the type, so always use |
| 374 |
:func:`QueryValueEx` if possible. |
| 375 |
|
| 376 |
.. audit-event:: winreg.QueryValue key,sub_key,value_name winreg.QueryValue |
| 377 |
|
| 378 |
|
| 379 |
.. function:: QueryValueEx(key, value_name) |
| 380 |
|
| 381 |
Retrieves the type and data for a specified value name associated with |
| 382 |
an open registry key. |
| 383 |
|
| 384 |
*key* is an already open key, or one of the predefined |
| 385 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 386 |
|
| 387 |
*value_name* is a string indicating the value to query. |
| 388 |
|
| 389 |
The result is a tuple of 2 items: |
| 390 |
|
| 391 |
+-------+-----------------------------------------+ |
| 392 |
| Index | Meaning | |
| 393 |
+=======+=========================================+ |
| 394 |
| ``0`` | The value of the registry item. | |
| 395 |
+-------+-----------------------------------------+ |
| 396 |
| ``1`` | An integer giving the registry type for | |
| 397 |
| | this value (see table in docs for | |
| 398 |
| | :meth:`SetValueEx`) | |
| 399 |
+-------+-----------------------------------------+ |
| 400 |
|
| 401 |
.. audit-event:: winreg.QueryValue key,sub_key,value_name winreg.QueryValueEx |
| 402 |
|
| 403 |
|
| 404 |
.. function:: SaveKey(key, file_name) |
| 405 |
|
| 406 |
Saves the specified key, and all its subkeys to the specified file. |
| 407 |
|
| 408 |
*key* is an already open key, or one of the predefined |
| 409 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 410 |
|
| 411 |
*file_name* is the name of the file to save registry data to. This file |
| 412 |
cannot already exist. If this filename includes an extension, it cannot be |
| 413 |
used on file allocation table (FAT) file systems by the :meth:`LoadKey` |
| 414 |
method. |
| 415 |
|
| 416 |
If *key* represents a key on a remote computer, the path described by |
| 417 |
*file_name* is relative to the remote computer. The caller of this method must |
| 418 |
possess the **SeBackupPrivilege** security privilege. Note that |
| 419 |
privileges are different than permissions -- see the |
| 420 |
`Conflicts Between User Rights and Permissions documentation |
| 421 |
<https://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`__ |
| 422 |
for more details. |
| 423 |
|
| 424 |
This function passes ``NULL`` for *security_attributes* to the API. |
| 425 |
|
| 426 |
.. audit-event:: winreg.SaveKey key,file_name winreg.SaveKey |
| 427 |
|
| 428 |
|
| 429 |
.. function:: SetValue(key, sub_key, type, value) |
| 430 |
|
| 431 |
Associates a value with a specified key. |
| 432 |
|
| 433 |
*key* is an already open key, or one of the predefined |
| 434 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 435 |
|
| 436 |
*sub_key* is a string that names the subkey with which the value is associated. |
| 437 |
|
| 438 |
*type* is an integer that specifies the type of the data. Currently this must be |
| 439 |
:const:`REG_SZ`, meaning only strings are supported. Use the :func:`SetValueEx` |
| 440 |
function for support for other data types. |
| 441 |
|
| 442 |
*value* is a string that specifies the new value. |
| 443 |
|
| 444 |
If the key specified by the *sub_key* parameter does not exist, the SetValue |
| 445 |
function creates it. |
| 446 |
|
| 447 |
Value lengths are limited by available memory. Long values (more than 2048 |
| 448 |
bytes) should be stored as files with the filenames stored in the configuration |
| 449 |
registry. This helps the registry perform efficiently. |
| 450 |
|
| 451 |
The key identified by the *key* parameter must have been opened with |
| 452 |
:const:`KEY_SET_VALUE` access. |
| 453 |
|
| 454 |
.. audit-event:: winreg.SetValue key,sub_key,type,value winreg.SetValue |
| 455 |
|
| 456 |
|
| 457 |
.. function:: SetValueEx(key, value_name, reserved, type, value) |
| 458 |
|
| 459 |
Stores data in the value field of an open registry key. |
| 460 |
|
| 461 |
*key* is an already open key, or one of the predefined |
| 462 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 463 |
|
| 464 |
*value_name* is a string that names the subkey with which the value is |
| 465 |
associated. |
| 466 |
|
| 467 |
*reserved* can be anything -- zero is always passed to the API. |
| 468 |
|
| 469 |
*type* is an integer that specifies the type of the data. See |
| 470 |
:ref:`Value Types <value-types>` for the available types. |
| 471 |
|
| 472 |
*value* is a string that specifies the new value. |
| 473 |
|
| 474 |
This method can also set additional value and type information for the specified |
| 475 |
key. The key identified by the key parameter must have been opened with |
| 476 |
:const:`KEY_SET_VALUE` access. |
| 477 |
|
| 478 |
To open the key, use the :func:`CreateKey` or :func:`OpenKey` methods. |
| 479 |
|
| 480 |
Value lengths are limited by available memory. Long values (more than 2048 |
| 481 |
bytes) should be stored as files with the filenames stored in the configuration |
| 482 |
registry. This helps the registry perform efficiently. |
| 483 |
|
| 484 |
.. audit-event:: winreg.SetValue key,sub_key,type,value winreg.SetValueEx |
| 485 |
|
| 486 |
|
| 487 |
.. function:: DisableReflectionKey(key) |
| 488 |
|
| 489 |
Disables registry reflection for 32-bit processes running on a 64-bit |
| 490 |
operating system. |
| 491 |
|
| 492 |
*key* is an already open key, or one of the predefined :ref:`HKEY_* constants |
| 493 |
<hkey-constants>`. |
| 494 |
|
| 495 |
Will generally raise :exc:`NotImplementedError` if executed on a 32-bit operating |
| 496 |
system. |
| 497 |
|
| 498 |
If the key is not on the reflection list, the function succeeds but has no |
| 499 |
effect. Disabling reflection for a key does not affect reflection of any |
| 500 |
subkeys. |
| 501 |
|
| 502 |
.. audit-event:: winreg.DisableReflectionKey key winreg.DisableReflectionKey |
| 503 |
|
| 504 |
|
| 505 |
.. function:: EnableReflectionKey(key) |
| 506 |
|
| 507 |
Restores registry reflection for the specified disabled key. |
| 508 |
|
| 509 |
*key* is an already open key, or one of the predefined :ref:`HKEY_* constants |
| 510 |
<hkey-constants>`. |
| 511 |
|
| 512 |
Will generally raise :exc:`NotImplementedError` if executed on a 32-bit operating |
| 513 |
system. |
| 514 |
|
| 515 |
Restoring reflection for a key does not affect reflection of any subkeys. |
| 516 |
|
| 517 |
.. audit-event:: winreg.EnableReflectionKey key winreg.EnableReflectionKey |
| 518 |
|
| 519 |
|
| 520 |
.. function:: QueryReflectionKey(key) |
| 521 |
|
| 522 |
Determines the reflection state for the specified key. |
| 523 |
|
| 524 |
*key* is an already open key, or one of the predefined |
| 525 |
:ref:`HKEY_* constants <hkey-constants>`. |
| 526 |
|
| 527 |
Returns ``True`` if reflection is disabled. |
| 528 |
|
| 529 |
Will generally raise :exc:`NotImplementedError` if executed on a 32-bit |
| 530 |
operating system. |
| 531 |
|
| 532 |
.. audit-event:: winreg.QueryReflectionKey key winreg.QueryReflectionKey |
| 533 |
|
| 534 |
|
| 535 |
.. _constants: |
| 536 |
|
| 537 |
Constants |
| 538 |
------------------ |
| 539 |
|
| 540 |
The following constants are defined for use in many :mod:`!winreg` functions. |
| 541 |
|
| 542 |
.. _hkey-constants: |
| 543 |
|
| 544 |
HKEY_* Constants |
| 545 |
++++++++++++++++ |
| 546 |
|
| 547 |
.. data:: HKEY_CLASSES_ROOT |
| 548 |
|
| 549 |
Registry entries subordinate to this key define types (or classes) of |
| 550 |
documents and the properties associated with those types. Shell and |
| 551 |
COM applications use the information stored under this key. |
| 552 |
|
| 553 |
|
| 554 |
.. data:: HKEY_CURRENT_USER |
| 555 |
|
| 556 |
Registry entries subordinate to this key define the preferences of |
| 557 |
the current user. These preferences include the settings of |
| 558 |
environment variables, data about program groups, colors, printers, |
| 559 |
network connections, and application preferences. |
| 560 |
|
| 561 |
.. data:: HKEY_LOCAL_MACHINE |
| 562 |
|
| 563 |
Registry entries subordinate to this key define the physical state |
| 564 |
of the computer, including data about the bus type, system memory, |
| 565 |
and installed hardware and software. |
| 566 |
|
| 567 |
.. data:: HKEY_USERS |
| 568 |
|
| 569 |
Registry entries subordinate to this key define the default user |
| 570 |
configuration for new users on the local computer and the user |
| 571 |
configuration for the current user. |
| 572 |
|
| 573 |
.. data:: HKEY_PERFORMANCE_DATA |
| 574 |
|
| 575 |
Registry entries subordinate to this key allow you to access |
| 576 |
performance data. The data is not actually stored in the registry; |
| 577 |
the registry functions cause the system to collect the data from |
| 578 |
its source. |
| 579 |
|
| 580 |
|
| 581 |
.. data:: HKEY_CURRENT_CONFIG |
| 582 |
|
| 583 |
Contains information about the current hardware profile of the |
| 584 |
local computer system. |
| 585 |
|
| 586 |
.. data:: HKEY_DYN_DATA |
| 587 |
|
| 588 |
This key is not used in versions of Windows after 98. |
| 589 |
|
| 590 |
|
| 591 |
.. _access-rights: |
| 592 |
|
| 593 |
Access Rights |
| 594 |
+++++++++++++ |
| 595 |
|
| 596 |
For more information, see `Registry Key Security and Access |
| 597 |
<https://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`__. |
| 598 |
|
| 599 |
.. data:: KEY_ALL_ACCESS |
| 600 |
|
| 601 |
Combines the STANDARD_RIGHTS_REQUIRED, :const:`KEY_QUERY_VALUE`, |
| 602 |
:const:`KEY_SET_VALUE`, :const:`KEY_CREATE_SUB_KEY`, |
| 603 |
:const:`KEY_ENUMERATE_SUB_KEYS`, :const:`KEY_NOTIFY`, |
| 604 |
and :const:`KEY_CREATE_LINK` access rights. |
| 605 |
|
| 606 |
.. data:: KEY_WRITE |
| 607 |
|
| 608 |
Combines the STANDARD_RIGHTS_WRITE, :const:`KEY_SET_VALUE`, and |
| 609 |
:const:`KEY_CREATE_SUB_KEY` access rights. |
| 610 |
|
| 611 |
.. data:: KEY_READ |
| 612 |
|
| 613 |
Combines the STANDARD_RIGHTS_READ, :const:`KEY_QUERY_VALUE`, |
| 614 |
:const:`KEY_ENUMERATE_SUB_KEYS`, and :const:`KEY_NOTIFY` values. |
| 615 |
|
| 616 |
.. data:: KEY_EXECUTE |
| 617 |
|
| 618 |
Equivalent to :const:`KEY_READ`. |
| 619 |
|
| 620 |
.. data:: KEY_QUERY_VALUE |
| 621 |
|
| 622 |
Required to query the values of a registry key. |
| 623 |
|
| 624 |
.. data:: KEY_SET_VALUE |
| 625 |
|
| 626 |
Required to create, delete, or set a registry value. |
| 627 |
|
| 628 |
.. data:: KEY_CREATE_SUB_KEY |
| 629 |
|
| 630 |
Required to create a subkey of a registry key. |
| 631 |
|
| 632 |
.. data:: KEY_ENUMERATE_SUB_KEYS |
| 633 |
|
| 634 |
Required to enumerate the subkeys of a registry key. |
| 635 |
|
| 636 |
.. data:: KEY_NOTIFY |
| 637 |
|
| 638 |
Required to request change notifications for a registry key or for |
| 639 |
subkeys of a registry key. |
| 640 |
|
| 641 |
.. data:: KEY_CREATE_LINK |
| 642 |
|
| 643 |
Reserved for system use. |
| 644 |
|
| 645 |
|
| 646 |
.. _64-bit-access-rights: |
| 647 |
|
| 648 |
64-bit Specific |
| 649 |
*************** |
| 650 |
|
| 651 |
For more information, see `Accessing an Alternate Registry View |
| 652 |
<https://msdn.microsoft.com/en-us/library/aa384129(v=VS.85).aspx>`__. |
| 653 |
|
| 654 |
.. data:: KEY_WOW64_64KEY |
| 655 |
|
| 656 |
Indicates that an application on 64-bit Windows should operate on |
| 657 |
the 64-bit registry view. On 32-bit Windows, this constant is ignored. |
| 658 |
|
| 659 |
.. data:: KEY_WOW64_32KEY |
| 660 |
|
| 661 |
Indicates that an application on 64-bit Windows should operate on |
| 662 |
the 32-bit registry view. On 32-bit Windows, this constant is ignored. |
| 663 |
|
| 664 |
.. _value-types: |
| 665 |
|
| 666 |
Value Types |
| 667 |
+++++++++++ |
| 668 |
|
| 669 |
For more information, see `Registry Value Types |
| 670 |
<https://msdn.microsoft.com/en-us/library/ms724884%28v=VS.85%29.aspx>`__. |
| 671 |
|
| 672 |
.. data:: REG_BINARY |
| 673 |
|
| 674 |
Binary data in any form. |
| 675 |
|
| 676 |
.. data:: REG_DWORD |
| 677 |
|
| 678 |
32-bit number. |
| 679 |
|
| 680 |
.. data:: REG_DWORD_LITTLE_ENDIAN |
| 681 |
|
| 682 |
A 32-bit number in little-endian format. Equivalent to :const:`REG_DWORD`. |
| 683 |
|
| 684 |
.. data:: REG_DWORD_BIG_ENDIAN |
| 685 |
|
| 686 |
A 32-bit number in big-endian format. |
| 687 |
|
| 688 |
.. data:: REG_EXPAND_SZ |
| 689 |
|
| 690 |
Null-terminated string containing references to environment |
| 691 |
variables (``%PATH%``). |
| 692 |
|
| 693 |
.. data:: REG_LINK |
| 694 |
|
| 695 |
A Unicode symbolic link. |
| 696 |
|
| 697 |
.. data:: REG_MULTI_SZ |
| 698 |
|
| 699 |
A sequence of null-terminated strings, terminated by two null characters. |
| 700 |
(Python handles this termination automatically.) |
| 701 |
|
| 702 |
.. data:: REG_NONE |
| 703 |
|
| 704 |
No defined value type. |
| 705 |
|
| 706 |
.. data:: REG_QWORD |
| 707 |
|
| 708 |
A 64-bit number. |
| 709 |
|
| 710 |
.. versionadded:: 3.6 |
| 711 |
|
| 712 |
.. data:: REG_QWORD_LITTLE_ENDIAN |
| 713 |
|
| 714 |
A 64-bit number in little-endian format. Equivalent to :const:`REG_QWORD`. |
| 715 |
|
| 716 |
.. versionadded:: 3.6 |
| 717 |
|
| 718 |
.. data:: REG_RESOURCE_LIST |
| 719 |
|
| 720 |
A device-driver resource list. |
| 721 |
|
| 722 |
.. data:: REG_FULL_RESOURCE_DESCRIPTOR |
| 723 |
|
| 724 |
A hardware setting. |
| 725 |
|
| 726 |
.. data:: REG_RESOURCE_REQUIREMENTS_LIST |
| 727 |
|
| 728 |
A hardware resource list. |
| 729 |
|
| 730 |
.. data:: REG_SZ |
| 731 |
|
| 732 |
A null-terminated string. |
| 733 |
|
| 734 |
|
| 735 |
.. _handle-object: |
| 736 |
|
| 737 |
Registry Handle Objects |
| 738 |
----------------------- |
| 739 |
|
| 740 |
This object wraps a Windows HKEY object, automatically closing it when the |
| 741 |
object is destroyed. To guarantee cleanup, you can call either the |
| 742 |
:meth:`~PyHKEY.Close` method on the object, or the :func:`CloseKey` function. |
| 743 |
|
| 744 |
All registry functions in this module return one of these objects. |
| 745 |
|
| 746 |
All registry functions in this module which accept a handle object also accept |
| 747 |
an integer, however, use of the handle object is encouraged. |
| 748 |
|
| 749 |
Handle objects provide semantics for :meth:`~object.__bool__` -- thus :: |
| 750 |
|
| 751 |
if handle: |
| 752 |
print("Yes") |
| 753 |
|
| 754 |
will print ``Yes`` if the handle is currently valid (has not been closed or |
| 755 |
detached). |
| 756 |
|
| 757 |
Handle objects can be converted to an integer (e.g., using the built-in |
| 758 |
:func:`int` function), in which case the underlying Windows handle value is |
| 759 |
returned. You can also use the :meth:`~PyHKEY.Detach` method to return the |
| 760 |
integer handle, and also disconnect the Windows handle from the handle object. |
| 761 |
|
| 762 |
|
| 763 |
.. method:: PyHKEY.Close() |
| 764 |
|
| 765 |
Closes the underlying Windows handle. |
| 766 |
|
| 767 |
If the handle is already closed, no error is raised. |
| 768 |
|
| 769 |
|
| 770 |
.. method:: PyHKEY.Detach() |
| 771 |
|
| 772 |
Detaches the Windows handle from the handle object. |
| 773 |
|
| 774 |
The result is an integer that holds the value of the handle before it is |
| 775 |
detached. If the handle is already detached or closed, this will return |
| 776 |
zero. |
| 777 |
|
| 778 |
After calling this function, the handle is effectively invalidated, but the |
| 779 |
handle is not closed. You would call this function when you need the |
| 780 |
underlying Win32 handle to exist beyond the lifetime of the handle object. |
| 781 |
|
| 782 |
.. audit-event:: winreg.PyHKEY.Detach key winreg.PyHKEY.Detach |
| 783 |
|
| 784 |
|
| 785 |
.. method:: PyHKEY.__enter__() |
| 786 |
PyHKEY.__exit__(*exc_info) |
| 787 |
|
| 788 |
The HKEY object implements :meth:`~object.__enter__` and |
| 789 |
:meth:`~object.__exit__` and thus supports the context protocol for the |
| 790 |
:keyword:`with` statement:: |
| 791 |
|
| 792 |
with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key: |
| 793 |
... # work with key |
| 794 |
|
| 795 |
will automatically close *key* when control leaves the :keyword:`with` block. |
| 796 |
|
| 797 |
|