# `winreg` — Windows registry access

Source code: PC/winreg.c

Ці функції надають Python API реєстру Windows. Замість використання цілого числа як дескриптора реєстру об’єкт дескриптора використовується для забезпечення правильного закриття дескрипторів, навіть якщо програміст нехтує їх явним закриттям.

Availability: Windows.

Змінено в версії 3.3: Кілька функцій у цьому модулі викликали помилку `WindowsError`, яка тепер є псевдонімом `OSError`.

## Функції

Цей модуль пропонує такі функції:

winreg.CloseKey(hkey)

  Закриває раніше відкритий розділ реєстру. Аргумент hkey визначає раніше відкритий ключ.

  Примітка

  Якщо hkey не закривається за допомогою цього методу (або через `hkey.Close()`), він закривається, коли об’єкт hkey знищується Python.

winreg.ConnectRegistry(computer_name, key)

  Встановлює підключення до попередньо визначеного дескриптора реєстру на іншому комп’ютері та повертає об’єкт дескриптора.

  ім’я_комп’ютера — це ім’я віддаленого комп’ютера у формі `r"\\ім’я комп’ютера`. Якщо `None`, використовується локальний комп’ютер.

  key — це попередньо визначений маркер для підключення.

  Поверненим значенням є дескриптор відкритого ключа. Якщо функція не виконується, виникає виняток `OSError`.

  Викликає подію аудиту `winreg.ConnectRegistry` з аргументами `computer_name`, `key`.

  Змінено в версії 3.3: Дивіться вище.

winreg.CreateKey(key, sub_key)

  Створює або відкриває вказаний ключ, повертаючи об’єкт дескриптора.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  sub_key — це рядок, який називає ключ, який відкриває або створює цей метод.

  Якщо key є одним із попередньо визначених ключів, sub_key може мати значення `None`. У цьому випадку повернутий дескриптор є тим самим дескриптором ключа, переданим у функцію.

  Якщо ключ уже існує, ця функція відкриває наявний ключ.

  Поверненим значенням є дескриптор відкритого ключа. Якщо функція не виконується, виникає виняток `OSError`.

  Викликає подію аудиту `winreg.CreateKey` з аргументами `key`, `sub_key`, `access`.

  Викликає подію аудиту `winreg.OpenKey/result` з аргументом `key`.

  Змінено в версії 3.3: Дивіться вище.

winreg.CreateKeyEx(key, sub_key, reserved=0, access=KEY_WRITE)

  Створює або відкриває вказаний ключ, повертаючи об’єкт дескриптора.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  sub_key — це рядок, який називає ключ, який відкриває або створює цей метод.

  reserved є зарезервованим цілим числом і має дорівнювати нулю. За умовчанням дорівнює нулю.

  access — це ціле число, що вказує маску доступу, яка описує бажаний доступ безпеки для ключа. Типовим є `KEY_WRITE`. Перегляньте Права доступу для інших дозволених значень.

  Якщо key є одним із попередньо визначених ключів, sub_key може мати значення `None`. У цьому випадку повернутий дескриптор є тим самим дескриптором ключа, переданим у функцію.

  Якщо ключ уже існує, ця функція відкриває наявний ключ.

  Поверненим значенням є дескриптор відкритого ключа. Якщо функція не виконується, виникає виняток `OSError`.

  Викликає подію аудиту `winreg.CreateKey` з аргументами `key`, `sub_key`, `access`.

  Викликає подію аудиту `winreg.OpenKey/result` з аргументом `key`.

  Added in version 3.2.

  Змінено в версії 3.3: Дивіться вище.

winreg.DeleteKey(key, sub_key)

  Видаляє вказаний ключ.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  sub_key – це рядок, який має бути підключем ключа, визначеного параметром key. Це значення не має бути `None`, і ключ не може мати підключів.

  Цей метод не може видалити ключі з підключами.

  Якщо метод завершується успішно, весь ключ, включаючи всі його значення, видаляється. Якщо метод не вдається, виникає виняток `OSError`.

  Викликає подію аудиту `winreg.DeleteKey` з аргументами `key`, `sub_key`, `access`.

  Змінено в версії 3.3: Дивіться вище.

