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 для 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.