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

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

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

1. Функции

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

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

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

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

Изменено в версии 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.

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

В этой функции для security_attributes передаётся NULL в 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 может быть любым — в API всегда передаётся ноль.

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

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

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

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

winreg.DisableReflectionKey(key)

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

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

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

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

winreg.EnableReflectionKey(key)

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

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

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

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

winreg.QueryReflectionKey(key)

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

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

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

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

2. Константы

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

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.

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

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

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

2.2.1. 64-разрядные

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

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

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

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

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

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: Unicode символическая ссылка.

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

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

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

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

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

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

if handle:
    print("Yes")

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

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

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

PyHKEY.Close()

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

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

END_OF_DOCUMENT_MARKER

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

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