winreg.DeleteKeyEx(key, sub_key, access=KEY_WOW64_64KEY, reserved=0)

  Видаляє вказаний ключ.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  sub_key – це рядок, який має бути підключем ключа, визначеного параметром key. Це значення не має бути `None`, і ключ не може мати підключів.

  reserved є зарезервованим цілим числом і має дорівнювати нулю. За умовчанням дорівнює нулю.

  access is an integer that specifies an access mask that describes the desired security access for the key. Default is `KEY_WOW64_64KEY`. On 32-bit Windows, the WOW64 constants are ignored. See Access Rights for other allowed values.

  Цей метод не може видалити ключі з підключами.

  Якщо метод завершується успішно, весь ключ, включаючи всі його значення, видаляється. Якщо метод не вдається, виникає виняток `OSError`.

  У непідтримуваних версіях Windows виникає `NotImplementedError`.

  Викликає подію аудиту `winreg.DeleteKey` з аргументами `key`, `sub_key`, `access`.

  Added in version 3.2.

  Змінено в версії 3.3: Дивіться вище.

winreg.DeleteTree(key, sub_key=None)

  Deletes the specified key and all its subkeys and values recursively.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  sub_key is a string that names the subkey to delete. If `None`, deletes all subkeys and values of the specified key.

  This function deletes a key and all its descendants. If sub_key is `None`, all subkeys and values of the specified key are deleted.

  Raises an auditing event `winreg.DeleteTree` with arguments `key`, `sub_key`.

  Added in version 3.15.

winreg.DeleteValue(key, value)

  Видаляє назване значення з розділу реєстру.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  value — це рядок, який визначає значення, яке потрібно видалити.

  Викликає подію аудиту `winreg.DeleteValue` з аргументами `key`, `value`.

winreg.EnumKey(key, index)

  Перераховує підрозділи відкритого ключа реєстру, повертаючи рядок.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  index — це ціле число, яке визначає індекс ключа, який потрібно отримати.

  Функція отримує ім’я одного підключа під час кожного виклику. Зазвичай він викликається неодноразово, доки не виникне виняток `OSError`, що вказує на відсутність більше доступних значень.

  Викликає подію аудиту `winreg.EnumKey` з аргументами `key`, `index`.

  Змінено в версії 3.3: Дивіться вище.

winreg.EnumValue(key, index)

  Перераховує значення відкритого ключа реєстру, повертаючи кортеж.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  index — це ціле число, яке визначає індекс значення, яке потрібно отримати.

  Функція отримує ім’я одного підключа під час кожного виклику. Зазвичай він викликається неодноразово, доки не буде викликано виняток `OSError`, що вказує на відсутність більше значень.

  Результатом є кортеж із 3 елементів:

  Індекс | Значення
  --- | ---
  `0` | Рядок, який ідентифікує назву значення
  `1` | Об’єкт, який містить дані значення, тип якого залежить від базового типу реєстру
  `2` | Ціле число, яке визначає тип даних значення (див. таблицю в документах для `SetValueEx()`)

  Викликає подію аудиту `winreg.EnumValue` з аргументами `key`, `index`.

  Змінено в версії 3.3: Дивіться вище.

winreg.ExpandEnvironmentStrings(str)

  Розгортає заповнювачі змінної середовища `%NAME%` у рядках на зразок `REG_EXPAND_SZ`:

      >>> ExpandEnvironmentStrings('%windir%')
      'C:\\Windows'

  Викликає подію аудиту `winreg.ExpandEnvironmentStrings` з аргументом `str`.

