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

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

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

Функции

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

winreg.CloseKey(hkey)

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

Примечание

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

winreg.ConnectRegistry(computer_name, key)

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

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

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

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

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

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

winreg.CreateKey(key, sub_key)

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

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

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

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

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

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

Вызывает событие аудита winreg.CreateKey с аргументами key, sub_key, access.

Вызывает событие аудита winreg.OpenKey/result с аргументом key.

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

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

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

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

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

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

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

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

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

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

Вызывает событие аудита winreg.CreateKey с аргументами key, sub_key, access.

Вызывает событие аудита winreg.OpenKey/result с аргументом key.

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

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

winreg.DeleteKey(key, sub_key)

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

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

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

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

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

Вызывает событие аудита winreg.DeleteKey с аргументами key, sub_key, access.

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

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

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

Примечание

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

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

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

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

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

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

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

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

Вызывает событие аудита winreg.DeleteKey с аргументами key, sub_key, access.

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

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

winreg.DeleteValue(key, value)

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

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

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

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

winreg.EnumKey(key, index)

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

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

index — это целое число, определяющее индекс ключа, который необходимо получает.

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

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

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

winreg.EnumValue(key, index)

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

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

index — это целое число, определяющее индекс значения, которое необходимо получает.

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

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

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

Вызывает событие аудита winreg.EnumValue с аргументами key, index.

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

winreg.ExpandEnvironmentStrings(str)

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

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

Вызывает событие аудита winreg.ExpandEnvironmentStrings с аргументом str.

winreg.FlushKey(key)

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

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

Нет необходимости вызывать FlushKey(), чтобы сменить ключ. Изменения реестра сбрасываются на диск реестром с помощью его отложенного сброса. Изменения реестра также сбрасываются на диск при завершении работы системы. В отличие от 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.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)

Открывает указанный ключ, возвращая обрабатываемый объект.

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

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

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

access — целое число, указывающее маску доступа, описывающую желаемый безопасный доступ для ключа. По умолчанию KEY_READ. Другие допустимые значения см. в Правах доступа.

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

В случае сбоя функции вызывается OSError.

Вызывает событие аудита winreg.OpenKey с аргументами key, sub_key, access.

Вызывает событие аудита winreg.OpenKey/result с аргументом key.

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

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

winreg.QueryInfoKey(key)

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

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

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

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

Вызывает событие аудита winreg.QueryInfoKey с аргументом key.

winreg.QueryValue(key, sub_key)

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

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

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

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

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

winreg.QueryValueEx(key, value_name)

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

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

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

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

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

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

winreg.SaveKey(key, file_name)

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

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

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

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

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

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

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.SetValue с аргументами key, sub_key, type, value.

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

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

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

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

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

type — целое число, указывающее тип данных. Доступные типы см. в Типы значений.

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

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

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

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

Вызывает событие аудита winreg.SetValue с аргументами key, sub_key, type, value.

winreg.DisableReflectionKey(key)

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

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

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

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

Вызывает событие аудита winreg.DisableReflectionKey с аргументом key.

winreg.EnableReflectionKey(key)

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

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

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

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

Вызывает событие аудита winreg.EnableReflectionKey с аргументом key.

winreg.QueryReflectionKey(key)

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

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

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

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

Вызывает событие аудита 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.

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

Для получения дополнительной информации см. Безопасность и доступ к ключу реестра.

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

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

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

64-битная версия

Дополнительные сведения см. в статье Доступ к альтернативному представлению реестра.

winreg.KEY_WOW64_64KEY

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

winreg.KEY_WOW64_32KEY

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

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

Для получения дополнительной информации см. Типы значений реестра.

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_MULTI_SZ

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

winreg.REG_NONE

Нет определённого типа значения.

winreg.REG_QWORD

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

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

winreg.REG_QWORD_LITTLE_ENDIAN

64-битное число в формате с прямым порядком (little-endian) байтов. Эквивалент REG_QWORD.

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

winreg.REG_RESOURCE_LIST

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

winreg.REG_FULL_RESOURCE_DESCRIPTOR

Аппаратная настройка.

winreg.REG_RESOURCE_REQUIREMENTS_LIST

Список аппаратных ресурсов.

winreg.REG_SZ

Строка с завершающим нулем.

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

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

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

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

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

if handle:
    print("Да")

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

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

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

PyHKEY.Close()

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

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

PyHKEY.Detach()

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

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

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

Вызывает событие аудита winreg.PyHKEY.Detach с аргументом key.

PyHKEY.__enter__()
PyHKEY.__exit__(*exc_info)

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

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

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