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

Функции¶

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

winreg.CloseKey(hkey)¶

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

Примечание

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

winreg.ConnectRegistry(computer_name, key)¶

Устанавливает соединение с предопределенным дескриптором реестра на другом компьютере и возвращает значение handle object.

имя_компьютера - это имя удаленного компьютера, которое имеет вид r"\\computername". Если None, то используется локальный компьютер.

ключ - это предопределенный дескриптор для подключения.

Возвращаемое значение является дескриптором открытого ключа. Если функция завершается ошибкой, возникает исключение OSError.

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

Изменено в версии 3.3: Смотрите above.

winreg.CreateKey(key, sub_key)¶

Создает или открывает указанный ключ, возвращая значение handle object.

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

sub_key - это строка с именем ключа, который открывается или создается этим методом.

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

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

Возвращаемое значение является дескриптором открытого ключа. Если функция завершается ошибкой, возникает исключение OSError.

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

Создает auditing event winreg.OpenKey/result с аргументом key.

Изменено в версии 3.3: Смотрите above.

winreg.CreateKeyEx(key, sub_key, reserved=0, access=KEY_WRITE)¶

Создает или открывает указанный ключ, возвращая значение handle object.

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

sub_key - это строка с именем ключа, который открывается или создается этим методом.

зарезервировано - это зарезервированное целое число, которое должно быть равно нулю. Значение по умолчанию равно нулю.

доступ - это целое число, задающее маску доступа, описывающую желаемый режим доступа для ключа. По умолчанию используется значение KEY_WRITE. Другие допустимые значения приведены в Access Rights.

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

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

Возвращаемое значение является дескриптором открытого ключа. Если функция завершается ошибкой, возникает исключение OSError.

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

Создает auditing event winreg.OpenKey/result с аргументом key.

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

Изменено в версии 3.3: Смотрите above.

winreg.DeleteKey(key, sub_key)¶

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

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

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

Этот метод не позволяет удалять ключи с подразделами.

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

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

Изменено в версии 3.3: Смотрите above.

winreg.DeleteKeyEx(key, sub_key, access=KEY_WOW64_64KEY, reserved=0)¶

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

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

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

зарезервировано - это зарезервированное целое число, которое должно быть равно нулю. Значение по умолчанию равно нулю.

access - это целое число, задающее маску доступа, описывающую желаемый режим доступа для ключа. По умолчанию используется значение KEY_WOW64_64KEY. В 32-разрядной Windows константы WOW64 игнорируются. Другие допустимые значения приведены в разделе Access Rights.

Этот метод не позволяет удалять ключи с подразделами.

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

В неподдерживаемых версиях Windows отображается значение NotImplementedError.

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

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

Изменено в версии 3.3: Смотрите above.

winreg.DeleteValue(key, value)¶

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

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

значение - это строка, которая идентифицирует значение, подлежащее удалению.

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

winreg.EnumKey(key, index)¶

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

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

index - это целое число, которое определяет индекс извлекаемого ключа.

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

Создает auditing event winreg.EnumKey с аргументами key, index.

Изменено в версии 3.3: Смотрите above.

winreg.EnumValue(key, index)¶

Перечисляет значения открытого раздела реестра, возвращая кортеж.

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

index - это целое число, которое определяет индекс извлекаемого значения.

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

В результате получается кортеж из 3 элементов:

Индекс	Значение
0	Строка, идентифицирующая имя значения
1	Объект, содержащий данные о значении, тип которого зависит от базового типа реестра
2	Целое число, определяющее тип данных значения (смотрите таблицу в документации для SetValueEx())

Создает auditing event winreg.EnumValue с аргументами key, index.

Изменено в версии 3.3: Смотрите above.

winreg.ExpandEnvironmentStrings(str)¶

Расширяет поля-заполнители переменных окружения %NAME% в строках типа REG_EXPAND_SZ:

>>> ExpandEnvironmentStrings('%windir%')
'C:\\Windows'

Создает auditing event winreg.ExpandEnvironmentStrings с аргументом str.

winreg.FlushKey(key)¶

Записывает все атрибуты ключа в реестр.

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

Для изменения ключа нет необходимости вызывать FlushKey(). Изменения в реестре записываются на диск системой registry с помощью функции отложенной очистки. Изменения в реестре также записываются на диск при завершении работы системы. В отличие от CloseKey(), метод FlushKey() возвращает результат только после того, как все данные были записаны в реестр. Приложение должно вызывать FlushKey() только в том случае, если требуется абсолютная уверенность в том, что изменения реестра внесены на диск.

