35.3. _winreg – доступ к реестру Windows¶_winreg – Windows registry access

Эти функции предоставляют доступ к API реестра Windows из Python. Вместо использования целого числа в качестве дескриптора реестра используется объект-дескриптор, чтобы гарантировать корректное закрытие дескрипторов, даже если программист забудет явно закрыть их.

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

_winreg.CloseKey(hkey)¶

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

Примечание

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

_winreg.ConnectRegistry(computer_name, key)¶

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

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

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

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

_winreg.CreateKey(key, sub_key)¶

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

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

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

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

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

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

_winreg.CreateKeyEx(key, sub_key[, res[, sam]])¶

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

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

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

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

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

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

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

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

_winreg.DeleteKey(key, sub_key)¶

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

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

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

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

В случае успеха метода удаляется весь ключ, включая все его значения. При ошибке возбуждается исключение WindowsError.

_winreg.DeleteKeyEx(key, sub_key[, sam[, res]])¶

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

Примечание

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

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

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

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

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

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

В случае успеха метода удаляется весь ключ, включая все его значения. При ошибке возбуждается исключение WindowsError.

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

_winreg.DeleteValue(key, value)¶

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

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

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

_winreg.EnumKey(key, index)¶

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

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

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

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

_winreg.EnumValue(key, index)¶

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

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

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

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

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

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

_winreg.ExpandEnvironmentStrings(unicode)¶

Заменяет заполнители переменных окружения %NAME% в строках Unicode, например REG_EXPAND_SZ:

>>> ExpandEnvironmentStrings(u"%windir%")
u"C:\\Windows"

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

_winreg.FlushKey(key)¶

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

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

Вызов FlushKey() для изменения раздела не обязателен. Изменения в реестре сбрасываются на диск самим реестром с помощью его отложенного сброса (lazy flusher). Изменения в реестре также сбрасываются на диск при завершении работы системы. В отличие от 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.OpenKey(key, sub_key[, res[, sam]])¶

Открывает указанный раздел и возвращает объект-дескриптор.

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

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

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

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

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

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

_winreg.OpenKeyEx()¶

Функциональность OpenKeyEx() предоставляется через OpenKey(), с использованием аргументов по умолчанию.

_winreg.QueryInfoKey(key)¶

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

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

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

Индекс	Значение
0	Целое число, указывающее количество подразделов, которые есть у этого раздела.
1	Целое число, указывающее количество значений, которые есть у этого раздела.
2	Длинное целое число, указывающее, когда ключ был последний раз изменён (если доступно), в сотнях наносекунд с 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 с методом LoadKey().

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

Эта функция передаёт 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 – это строка, задающая имя подключа, с которым связано значение.

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

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

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

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

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

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

_winreg.DisableReflectionKey(key)¶

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

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

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

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

_winreg.EnableReflectionKey(key)¶

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

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

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

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

_winreg.QueryReflectionKey(key)¶

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

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

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

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

if handle:
    print "Yes"