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.

Raises an auditing event winreg.ConnectRegistry with arguments computer_name, key.

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

winreg.CreateKey(key, sub_key)

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

key является уже открытым ключом или одним из предварительно определенных HKEY_* константы.

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

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

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

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

Raises an auditing event winreg.CreateKey with arguments key, sub_key, access.

Raises an auditing event winreg.OpenKey/result with argument 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.

Raises an auditing event winreg.CreateKey with arguments key, sub_key, access.

Raises an auditing event winreg.OpenKey/result with argument key.

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

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

winreg.DeleteKey(key, sub_key)

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

key является уже открытым ключом или одним из предварительно определенных HKEY_* константы.

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

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

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

Raises an auditing event winreg.DeleteKey with arguments key, sub_key, access.

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

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

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

Примечание

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

key является уже открытым ключом или одним из предварительно определенных HKEY_* константы.

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

reserved является зарезервированным целым числом и должно быть равно нулю. Значение по умолчанию равно нулю.

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

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

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

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

Raises an auditing event winreg.DeleteKey with arguments key, sub_key, access.

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

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

winreg.DeleteValue(key, value)

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

key является уже открытым ключом или одним из предварительно определенных HKEY_* константы.

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

Raises an auditing event winreg.DeleteValue with arguments key, value.

winreg.EnumKey(key, index)

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

key является уже открытым ключом или одним из предварительно определенных HKEY_* константы.

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

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

Raises an auditing event winreg.EnumKey with arguments key, index.

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

winreg.EnumValue(key, index)

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

key является уже открытым ключом или одним из предварительно определенных HKEY_* константы.

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

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

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

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

Raises an auditing event winreg.EnumValue with arguments key, index.

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

winreg.ExpandEnvironmentStrings(str)

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

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

Raises an auditing event winreg.ExpandEnvironmentStrings with argument 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 путь относится к удаленному компьютеру.

Raises an auditing event winreg.LoadKey with arguments 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 поднимается.

Raises an auditing event winreg.OpenKey with arguments key, sub_key, access.

Raises an auditing event winreg.OpenKey/result with argument key.

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

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

winreg.QueryInfoKey(key)

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

key является уже открытым ключом или одним из предварительно определенных HKEY_* константы.

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

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

Raises an auditing event winreg.QueryInfoKey with argument key.

winreg.QueryValue(key, sub_key)

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

key является уже открытым ключом или одним из предварительно определенных HKEY_* константы.

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

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

Raises an auditing event winreg.QueryValue with arguments key, sub_key, value_name.

winreg.QueryValueEx(key, value_name)

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

key является уже открытым ключом или одним из предварительно определенных HKEY_* константы.

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

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

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

Raises an auditing event winreg.QueryValue with arguments key, sub_key, value_name.

winreg.SaveKey(key, file_name)

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

key является уже открытым ключом или одним из предварительно определенных HKEY_* константы.

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

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

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

Raises an auditing event winreg.SaveKey with arguments 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 доступом.

Raises an auditing event winreg.SetValue with arguments key, sub_key, type, value.

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

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

key является уже открытым ключом или одним из предварительно определенных HKEY_* константы.

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

reserved может быть что угодно - ноль всегда передается в API.

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

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

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

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

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

Raises an auditing event winreg.SetValue with arguments key, sub_key, type, value.

winreg.DisableReflectionKey(key)

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

key является уже открытым ключом или одним из предварительно определенных HKEY_* константы.

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

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

Raises an auditing event winreg.DisableReflectionKey with argument key.

winreg.EnableReflectionKey(key)

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

key является уже открытым ключом или одним из предварительно определенных HKEY_* константы.

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

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

Raises an auditing event winreg.EnableReflectionKey with argument key.

winreg.QueryReflectionKey(key)

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

key является уже открытым ключом или одним из предварительно определенных HKEY_* константы.

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

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

Raises an auditing event winreg.QueryReflectionKey with argument 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

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

winreg.KEY_CREATE_LINK

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

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_LINK

Символьная ссылка в Юникоде.

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("Yes")

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

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

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

PyHKEY.Close()

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

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

PyHKEY.Detach()

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

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

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

Raises an auditing event winreg.PyHKEY.Detach with argument key.

PyHKEY.__enter__()

PyHKEY.__exit__(*exc_info)

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

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

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