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

---

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

Изменено в версии 3.3: Несколько функций в этом модуле раньше вызывали WindowsError, который теперь является псевдонимом OSError.

Функции

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

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.

Added in version 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.

Added in version 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.

HKEY_* Константы

winreg.HKEY_CLASSES_ROOT

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

winreg.HKEY_CURRENT_USER

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

winreg.HKEY_LOCAL_MACHINE

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

winreg.HKEY_USERS

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

winreg.HKEY_PERFORMANCE_DATA

Записи реестра, подчиненные этому ключу, позволяют получить доступ к данным о производительности. На самом деле данные не хранятся в реестре; функции реестра заставляют систему собирать данные из источника.

winreg.HKEY_CURRENT_CONFIG

Содержит информацию о текущем профиле аппаратного обеспечения локальной компьютерной системы.

winreg.HKEY_DYN_DATA

Этот ключ не используется в версиях Windows после 98.

Права доступа

Дополнительные сведения см. в разделе Registry Key Security and Access.

winreg.KEY_ALL_ACCESS

Объединяет права доступа STANDARD_RIGHTS_REQUIRED, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY и KEY_CREATE_LINK.

winreg.KEY_WRITE

Объединяет права доступа STANDARD_RIGHTS_WRITE, KEY_SET_VALUE и KEY_CREATE_SUB_KEY.

winreg.KEY_READ

Объединяет значения STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS и KEY_NOTIFY.

winreg.KEY_EXECUTE

Эквивалент KEY_READ.

winreg.KEY_QUERY_VALUE

Требуется для запроса значений ключа реестра.

winreg.KEY_SET_VALUE

Требуется для создания, удаления или установки значения реестра.

winreg.KEY_CREATE_SUB_KEY

Требуется для создания подзамка ключа реестра.

winreg.KEY_ENUMERATE_SUB_KEYS

Требуется для перечисления подзаголовков ключа реестра.

winreg.KEY_NOTIFY

Требуется для запроса уведомлений об изменениях для ключа реестра или для подключей ключа реестра.

winreg.KEY_CREATE_LINK

Зарезервировано для использования в системе.

64-битная специфика

Дополнительные сведения см. в разделе Accessing an Alternate Registry View.

winreg.KEY_WOW64_64KEY

Указывает, что приложение в 64-битной Windows должно работать с 64-битным представлением реестра. В 32-разрядной Windows эта константа игнорируется.

winreg.KEY_WOW64_32KEY

Указывает, что приложение в 64-битной Windows должно работать с 32-битным представлением реестра. В 32-разрядной Windows эта константа игнорируется.

Типы значений

Дополнительные сведения см. в разделе Registry Value Types.

winreg.REG_BINARY

Двоичные данные в любой форме.

winreg.REG_DWORD

32-битное число.

winreg.REG_DWORD_LITTLE_ENDIAN

32-битное число в формате little-endian. Эквивалентно REG_DWORD.

winreg.REG_DWORD_BIG_ENDIAN

32-битное число в формате big-endian.

winreg.REG_EXPAND_SZ

Нуль-терминированная строка, содержащая ссылки на переменные окружения (%PATH%).

winreg.REG_LINK

Символьная ссылка Unicode.

winreg.REG_MULTI_SZ

Последовательность строк с нулевым окончанием, завершающаяся двумя нулевыми символами. (Python обрабатывает это завершение автоматически).

winreg.REG_NONE

Тип значения не определен.

winreg.REG_QWORD

64-битное число.

Added in version 3.6.

winreg.REG_QWORD_LITTLE_ENDIAN

64-битное число в формате little-endian. Эквивалентно REG_QWORD.

Added in version 3.6.

winreg.REG_RESOURCE_LIST

Список ресурсов устройств и драйверов.

winreg.REG_FULL_RESOURCE_DESCRIPTOR

Настройка оборудования.

winreg.REG_RESOURCE_REQUIREMENTS_LIST

Список ресурсов оборудования.

winreg.REG_SZ

Нуль-терминированная строка.

Объекты реестра

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

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

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

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

if handle:
    print("Yes")

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

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

Объекты handle можно преобразовать в целое число (например, с помощью встроенной функции int()), в этом случае возвращается базовое значение Windows handle. Можно также использовать метод 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

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