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.

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

winreg.CreateKey(key, sub_key)

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

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

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

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

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

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

END_OF_DOCUMENT_MARKER

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

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

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

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

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

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

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

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

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

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

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

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

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 может быть любым — всегда передаётся значение 0 в API.

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

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

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

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

winreg.DisableReflectionKey(key)

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

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

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

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

winreg.EnableReflectionKey(key)

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

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

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

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

winreg.QueryReflectionKey(key)

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

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

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

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

Константы

Следующие константы определены для использования во многих _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-разрядным представлением реестра.

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

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

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

winreg.REG_FULL_RESOURCE_DESCRIPTOR: Настройка аппаратного обеспечения.

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

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

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

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

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

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

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

if handle:
    print("Yes")

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

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

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

PyHKEY.Close()

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

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

PyHKEY.Detach()

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

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

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

PyHKEY.__enter__()

PyHKEY.__exit__(*exc_info)

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

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

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