winreg.FlushKey(key)

  Записує всі атрибути ключа до реєстру.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  Щоб змінити ключ, не потрібно викликати `FlushKey()`. Зміни реєстру скидаються на диск реєстром за допомогою відкладеного очищувача. Зміни реєстру також скидаються на диск під час завершення роботи системи. На відміну від `CloseKey()`, метод `FlushKey()` повертається лише тоді, коли всі дані були записані до реєстру. Програма має викликати `FlushKey()`, лише якщо вона вимагає абсолютної впевненості, що зміни реєстру є на диску.

  Примітка

  Якщо ви не знаєте, чи потрібен виклик `FlushKey()`, можливо, ні.

winreg.LoadKey(key, sub_key, file_name)

  Створює підрозділ у вказаному розділі та зберігає реєстраційну інформацію з указаного файлу в цьому підрозділі.

  key — це дескриптор, який повертає `ConnectRegistry()` або одна з констант `HKEY_USERS` або `HKEY_LOCAL_MACHINE`.

  sub_key — це рядок, який визначає підключ для завантаження.

  ім’я_файлу — це ім’я файлу, з якого потрібно завантажити дані реєстру. Цей файл має бути створено за допомогою функції `SaveKey()`. У файловій системі таблиці розподілу файлів (FAT) назва файлу може не мати розширення.

  A call to `LoadKey()` fails if the calling process does not have the `SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different from permissions – see the RegLoadKey documentation for more details.

  Якщо key — це дескриптор, повернутий `ConnectRegistry()`, тоді шлях, указаний у file_name, є відносно віддаленого комп’ютера.

  Викликає подію аудиту `winreg.LoadKey` з аргументами `key`, `sub_key`, `file_name`.

winreg.OpenKey(key, sub_key, reserved=0, access=KEY_READ)
winreg.OpenKeyEx(key, sub_key, reserved=0, access=KEY_READ)

  Відкриває вказаний ключ, повертаючи об’єкт дескриптора.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  sub_key — це рядок, який визначає sub_key, який потрібно відкрити.

  reserved є зарезервованим цілим числом і має дорівнювати нулю. За умовчанням дорівнює нулю.

  access — це ціле число, що вказує маску доступу, яка описує бажаний доступ безпеки для ключа. Типовим є `KEY_READ`. Перегляньте Права доступу для інших дозволених значень.

  Результатом є новий дескриптор зазначеного ключа.

  Якщо функція не виконується, виникає `OSError`.

  Викликає подію аудиту `winreg.OpenKey` з аргументами `key`, `sub_key`, `access`.

  Викликає подію аудиту `winreg.OpenKey/result` з аргументом `key`.

  Змінено в версії 3.2: Дозволити використання іменованих аргументів.

  Змінено в версії 3.3: Дивіться вище.

winreg.QueryInfoKey(key)

  Повертає інформацію про ключ у вигляді кортежу.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  Результатом є кортеж із 3 елементів:

  Індекс | Значення
  --- | ---
  `0` | Ціле число, що вказує кількість підключів, які має цей ключ.
  `1` | Ціле число, що вказує кількість значень, які має цей ключ.
  `2` | Ціле число, яке вказує дату останньої зміни ключа (якщо доступно) як 100 наносекунд з 1 січня 1601 року.

  Викликає подію аудиту `winreg.QueryInfoKey` з аргументом `key`.

winreg.QueryValue(key, sub_key)

  Отримує безіменне значення для ключа у вигляді рядка.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  sub_key — це рядок, який містить назву підрозділу, з яким пов’язане значення. Якщо цей параметр `None` або порожній, функція отримує значення, встановлене методом `SetValue()` для ключа, визначеного key.

  Значення в реєстрі мають назву, тип і компоненти даних. Цей метод отримує дані для першого значення ключа, яке має назву `NULL`. Але основний виклик API не повертає тип, тому завжди використовуйте `QueryValueEx()`, якщо це можливо.

  Викликає подію аудиту `winreg.QueryValue` з аргументами `key`, `sub_key`, `value_name`.

winreg.QueryValueEx(key, value_name)

  Отримує тип і дані для вказаного імені значення, пов’язаного з відкритим розділом реєстру.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  value_name — це рядок, що вказує на значення для запиту.

  Результатом є кортеж із 2 елементів:

  Індекс | Значення
  --- | ---
  `0` | Значення елемента реєстру.
  `1` | Ціле число, що вказує тип реєстру для цього значення (див. таблицю в документах для `SetValueEx()`)

  Викликає подію аудиту `winreg.QueryValue` з аргументами `key`, `sub_key`, `value_name`.

winreg.SaveKey(key, file_name)

  Зберігає вказаний ключ і всі його підключі у вказаний файл.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  ім’я_файлу — це ім’я файлу, у який потрібно зберегти дані реєстру. Цей файл уже не може існувати. Якщо це ім’я файлу містить розширення, його не можна використовувати у файлових системах таблиці розподілу файлів (FAT) методом `LoadKey()`.

  If key represents a key on a remote computer, the path described by file_name is relative to the remote computer. The caller of this method must possess the SeBackupPrivilege security privilege. Note that privileges are different than permissions – see the Conflicts Between User Rights and Permissions documentation for more details.

  Ця функція передає `NULL` для security_attributes в API.

  Викликає подію аудиту `winreg.SaveKey` з аргументами `key`, `file_name`.

winreg.SetValue(key, sub_key, type, value)

  Пов’язує значення з указаним ключем.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  sub_key — це рядок, що називає підрозділ, з яким пов’язане значення.

  type — це ціле число, яке визначає тип даних. Наразі це має бути `REG_SZ`, тобто підтримуються лише рядки. Використовуйте функцію `SetValueEx()` для підтримки інших типів даних.

  value — це рядок, який визначає нове значення.

  Якщо ключ, визначений параметром sub_key, не існує, функція SetValue створює його.

  Довжина значень обмежена доступною пам’яттю. Довгі значення (понад 2048 байт) слід зберігати як файли з іменами файлів, які зберігаються в реєстрі конфігурації. Це сприяє ефективній роботі реєстру.

  Ключ, визначений параметром key, має бути відкритий із доступом `KEY_SET_VALUE`.

  Викликає подію аудиту `winreg.SetValue` з аргументами `key`, `sub_key`, `type`, `value`.

winreg.SetValueEx(key, value_name, reserved, type, value)

  Зберігає дані в полі значення відкритого ключа реєстру.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  value_name — це рядок, що називає підрозділ, з яким пов’язане значення.

  reserved може бути будь-яким - нуль завжди передається в API.

  type — це ціле число, яке визначає тип даних. Перегляньте Типи значень для доступних типів.

  value — це рядок, який визначає нове значення.

  Цей метод також може встановити додаткове значення та інформацію про тип для вказаного ключа. Ключ, визначений параметром ключа, має бути відкрито з доступом `KEY_SET_VALUE`.

  Щоб відкрити ключ, використовуйте методи `CreateKey()` або `OpenKey()`.

  Довжина значень обмежена доступною пам’яттю. Довгі значення (понад 2048 байт) слід зберігати як файли з іменами файлів, які зберігаються в реєстрі конфігурації. Це сприяє ефективній роботі реєстру.

  Викликає подію аудиту `winreg.SetValue` з аргументами `key`, `sub_key`, `type`, `value`.

winreg.DisableReflectionKey(key)

  Вимикає відображення реєстру для 32-розрядних процесів, запущених у 64-розрядній операційній системі.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  Зазвичай викликає помилку `NotImplementedError`, якщо її виконувати в 32-розрядній операційній системі.

  Якщо ключ відсутній у списку відображення, функція виконується успішно, але не має ефекту. Вимкнення відображення для ключа не впливає на відображення будь-яких підключів.

  Викликає подію аудиту `winreg.DisableReflectionKey` з аргументом `key`.

winreg.EnableReflectionKey(key)

  Відновлює відображення реєстру для вказаного вимкненого ключа.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  Зазвичай викликає помилку `NotImplementedError`, якщо її виконувати в 32-розрядній операційній системі.

  Відновлення відображення для ключа не впливає на відображення будь-яких підключів.

  Викликає подію аудиту `winreg.EnableReflectionKey` з аргументом `key`.

winreg.QueryReflectionKey(key)

  Визначає стан відображення для вказаного ключа.

  key — це вже відкритий ключ або одна з попередньо визначених HKEY_* констант.

  Повертає `True`, якщо відображення вимкнено.

  Зазвичай викликає помилку `NotImplementedError`, якщо її виконувати в 32-розрядній операційній системі.

  Викликає подію аудиту `winreg.QueryReflectionKey` з аргументом `key`.

## Константи

The following constants are defined for use in many `winreg` functions.

### HKEY_* Константи

winreg.HKEY_CLASSES_ROOT

  Записи реєстру, підпорядковані цьому ключу, визначають типи (або класи) документів і властивості, пов’язані з цими типами. Додатки Shell і COM використовують інформацію, що зберігається під цим ключем.

winreg.HKEY_CURRENT_USER

  Записи реєстру, підпорядковані цьому ключу, визначають уподобання поточного користувача. Ці параметри включають параметри змінних середовища, дані про групи програм, кольори, принтери, мережеві підключення та параметри програми.

winreg.HKEY_LOCAL_MACHINE

  Записи реєстру, підпорядковані цьому ключу, визначають фізичний стан комп’ютера, включаючи дані про тип шини, системну пам’ять, а також встановлене обладнання та програмне забезпечення.

winreg.HKEY_USERS

  Записи реєстру, підпорядковані цьому розділу, визначають конфігурацію користувача за замовчуванням для нових користувачів на локальному комп’ютері та конфігурацію користувача для поточного користувача.

winreg.HKEY_PERFORMANCE_DATA

  Записи реєстру, підпорядковані цьому ключу, дозволяють отримати доступ до даних продуктивності. Дані фактично не зберігаються в реєстрі; функції реєстру змушують систему збирати дані з джерела.

winreg.HKEY_CURRENT_CONFIG

  Містить інформацію про поточний профіль апаратного забезпечення локальної комп’ютерної системи.

winreg.HKEY_DYN_DATA

  Цей ключ не використовується у версіях Windows після 98.

### Права доступу

Щоб отримати додаткові відомості, перегляньте Безпека ключа реєстру та доступ.

winreg.KEY_ALL_ACCESS

  Поєднує права доступу STANDARD_RIGHTS_REQUIRED, `KEY_QUERY_VALUE`, `KEY_SET_VALUE`, `KEY_CREATE_SUB_KEY`, `KEY_ENUMERATE_SUB_KEYS`, `KEY_NOTIFY` і `KEY_CREATE_LINK`.

winreg.KEY_WRITE

  Поєднує права доступу STANDARD_RIGHTS_WRITE, `KEY_SET_VALUE` і `KEY_CREATE_SUB_KEY`.

winreg.KEY_READ

  Поєднує значення STANDARD_RIGHTS_READ, `KEY_QUERY_VALUE`, `KEY_ENUMERATE_SUB_KEYS` і `KEY_NOTIFY`.

winreg.KEY_EXECUTE

  Еквівалент `KEY_READ`.

winreg.KEY_QUERY_VALUE

  Необхідний для запиту значень розділу реєстру.

winreg.KEY_SET_VALUE

  Необхідний для створення, видалення або встановлення значення реєстру.

winreg.KEY_CREATE_SUB_KEY

  Необхідний для створення підрозділу розділу реєстру.

winreg.KEY_ENUMERATE_SUB_KEYS

  Необхідний для перерахування підрозділів розділу реєстру.

winreg.KEY_NOTIFY

  Необхідний для запиту сповіщень про зміни для розділу реєстру або для підрозділів розділу реєстру.

winreg.KEY_CREATE_LINK

  Зарезервовано для системного використання.

#### Спеціально для 64-біт

Для отримання додаткової інформації див. Доступ до альтернативного подання реєстру.

winreg.KEY_WOW64_64KEY

  Indicates that an application on 64-bit Windows should operate on the 64-bit registry view. On 32-bit Windows, this constant is ignored.

winreg.KEY_WOW64_32KEY

  Indicates that an application on 64-bit Windows should operate on the 32-bit registry view. On 32-bit Windows, this constant is ignored.

### Типи значень

Щоб отримати додаткові відомості, перегляньте Типи значень реєстру.

winreg.REG_BINARY

  Двійкові дані в довільній формі.

winreg.REG_DWORD

  32-розрядне число.

winreg.REG_DWORD_LITTLE_ENDIAN

  32-розрядне число у форматі little-endian. Еквівалент `REG_DWORD`.

winreg.REG_DWORD_BIG_ENDIAN

  32-розрядне число у форматі старшого порядку.

winreg.REG_EXPAND_SZ

  Рядок із нульовим завершенням, що містить посилання на змінні середовища (`%PATH%`).

winreg.REG_LINK

  Символьне посилання Unicode.

winreg.REG_MULTI_SZ

  Послідовність рядків із закінченням нулем, що завершується двома символами нуль. (Python обробляє це завершення автоматично.)

winreg.REG_NONE

  Немає визначеного типу значення.

winreg.REG_QWORD

  64-розрядне число.

  Added in version 3.6.

winreg.REG_QWORD_LITTLE_ENDIAN

  64-розрядне число у форматі little-endian. Еквівалент `REG_QWORD`.

  Added in version 3.6.

winreg.REG_RESOURCE_LIST

  Список ресурсів драйверів пристроїв.

winreg.REG_FULL_RESOURCE_DESCRIPTOR

  Налаштування обладнання.

winreg.REG_RESOURCE_REQUIREMENTS_LIST

  Список апаратних ресурсів.

winreg.REG_SZ

  Рядок із закінченням нулем.

## Об’єкти обробки реєстру

Цей об’єкт огортає об’єкт HKEY Windows, автоматично закриваючи його, коли об’єкт знищується. Щоб гарантувати очищення, ви можете викликати або метод `Close()` для об’єкта, або функцію `CloseKey()`.

Усі функції реєстру в цьому модулі повертають один із цих об’єктів.

Усі функції реєстру в цьому модулі, які приймають об’єкт-дескриптор, також приймають ціле число, проте використання об’єкта-дескриптора заохочується.

Handle objects provide semantics for `__bool__()` – thus

    if handle:
        print("Yes")

надрукує `Так`, якщо дескриптор наразі дійсний (не був закритий або від’єднаний).

The object also support equality comparison semantics, so handle objects will compare equal if they both reference the same underlying Windows handle value. Closed handle objects (those with a handle value of zero) always compare equal.

Об’єкти дескриптора можна перетворити на ціле число (наприклад, за допомогою вбудованої функції `int()`), у цьому випадку повертається базове значення дескриптора Windows. Ви також можете використати метод `Detach()`, щоб повернути цілочисельний дескриптор, а також від’єднати дескриптор Windows від об’єкта дескриптора.

PyHKEY.Close()

  Закриває основний маркер Windows.

  Якщо ручка вже закрита, помилка не виникає.

PyHKEY.Detach()

  Від’єднує маркер Windows від об’єкта маркера.

  Результатом є ціле число, яке містить значення дескриптора до його від’єднання. Якщо ручка вже від’єднана або закрита, це поверне нуль.

  Після виклику цієї функції дескриптор фактично стає недійсним, але дескриптор не закривається. Ви можете викликати цю функцію, якщо вам потрібно, щоб основний дескриптор Win32 існував після закінчення терміну служби об’єкта дескриптора.

  Викликає подію аудиту `winreg.PyHKEY.Detach` з аргументом `key`.

PyHKEY.__enter__()
PyHKEY.__exit__(*exc_info)

  Об’єкт HKEY реалізує `__enter__()` і `__exit__()` і таким чином підтримує контекстний протокол для оператора `with`:

      with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
          ...  # work with key

  автоматично закриє key, коли керування залишить блок `with`.

Змінено в версії 3.15: Handle objects are now compared by their underlying Windows handle value instead of object identity for equality comparisons.