winreg — Windows registry access

---

Ці функції надають Python API реєстру 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.

Нове в версії 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)

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

Примітка

The DeleteKeyEx() function is implemented with the RegDeleteKeyEx Windows API function, which is specific to 64-bit versions of Windows. See the RegDeleteKeyEx documentation.

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. See Access Rights for other allowed values.

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

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

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

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

Нове в версії 3.2.

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

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.

winreg.KEY_WOW64_32KEY

Indicates that an application on 64-bit Windows should operate on the 32-bit registry view.

Типи значень

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

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-розрядне число.

Нове в версії 3.6.

winreg.REG_QWORD_LITTLE_ENDIAN

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

Нове в версії 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")

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

Об’єкт також підтримує семантику порівняння, тому об’єкти-дескриптори порівнюватимуться як істинні, якщо вони обидва посилаються на одне базове значення маркера Windows.

Об’єкти дескриптора можна перетворити на ціле число (наприклад, за допомогою вбудованої функції 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.