34.3. winreg – доступ к реестру Windows¶winreg – Windows registry access

34.3.1. Функции¶Functions

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

winreg.CloseKey(hkey)¶

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

Примечание

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

winreg.ConnectRegistry(computer_name, key)¶

Устанавливает соединение с предопределенным дескриптором реестра на другом компьютере и возвращает объект-дескриптор.

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

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

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

Изменено в версии 3.3: См. выше.

winreg.CreateKey(key, sub_key)¶

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

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

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

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

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

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

Изменено в версии 3.3: См. выше.

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

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

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

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

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

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

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

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

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

Новое в версии 3.2.

Изменено в версии 3.3: См. выше.

winreg.DeleteKey(key, sub_key)¶

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

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

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

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

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

Изменено в версии 3.3: См. выше.

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

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

Примечание

Функция DeleteKeyEx() реализована с помощью функции RegDeleteKeyEx из Windows API, которая специфична для 64-разрядных версий Windows. См. документацию по RegDeleteKeyEx.

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

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

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

access – целое число, задающее маску доступа, которая описывает требуемый уровень безопасности для ключа. По умолчанию KEY_WOW64_64KEY. Другие допустимые значения см. в разделе Access Rights.

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

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

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

Новое в версии 3.2.

Изменено в версии 3.3: См. выше.

winreg.DeleteValue(key, value)¶

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

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

value – это строка, определяющая значение, которое нужно удалить.

winreg.EnumKey(key, index)¶

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

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

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

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

Изменено в версии 3.3: См. выше.

winreg.EnumValue(key, index)¶

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

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

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

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

Результат – кортеж из 3 элементов:

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

Изменено в версии 3.3: См. выше.

winreg.ExpandEnvironmentStrings(str)¶

Разворачивает заполнители переменных среды %NAME% в строках типа REG_EXPAND_SZ:

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

winreg.FlushKey(key)¶

Записывает все атрибуты раздела в реестр.

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

Необязательно вызывать FlushKey() для изменения ключа. Изменения в реестре сбрасываются на диск реестром с помощью его отложенного сброса (lazy flusher). Изменения в реестре также сбрасываются на диск при завершении работы системы. В отличие от CloseKey(), метод FlushKey() возвращает управление только после того, как все данные будут записаны в реестр. Приложение должно вызывать FlushKey() только если ему нужна абсолютная уверенность, что изменения в реестре записаны на диск.

Примечание

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

winreg.LoadKey(key, sub_key, file_name)¶

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

key is a handle returned by ConnectRegistry() or one of the constants HKEY_USERS or HKEY_LOCAL_MACHINE.

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

file_name – это имя файла, из которого загружаются данные реестра. Этот файл должен быть создан функцией SaveKey(). В файловой системе FAT (file allocation table) имя файла не может содержать расширение.

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

Если key – это дескриптор, возвращаемый ConnectRegistry(), то путь, указанный в 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. См. Access Rights для других допустимых значений.

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

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

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

Изменено в версии 3.3: См. выше.

winreg.QueryInfoKey(key)¶

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

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

Результат – кортеж из 3 элементов:

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

winreg.QueryValue(key, sub_key)¶

Извлекает безымянное значение для раздела в виде строки.

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

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

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

winreg.QueryValueEx(key, value_name)¶

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

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

value_name – строка, указывающая имя запрашиваемого значения.

Результат – кортеж из 2 элементов:

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

winreg.SaveKey(key, file_name)¶

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

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

file_name – это имя файла, в который будут сохранены данные реестра. Этот файл не должен существовать. Если имя файла содержит расширение, его нельзя использовать в файловых системах FAT (file allocation table) с помощью метода LoadKey().

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

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

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.SetValueEx(key, value_name, reserved, type, value)¶

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

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

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

reserved может быть любым – в API всегда передаётся ноль.

type – это целое число, задающее тип данных. Смотрите Value Types для получения списка доступных типов.

value – это строка, задающая новое значение.

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

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

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

winreg.DisableReflectionKey(key)¶

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

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

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

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

winreg.EnableReflectionKey(key)¶

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

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

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

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

winreg.QueryReflectionKey(key)¶

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

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

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

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

34.3.2. Константы¶Constants

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

34.3.3. Объекты дескрипторов реестра¶Registry Handle Objects

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

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

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

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

if handle:
    print("Yes")

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

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

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

PyHKEY.Close()¶

Закрывает соответствующий дескриптор Windows.

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

PyHKEY.Detach()¶

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

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

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

PyHKEY.__enter__()¶

PyHKEY.__exit__(*exc_info)¶

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

with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
    ...  # работа с ключом

автоматически закроет key, когда управление покинет блок with.