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 (File Allocation Table) методом LoadKey().

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

Эта функция передаёт 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.