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

Функции

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

winreg.CloseKey(hkey)

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

Примечание

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

winreg.ConnectRegistry(computer_name, key)

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

computer_name — имя удалённого компьютера, имеющее формат r"\\computername". Если None, используется локальный компьютер.

key — предопределённый дескриптор для подключения.

Возвращаемое значение — дескриптор открытого ключа. При неудачном выполнении функции возникает исключение OSError.

Возбуждает событие аудита auditing event winreg.ConnectRegistry с аргументами computer_name, key.

Изменено в версии 3.3: См. выше.

winreg.CreateKey(key, sub_key)

Создаёт или открывает указанный ключ, возвращая объект-дескриптор.

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

sub_key — строка, определяющая имя ключа, открываемого или создаваемого этим методом.

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

Если ключ уже существует, функция открывает существующий ключ.

Возвращаемое значение — дескриптор открытого ключа. При неудачном выполнении функции возникает исключение OSError.

Возбуждает событие аудита auditing event winreg.CreateKey с аргументами key, sub_key, access.

Возбуждает событие аудита auditing event 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.

Возбуждает событие аудита auditing event winreg.CreateKey с аргументами key, sub_key, access.

Возбуждает событие аудита auditing event winreg.OpenKey/result с аргументом key.

Добавлена в версии 3.2.

Изменено в версии 3.3: См. выше.

winreg.DeleteKey(key, sub_key)

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

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

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

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

При успешном выполнении метода весь ключ, включая все его значения, удаляется. При неудачном выполнении возникает исключение OSError.

Возбуждает событие аудита auditing event 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.

Возбуждает событие аудита auditing event winreg.DeleteKey с аргументами key, sub_key, access.

Добавлена в версии 3.2.

Изменено в версии 3.3: См. выше.

winreg.DeleteValue(key, value)

Удаляет именованное значение из ключа реестра.

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

value — строка, определяющая значение для удаления.

Возбуждает событие аудита auditing event winreg.DeleteValue с аргументами key, value.

winreg.EnumKey(key, index)

Перечисляет подключаемые ключи открытого ключа реестра, возвращая строку.

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

index — целое число, определяющее индекс ключа для получения.

Функция каждый раз получает имя одного подключаемого ключа. Обычно она вызывается повторно, пока не произойдёт возбуждение исключения OSError, указывающего на то, что больше значений недоступно.

Возбуждает событие аудита auditing event 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 для 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

автоматически закроет ключ, когда управление покинет блок with.