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_* constants.
sub_key — это строка с именем ключа, который открывает или создаёт данный метод.
Если key является одним из предопределенных ключей, sub_key может быть
None
. В этом случае возвращаемый дескриптор является тем же дескриптором ключа, который был передан функции.Если ключ уже существует, данная функция открывает существующий ключ.
Возвращаемое значение — это дескриптор открытого ключа. В случае сбоя функции вызывается исключение
OSError
.Вызывает событие аудита
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
. В этом случае возвращаемый дескриптор является тем же дескриптором ключа, который был передан функции.Если ключ уже существует, данная функция открывает существующий ключ.
Возвращаемое значение — это дескриптор открытого ключа. В случае сбоя функции вызывается исключение
OSError
.Вызывает событие аудита
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)¶ Удаляет указанный ключ.
Примечание
Функция
DeleteKeyEx()
реализована с помощью функции Windows API RegDeleteKeyEx, характерной для 64-разрядных версий Windows. См. документацию по RegDeleteKeyEx.key — это уже открытый ключ или одна из предопределенных HKEY_* констант.
sub_key — это строка, которая должна быть подразделом ключа, определяемого параметром key. Это значение не должно быть
None
, и ключ не может иметь подразделов.reserved — это зарезервированное целое число, которое должно быть равно нулю. По умолчанию ноль.
access — целое число, указывающее маску доступа, определяющий желаемый безопасный доступ для ключа. По умолчанию
KEY_WOW64_64KEY
. Другие допустимые значения см. в Права доступа.Данный метод не позволяет удалять ключи с подразделами.
Если метод завершается успешно, весь ключ, включая все его значения, удаляется. Если метод не работает, вызывается исключение
OSError
.В неподдерживаемых версиях 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: См. выше.
-
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 — это строка, определяющая открываемый подраздел 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
Целое число, дающее время последнего изменения ключа (если доступно) в 100 наносекунд с 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()
.Длина значений ограничена доступной памятью. Длинные значения (более 2048 байт) следует хранить в виде файлов с именами файлов, сохраненными в реестре конфигурации. Это помогает реестру работать эффективно.
Вызывает событие аудита
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_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-разрядным представлением реестра.
-
winreg.
KEY_WOW64_32KEY
¶ Указывает, что приложение в 64-разрядной версии Windows должно работать с 32-разрядным представлением реестра.
Типы значений¶
Для получения дополнительной информации см. Типы значений реестра.
-
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
¶ Символическая ссылка Юникод.
-
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("Да")
напечатает Да
, если дескриптор в настоящее время действителен (не был
закрыт или отсоединен).
Объект также поддерживает семантику сравнения, поэтому объекты дескрипторов будут сравниваться как истина, если они оба ссылаются на одно и то же базовое значение дескриптора 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: ... # работа с ключом
автоматически закроет key, когда управление покинет блок
with
.