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. Обратите внимание: привилегии отличаются от разрешений. Подробнее см. в документации о конфликтах между правами пользователей и разрешениями.

Эта функция передаёт в API значение NULL для параметра 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.