Примечание

Если вы не знаете, требуется ли вызов FlushKey(), то, скорее всего, это не так.

winreg.LoadKey(key, sub_key, file_name)¶

Создает подраздел под указанным ключом и сохраняет регистрационную информацию из указанного файла в этом подразделе.

ключ - это дескриптор, возвращаемый ConnectRegistry() или одной из констант HKEY_USERS или HKEY_LOCAL_MACHINE.

вложенный ключ - это строка, которая идентифицирует загружаемый подраздел.

имя_файла - это имя файла, из которого загружаются данные реестра. Этот файл должен быть создан с помощью функции SaveKey(). В файловой системе с таблицей размещения файлов (FAT) имя файла может не иметь расширения.

Вызов LoadKey() завершается ошибкой, если вызывающий процесс не имеет привилегии SE_RESTORE_PRIVILEGE. Обратите внимание, что привилегии отличаются от разрешений - более подробную информацию смотрите в RegLoadKey documentation.

Если ключ является дескриптором, возвращаемым ConnectRegistry(), то путь, указанный в имя_файла, относится к удаленному компьютеру.

Создает auditing event 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)¶

Открывает указанный ключ, возвращая значение handle object.

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

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

зарезервировано - это зарезервированное целое число, которое должно быть равно нулю. Значение по умолчанию равно нулю.

доступ - это целое число, задающее маску доступа, описывающую желаемый режим доступа для ключа. По умолчанию используется значение KEY_READ. Другие допустимые значения приведены в Access Rights.

Результатом является новый дескриптор указанного ключа.

Если функция завершается сбоем, генерируется OSError.

Создает auditing event winreg.OpenKey с аргументами key, sub_key, access.

Создает auditing event winreg.OpenKey/result с аргументом key.

Изменено в версии 3.2: Разрешите использование именованных аргументов.

Изменено в версии 3.3: Смотрите above.

winreg.QueryInfoKey(key)¶

Возвращает информацию о ключе в виде кортежа.

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

В результате получается кортеж из 3 элементов:

Индекс	Значение
0	Целое число, указывающее количество подразделов, которые есть у этого ключа.
1	Целое число, указывающее количество значений, которые имеет этот ключ.
2	Целое число, указывающее, когда ключ был изменен в последний раз (если таковой имеется) в течение 100 наносекунд с 1 января 1601 года.

Создает auditing event winreg.QueryInfoKey с аргументом key.

winreg.QueryValue(key, sub_key)¶

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

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

вложенный ключ - это строка, содержащая имя подраздела, с которым связано значение. Если этот параметр равен None или пуст, функция извлекает значение, установленное методом SetValue() для ключа, обозначенного key.

Значения в реестре содержат имя, тип и компоненты данных. Этот метод извлекает данные для первого значения ключа, которое имеет имя NULL. Но базовый вызов API не возвращает тип, поэтому всегда используйте QueryValueEx(), если это возможно.

Создает auditing event winreg.QueryValue с аргументами key, sub_key, value_name.

winreg.QueryValueEx(key, value_name)¶

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

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

имя_значения - это строка, указывающая значение для запроса.

В результате получается кортеж из 2 элементов:

Индекс	Значение
0	Значение элемента реестра.
1	Целое число, указывающее тип реестра для этого значения (смотрите таблицу в документации для SetValueEx())

Создает auditing event winreg.QueryValue с аргументами key, sub_key, value_name.

winreg.SaveKey(key, file_name)¶

Сохраняет указанный ключ и все его подразделы в указанном файле.

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

имя_файла - это имя файла, в который будут сохранены данные реестра. Этот файл не может уже существовать. Если это имя файла содержит расширение, оно не может быть использовано в файловых системах с таблицей размещения файлов (FAT) методом LoadKey().

Если key представляет собой ключ на удаленном компьютере, путь, описываемый имя_файла, относится к удаленному компьютеру. Вызывающий этот метод должен обладать привилегией безопасности SeBackupPrivilege. Обратите внимание, что привилегии отличаются от разрешений - смотрите Conflicts Between User Rights and Permissions documentation для получения более подробной информации.

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

Создает auditing event winreg.SaveKey с аргументами key, file_name.

winreg.SetValue(key, sub_key, type, value)¶

Связывает значение с указанным ключом.

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

вложенный ключ - это строка, дающая имя подразделу, с которым связано значение.

