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)

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

Примечание

Функция DeleteKeyEx() реализована с помощью функции Windows API RegDeleteKeyEx, которая специфична для 64-битных версий Windows. См. документацию RegDeleteKeyEx.

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

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

reserved — зарезервированное целое число и должно быть равно нулю. По умолчанию равно нулю.

access — целое число, определяющее маску доступа, описывающую требуемый уровень безопасности для ключа. По умолчанию KEY_WOW64_64KEY. Смотрите Права доступа для других разрешённых значений.

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

Если метод завершается успешно, весь ключ, включая все его значения, удаляется. Если метод завершается ошибкой, генерируется исключение 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 уровень доступа. Обратите внимание, что права доступа отличаются от разрешений — см. документацию Conflicts Between User Rights and Permissions для получения дополнительных сведений.

Эта функция передает 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, должен быть открыт с доступом 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.

Константы

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

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

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

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

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

Объекты дескрипторов обеспечивают семантику __bool__() – таким образом

if handle:
    print("Yes")

будет выводить 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.