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

Функции¶

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

winreg.CloseKey(hkey)¶

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

Примечание

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

winreg.ConnectRegistry(computer_name, key)¶

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

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

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

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

Вызывает auditing event winreg.ConnectRegistry с аргументами computer_name, key.

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

winreg.CreateKey(key, sub_key)¶

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

key - это уже открытый ключ, или один из предопределенных 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.

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

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

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

access - целое число, задающее маску доступа, которая описывает желаемый доступ безопасности для ключа. По умолчанию 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)¶

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

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)¶

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

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

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

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

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)¶

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

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

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

Вызывает auditing event winreg.DeleteValue с аргументами key, value.

winreg.EnumKey(key, index)¶

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

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

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

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

Вызывает auditing event winreg.EnumKey с аргументами key, index.

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

winreg.EnumValue(key, index)¶

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

key - это уже открытый ключ, или один из предопределенных 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)¶

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

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

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

Примечание

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

winreg.LoadKey(key, sub_key, file_name)¶

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

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

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

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

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

Если key - это дескриптор, возвращенный командой 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.

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

sub_key - строка, определяющая под_ключ для открытия.

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

access - целое число, задающее маску доступа, которая описывает желаемый доступ безопасности для ключа. По умолчанию 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)¶

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

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

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

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

Вызывает auditing event winreg.QueryInfoKey с аргументом key.

winreg.QueryValue(key, sub_key)¶

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

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

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

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

Вызывает auditing event winreg.QueryValue с аргументами key, sub_key, value_name.

winreg.QueryValueEx(key, value_name)¶

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

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

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

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

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

Вызывает auditing event winreg.QueryValue с аргументами key, sub_key, value_name.

winreg.SaveKey(key, file_name)¶

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

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

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

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

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

Вызывает auditing event winreg.SaveKey с аргументами key, file_name.

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

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

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

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

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)¶

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

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

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

reserved может быть чем угодно - ноль всегда передается 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-битной операционной системе.

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

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

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

Вызывает auditing event winreg.DisableReflectionKey с аргументом key.

winreg.EnableReflectionKey(key)¶

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

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

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

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

Вызывает auditing event winreg.EnableReflectionKey с аргументом key.

winreg.QueryReflectionKey(key)¶

Определяет состояние отражения для указанной клавиши.

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

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

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

Вызывает auditing event winreg.QueryReflectionKey с аргументом key.

Константы¶

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

Объекты обращения к реестру¶

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

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

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

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

if handle:
    print("Yes")

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

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

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

PyHKEY.Close()¶

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

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

PyHKEY.Detach()¶

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

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

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

Вызывает auditing event 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.