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 — имя файла, в который сохраняются данные реестра. Этот файл не должен уже существовать. Если имя файла содержит расширение, метод LoadKey() не сможет использовать его в файловых системах FAT.

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

Эта функция передаёт NULL API в качестве security_attributes.

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

При вызове в 32-разрядной операционной системе обычно возбуждается исключение NotImplementedError.

Если ключ отсутствует в списке отражения, функция завершается успешно, но ничего не делает. Отключение отражения для ключа не влияет на отражение его подразделов.

Возбуждает событие аудита winreg.DisableReflectionKey с аргументом key.

winreg.EnableReflectionKey(key)

Восстанавливает отражение реестра для указанного ключа, для которого оно было отключено.

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

При вызове в 32-разрядной операционной системе обычно возбуждается исключение NotImplementedError.

Восстановление отражения для ключа не влияет на отражение его подразделов.

Возбуждает событие аудита winreg.EnableReflectionKey с аргументом key.

winreg.QueryReflectionKey(key)

Определяет состояние отражения для указанного ключа.

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

Возвращает True, если отражение отключено.

При вызове в 32-разрядной операционной системе обычно возбуждается исключение NotImplementedError.

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