winreg — доступ к реестру Windows

Функции

Этот модуль предоставляет следующие функции:

winreg.CloseKey(hkey)

Закрывает ранее открытый ключ реестра. Аргумент hkey указывает на ранее открытый ключ.

Примечание

Если hkey не закрыт с помощью этого метода (или через hkey.Close()), он будет закрыт, когда объект hkey будет уничтожен Python.

winreg.ConnectRegistry(computer_name, key)

Устанавливает соединение с предопределённым дескриптором реестра на другом компьютере и возвращает объект дескриптора.

computer_name — имя удалённого компьютера в формате r"\\computername". Если 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)

Удаляет указанный ключ.

key — уже открытый ключ или одна из предопределённых констант HKEY_*.

sub_key — строка, которая должна обозначать подраздел ключа, указанного параметром key. Это значение не должно быть None, а у ключа не должно быть подразделов.

reserved — зарезервированное целое число, равное нулю. Значение по умолчанию — ноль.

access — целое число, указывающее маску доступа, которая задаёт требуемый уровень безопасности для ключа. По умолчанию используется KEY_WOW64_64KEY. В 32-разрядной Windows константы WOW64 игнорируются. Другие допустимые значения см. в разделе Права доступа.

Этот метод не может удалять ключи, содержащие подразделы.

При успешном выполнении метода удаляется весь ключ, включая все его значения. Если метод завершается с ошибкой, возбуждается исключение 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 — строка, указывающая загружаемый подраздел.

file_name — имя файла, из которого загружаются данные реестра. Этот файл должен быть создан функцией SaveKey(). В файловой системе с таблицей размещения файлов (FAT) имя файла не может иметь расширение.

Вызов LoadKey() завершается с ошибкой, если у вызывающего процесса нет привилегии SE_RESTORE_PRIVILEGE. Обратите внимание, что привилегии отличаются от разрешений. Подробнее см. документацию RegLoadKey.

Если 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 — строка, указывающая открываемый подраздел.

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	Целое число, указывающее время последнего изменения ключа (если доступно) в сотнях наносекунд с 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_*.

file_name — имя файла, в который нужно сохранить данные реестра. Этот файл не должен уже существовать. Если имя файла содержит расширение, его нельзя использовать в файловых системах с таблицей размещения файлов (FAT) методом LoadKey().

Если key представляет ключ на удалённом компьютере, путь, указанный в file_name, задаётся относительно удалённого компьютера. Вызывающий этот метод должен обладать привилегией безопасности SeBackupPrivilege. Обратите внимание, что привилегии отличаются от разрешений. Подробнее см. документацию о конфликтах между правами пользователя и разрешениями.

Эта функция передаёт NULL API в качестве значения security_attributes.

Вызывает событие аудита 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, должен быть открыт с правом доступа KEY_SET_VALUE.

Чтобы открыть ключ, используйте методы CreateKey() или OpenKey().

Длина значений ограничена доступной памятью. Длинные значения (более 2048 байт) следует хранить в файлах, а имена файлов — в реестре конфигурации. Это помогает реестру работать эффективнее.

Вызывает событие аудита winreg.SetValue с аргументами key, sub_key, type, value.

winreg.DisableReflectionKey(key)

Отключает отражение реестра для 32-разрядных процессов, работающих в 64-разрядной операционной системе.

key — уже открытый ключ или одна из предопределённых констант HKEY_*.

При выполнении в 32-разрядной операционной системе обычно возбуждается исключение NotImplementedError.

Если ключ отсутствует в списке отражения, функция завершается успешно, но ничего не делает. Отключение отражения для ключа не влияет на отражение его подразделов.

Вызывает событие аудита winreg.DisableReflectionKey с аргументом key.

winreg.EnableReflectionKey(key)

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

key — уже открытый ключ или одна из предопределённых констант HKEY_*.

При выполнении в 32-разрядной операционной системе обычно возбуждается исключение NotImplementedError.

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

Вызывает событие аудита winreg.EnableReflectionKey с аргументом key.

winreg.QueryReflectionKey(key)

Определяет состояние отражения указанного ключа.

key — уже открытый ключ или одна из предопределённых констант HKEY_*.

Возвращает True, если отражение отключено.

При выполнении в 32-разрядной операционной системе обычно возбуждается исключение NotImplementedError.

Вызывает событие аудита winreg.QueryReflectionKey с аргументом key.

Константы

Следующие константы определены для использования во многих функциях winreg.

Объекты-дескрипторы реестра

Этот объект оборачивает объект Windows HKEY и автоматически закрывает его при уничтожении объекта. Чтобы гарантировать очистку, можно вызвать метод Close() объекта или функцию CloseKey().

Все функции реестра в этом модуле возвращают один из таких объектов.

Все функции реестра в этом модуле, принимающие объект-дескриптор, также принимают целое число, однако рекомендуется использовать объект-дескриптор.

Объекты-дескрипторы предоставляют семантику для __bool__() – поэтому

if handle:
    print("Yes")

выведет Yes, если дескриптор действителен на данный момент (не закрыт и не отсоединён).

Объекты-дескрипторы можно преобразовать в целое число (например, с помощью встроенной функции 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.