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

Примечание

Модуль _winreg был переименован в winreg в Python 3. Инструмент 2to3 автоматически адаптирует импорты при преобразовании ваших источников в Python 3.

Введено в версии 2.0.

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

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

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

Примечание

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

_winreg.ConnectRegistry(computer_name, key)

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

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

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

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

_winreg.CreateKey(key, sub_key)

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

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

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

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

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

_winreg.CreateKeyEx(key, sub_key[, res[, sam]])

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

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

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

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

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

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

Введено в версии 2.7.

_winreg.DeleteKey(key, sub_key)

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

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

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

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

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

_winreg.DeleteKeyEx(key, sub_key[, sam[, res]])

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

Примечание

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

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

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

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

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

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

Введено в версии 2.7.

_winreg.DeleteValue(key, value)

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

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

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

_winreg.EnumKey(key, index)

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

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

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

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

_winreg.EnumValue(key, index)

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

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

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

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

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

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

_winreg.ExpandEnvironmentStrings(unicode)

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

>>> ExpandEnvironmentStrings(u"%windir%")
u"C:\\Windows"

Введено в версии 2.6.

_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[, res[, sam]])

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

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

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

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

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

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

Если функция завершается ошибкой, возникает исключение WindowsError.

_winreg.OpenKeyEx(): Функциональность OpenKeyEx() предоставляется через OpenKey() с помощью аргументов по умолчанию.

_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. Обратите внимание, что привилегии отличаются от разрешений — см. документацию Conflicts Between User Rights and Permissions для получения более подробной информации.

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

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

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

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

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

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

END_OF_DOCUMENT_MARKER

_winreg.DisableReflectionKey(key)

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

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

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

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

_winreg.EnableReflectionKey(key)

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

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

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

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

_winreg.QueryReflectionKey(key)

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

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

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

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

1. Константы

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

1.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.

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

1.2.1. 64-битные права доступа

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

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

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

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

Дополнительную информацию см. на Registry Value Types.

_winreg.REG_BINARY: Бинарные данные в любом формате.

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

_winreg.REG_DWORD_LITTLE_ENDIAN: 32-битное число в формате little-endian.

_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_RESOURCE_LIST: Список ресурсов драйвера устройства.

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

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

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

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

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

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

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

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

if handle:
    print "Yes"

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

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

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

END_OF_DOCUMENT_MARKER

PyHKEY.Close()

Закрывает лежащий в основе дескриптор Windows.

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

PyHKEY.Detach()

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

Результат — целое число (или целое число с плавающей точкой на 64-битной 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.

Новая функция в версии 2.6.