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 если дескриптор в настоящее время действителен (не был закрыт или отсоединён).

Объекты также поддерживают семантику сравнения, поэтому объекты дескрипторов будут сравнивать true, если оба ссылаются на одно и то же значение базового дескриптора 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.