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