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

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

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

34.3.1. Функции

В этом модуле представлены следующие функции:

winreg.CloseKey(hkey): Закрывает ранее открытый ключ реестра. Аргумент hkey определяет ранее открытый ключ.

Примечание

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

winreg.ConnectRegistry(computer_name, key)

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

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

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

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

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

winreg.CreateKey(key, sub_key)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

winreg.DeleteKey(key, sub_key)

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

winreg.DeleteValue(key, value)

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

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

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

winreg.EnumKey(key, index)

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

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

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

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

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

winreg.EnumValue(key, index)

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

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

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

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

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

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

winreg.ExpandEnvironmentStrings(str)

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

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

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.OpenKey(key, sub_key, reserved=0, access=KEY_READ)

winreg.OpenKeyEx(key, sub_key, reserved=0, access=KEY_READ)

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

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

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

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

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

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

В случае неудачи генерируется исключение OSError.

Изменено в версии 3.2: Поддержка именованных аргументов.

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

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. Обратите внимание, что привилегии отличаются от разрешений — см. документацию о конфликтах между правами пользователя и разрешениями для получения более подробной информации.

В этом методе для security_attributes передаётся значение NULL.

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

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

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

value — строка, которая задаёт новое значение.

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

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

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

winreg.DisableReflectionKey(key)

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

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

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

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

winreg.EnableReflectionKey(key)

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

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

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

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

winreg.QueryReflectionKey(key)

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

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

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

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

34.3.2. Константы

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

34.3.2.1. Константы 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.

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

Для получения дополнительной информации см. 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: Зарезервировано для системного использования.

34.3.2.2.1. 64-битные

Для получения дополнительной информации см. Accessing an Alternate Registry View.

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

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

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

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

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

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

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

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

END_OF_DOCUMENT_MARKER

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

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

winreg.REG_SZ: Строка с нулевым завершением.

34.3.3. Объекты дескрипторов реестра

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

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

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

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

if handle:
    print("Yes")

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

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

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

PyHKEY.Close()

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

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

PyHKEY.Detach()

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

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

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

PyHKEY.__enter__()

PyHKEY.__exit__(*exc_info)

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

with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
    ...  # work with key

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