type - это целое число, которое определяет тип данных. В настоящее время это значение должно быть REG_SZ, что означает, что поддерживаются только строки. Используйте функцию SetValueEx() для поддержки других типов данных.

value - это строка, указывающая новое значение.

Если ключ, указанный параметром sub_key, не существует, функция setValue создает его.

Длина значений ограничена доступной памятью. Длинные значения (более 2048 байт) следует сохранять в виде файлов с именами, сохраненными в реестре конфигурации. Это помогает реестру работать эффективно.

Ключ, указанный параметром key, должен быть открыт с доступом KEY_SET_VALUE.

Создает auditing event winreg.SetValue с аргументами key, sub_key, type, value.

winreg.SetValueEx(key, value_name, reserved, type, value)¶

Хранит данные в поле значение открытого раздела реестра.

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

имя_значения - это строка, дающая имя подразделу, с которым связано значение.

зарезервировано может быть что угодно - ноль всегда передается в API.

type - это целое число, которое определяет тип данных. Доступные типы приведены в разделе Value Types.

value - это строка, указывающая новое значение.

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

Чтобы открыть ключ, используйте методы CreateKey() или OpenKey().

Длина значений ограничена доступной памятью. Длинные значения (более 2048 байт) следует сохранять в виде файлов с именами, сохраненными в реестре конфигурации. Это помогает реестру работать эффективно.

Создает auditing event winreg.SetValue с аргументами key, sub_key, type, value.

winreg.DisableReflectionKey(key)¶

Отключает отображение реестра для 32-разрядных процессов, запущенных в 64-разрядной операционной системе.

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

Обычно вызывает NotImplementedError, если выполняется в 32-разрядной операционной системе.

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

Создает auditing event winreg.DisableReflectionKey с аргументом key.

winreg.EnableReflectionKey(key)¶

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

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

Обычно вызывает NotImplementedError, если выполняется в 32-разрядной операционной системе.

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

Создает auditing event winreg.EnableReflectionKey с аргументом key.

winreg.QueryReflectionKey(key)¶

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

ключ - это уже открытый ключ или один из предопределенных HKEY_* constants.

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

Обычно вызывает NotImplementedError, если выполняется в 32-разрядной операционной системе.

Создает auditing event winreg.QueryReflectionKey с аргументом key.

Константы¶

Следующие константы определены для использования во многих функциях winreg.

Объекты управления реестром¶

Этот объект обертывает объект Windows HKEY, автоматически закрывая его при уничтожении объекта. Чтобы гарантировать очистку, вы можете вызвать либо метод Close() для объекта, либо функцию CloseKey().

Все функции реестра в этом модуле возвращают один из этих объектов.

Все функции реестра в этом модуле, которые принимают объект handle, также принимают целое число, однако рекомендуется использовать объект handle.

Объекты Handle предоставляют семантику для __bool__() - таким образом

if handle:
    print("Yes")

выведет Yes, если дескриптор в данный момент действителен (не был закрыт или отсоединен).

Объект также поддерживает семантику сравнения, поэтому объекты-дескрипторы будут сравниваться с true, если они оба ссылаются на одно и то же базовое значение дескриптора Windows.

Объекты-дескрипторы могут быть преобразованы в целое число (например, с помощью встроенной функции int()), и в этом случае возвращается базовое значение дескриптора Windows. Вы также можете использовать метод Detach() для возврата целочисленного дескриптора, а также отключить дескриптор Windows от объекта handle.

PyHKEY.Close()¶

Закрывает базовый дескриптор Windows.

Если дескриптор уже закрыт, ошибка не возникает.

PyHKEY.Detach()¶

Отсоединяет дескриптор Windows от объекта handle.

Результатом является целое число, которое содержит значение дескриптора до его отсоединения. Если дескриптор уже отсоединен или закрыт, это вернет ноль.

После вызова этой функции дескриптор фактически становится недействительным, но не закрывается. Эту функцию можно вызвать, если вам нужно, чтобы базовый дескриптор Win32 существовал после истечения срока действия объекта handle.

Создает auditing event winreg.PyHKEY.Detach с аргументом key.

PyHKEY.__enter__()¶

PyHKEY.__exit__(*exc_info)¶

Объект KEY реализует __enter__() и __exit__() и, таким образом, поддерживает контекстный протокол для оператора with:

with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
    ...  # work with key

автоматически закроет клавишу, когда элемент управления выйдет из блока with.