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_*.

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

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

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

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

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

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

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

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

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

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

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

В неподдерживаемых версиях 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: См. выше.

END_OF_DOCUMENT_MARKER

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 — строка, определяющая подключаемый ключ для открытия.

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`	Целое число, указывающее время последнего изменения ключа (если доступно) в виде сотен наносекунд с 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().

Вызывает событие аудита 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: Необходимо для запроса уведомлений об изменениях для ключа реестра или подключа реестра.

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

64-разрядные специфические

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

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

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

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

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

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: Строка с завершением нулем.

END_OF_DOCUMENT_MARKER

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

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

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

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

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

if handle:
    print("Yes")

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

Объекты дескрипторов также поддерживают семантику сравнения, поэтому объекты дескрипторов будут сравниваться как истина, если оба ссылаются на одно и то же значение базового дескриптора 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:
    ...  # work with key

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