winreg.md

1> **Источник:** https://python-all.ru/3.0/library/winreg.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `winreg` – доступ к реестру Windows89*Платформы:* Windows1011Эти функции предоставляют доступ к Windows registry API из Python. Вместо целого числа в качестве дескриптора реестра используется объект-дескриптор, чтобы гарантировать корректное закрытие дескрипторов, даже если программист забудет явно закрыть их.1213Этот модуль предоставляет очень низкоуровневый интерфейс к реестру Windows; ожидается, что в будущем будет создан новый модуль `winreg`, предлагающий более высокоуровневый интерфейс к API реестра.1415Этот модуль предоставляет следующие функции:1617#### `[winreg.CloseKey]winreg.CloseKey(hkey)`1819Закрывает ранее открытый ключ реестра. Аргумент hkey задаёт ранее открытый ключ.2021Обратите внимание, что если *hkey* не был закрыт с помощью этого метода (или через `handle.Close()`), он закрывается, когда объект *hkey* уничтожается Python.2223#### `[winreg.ConnectRegistry]winreg.ConnectRegistry(computer_name, key)`2425Устанавливает соединение с предопределённым дескриптором реестра на другом компьютере и возвращает *объект-дескриптор*2627*computer\_name* – это имя удалённого компьютера, в форме `r"\\computername"`. Если `None`, используется локальный компьютер.2829*key* – это предопределенный дескриптор для подключения.3031Возвращаемое значение – дескриптор открытого ключа. Если функция завершается ошибкой, возбуждается исключение [`EnvironmentError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.EnvironmentError).3233#### `[winreg.CreateKey]winreg.CreateKey(key, sub_key)`3435Создаёт или открывает указанный ключ, возвращая *объект-дескриптор*3637*key* – это уже открытый ключ или одна из предопределённых констант `HKEY_*`.3839*sub\_key* – строка, задающая имя ключа, который этот метод открывает или создаёт.4041Если *key* – один из предопределённых ключей, *sub\_key* может быть `None`. В этом случае возвращаемый дескриптор – это тот же дескриптор ключа, который был передан функции.4243Если ключ уже существует, эта функция открывает существующий ключ.4445Возвращаемое значение – дескриптор открытого ключа. Если функция завершается ошибкой, возбуждается исключение [`EnvironmentError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.EnvironmentError).4647#### `[winreg.DeleteKey]winreg.DeleteKey(key, sub_key)`4849Удаляет указанный ключ.5051*key* – уже открытый ключ или любая из предопределённых констант `HKEY_*`.5253*sub\_key* – это строка, которая должна быть подключом ключа, указанного *key* параметром. Это значение не должно быть `None`, и ключ не может содержать подключи.5455*Этот метод не может удалять ключи, содержащие подразделы.*5657Если метод выполняется успешно, удаляется весь ключ, включая все его значения. Если метод завершается ошибкой, возбуждается исключение [`EnvironmentError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.EnvironmentError).5859#### `[winreg.DeleteValue]winreg.DeleteValue(key, value)`6061Удаляет именованное значение из ключа реестра.6263*key* – уже открытый ключ или одна из предопределённых констант `HKEY_*`.6465*value* – это строка, определяющая значение, которое нужно удалить.6667#### `[winreg.EnumKey]winreg.EnumKey(key, index)`6869Перечисляет подразделы открытого ключа реестра, возвращая строку.7071*key* – уже открытый ключ или любая из предопределённых констант `HKEY_*`.7273*index* – целое число, идентифицирующее индекс извлекаемого ключа.7475Функция извлекает имя одного подключа при каждом вызове. Обычно она вызывается повторно до тех пор, пока не будет возбуждено исключение [`EnvironmentError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.EnvironmentError), указывающее на отсутствие других значений.7677#### `[winreg.EnumValue]winreg.EnumValue(key, index)`7879Перечисляет значения открытого ключа реестра, возвращая кортеж.8081*key* – уже открытый ключ или любая из предопределённых констант `HKEY_*`.8283*index* – целое число, идентифицирующее индекс извлекаемого значения.8485Функция извлекает имя одного подключа при каждом вызове. Обычно она вызывается повторно, пока не будет возбуждено исключение [`EnvironmentError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.EnvironmentError), указывающее на отсутствие значений.8687Результат – кортеж из 3 элементов:8889| Индекс | Значение |90| --- | --- |91| `0` | Строка, идентифицирующая имя значения. |92| `1` | Объект, содержащий данные значения, и его тип зависит от базового типа раздела реестра. |93| `2` | Целое число, идентифицирующее тип данных значения. |9495#### `[winreg.ExpandEnvironmentStrings]winreg.ExpandEnvironmentStrings(unicode)`9697Разворачивает строки окружения %NAME% в строке Unicode, как константа *REG\_EXPAND\_SZ*:9899```python100>>> ExpandEnvironmentStrings(u"%windir%")101u"C:\\Windows"102```103104#### `[winreg.FlushKey]winreg.FlushKey(key)`105106Записывает все атрибуты раздела в реестр.107108*key* – уже открытый ключ или одна из предопределённых констант `HKEY_*`.109110It is not necessary to call [`FlushKey()`](https://python-all.ru/3.0/library/winreg.html#winreg.FlushKey) to change a key. Registry changes are flushed to disk by the registry using its lazy flusher. Registry changes are also flushed to disk at system shutdown. Unlike [`CloseKey()`](https://python-all.ru/3.0/library/winreg.html#winreg.CloseKey), the [`FlushKey()`](https://python-all.ru/3.0/library/winreg.html#winreg.FlushKey) method returns only when all the data has been written to the registry. An application should only call [`FlushKey()`](https://python-all.ru/3.0/library/winreg.html#winreg.FlushKey) if it requires absolute certainty that registry changes are on disk.111112> **Примечание**113>114> Если неизвестно, необходим ли вызов [`FlushKey()`](https://python-all.ru/3.0/library/winreg.html#winreg.FlushKey), то, скорее всего, он не нужен.115116#### `[winreg.LoadKey]winreg.LoadKey(key, sub_key, file_name)`117118Создаёт подключ под указанным ключом и сохраняет информацию регистрации из указанного файла в этот подключ.119120*key* – уже открытый ключ или любая из предопределённых констант `HKEY_*`.121122*sub\_key* – строка, идентифицирующая загружаемый подключ.123124*file\_name* – это имя файла, из которого загружаются данные реестра. Этот файл должен быть создан функцией [`SaveKey()`](https://python-all.ru/3.0/library/winreg.html#winreg.SaveKey). В файловой системе FAT (file allocation table) имя файла не может содержать расширение.125126Вызов LoadKey() завершается ошибкой, если вызывающий процесс не имеет привилегии `SE_RESTORE_PRIVILEGE`. Обратите внимание: привилегии отличаются от разрешений – подробнее см. в документации Win32.127128Если *key* – дескриптор, возвращённый [`ConnectRegistry()`](https://python-all.ru/3.0/library/winreg.html#winreg.ConnectRegistry), то путь, указанный в *fileName*, является относительным для удалённого компьютера.129130В документации Win32 подразумевается, что *key* должен находиться в ветке `HKEY_USER` или `HKEY_LOCAL_MACHINE`. Это может быть как верно, так и нет.131132#### `[winreg.OpenKey]winreg.OpenKey(key, sub_key[, res=0][, sam=KEY_READ])`133134Открывает указанный ключ, возвращая *объект-дескриптор*135136*key* – уже открытый ключ или любая из предопределённых констант `HKEY_*`.137138*sub\_key* – это строка, идентифицирующая открываемый подраздел.139140*res* – зарезервированное целое число, должно быть равно нулю. По умолчанию – ноль.141142*sam* – целое число, задающее маску доступа, описывающую требуемый уровень безопасности для ключа. По умолчанию `KEY_READ`143144Результат – новый дескриптор указанного раздела.145146Если функция завершается ошибкой, возбуждается исключение [`EnvironmentError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.EnvironmentError).147148#### `[winreg.OpenKeyEx]winreg.OpenKeyEx()`149150Функциональность151152[`OpenKeyEx()`](https://python-all.ru/3.0/library/winreg.html#winreg.OpenKeyEx)153154предоставляется через155156[`OpenKey()`](https://python-all.ru/3.0/library/winreg.html#winreg.OpenKey)157158с использованием аргументов по умолчанию.159160#### `[winreg.QueryInfoKey]winreg.QueryInfoKey(key)`161162Возвращает информацию о разделе в виде кортежа.163164*key* – уже открытый ключ или одна из предопределённых констант `HKEY_*`.165166Результат – кортеж из 3 элементов:167168| Индекс | Значение |169| --- | --- |170| `0` | Целое число, указывающее количество подразделов, которые есть у этого раздела. |171| `1` | Целое число, указывающее количество значений, которые есть у этого раздела. |172| `2` | Целое число, указывающее время последнего изменения ключа (если доступно), в сотнях наносекунд с 1 января 1600 года. |173174#### `[winreg.QueryValue]winreg.QueryValue(key, sub_key)`175176Извлекает безымянное значение ключа в виде строки177178*key* – уже открытый ключ или одна из предопределённых констант `HKEY_*`.179180*sub\_key* – строка, содержащая имя подключа, с которым связано значение. Если этот параметр равен `None` или пуст, функция извлекает значение, заданное методом [`SetValue()`](https://python-all.ru/3.0/library/winreg.html#winreg.SetValue) для ключа, определяемого *key*.181182Значения в реестре имеют компоненты имени, типа и данных. Этот метод извлекает данные для первого значения ключа с именем NULL. Однако нижележащий вызов API не возвращает тип. Некруто, некруто, некруто – НЕ ИСПОЛЬЗУЙТЕ ЭТОТ МЕТОД!!!183184#### `[winreg.QueryValueEx]winreg.QueryValueEx(key, value_name)`185186Извлекает тип и данные для указанного имени значения, связанного с открытым ключом реестра.187188*key* – уже открытый ключ или одна из предопределённых констант `HKEY_*`.189190*value\_name* – строка, указывающая имя запрашиваемого значения.191192Результат – кортеж из 2 элементов:193194| Индекс | Значение |195| --- | --- |196| `0` | Значение элемента реестра. |197| `1` | Целое число, задающее тип реестра для этого значения. |198199#### `[winreg.SaveKey]winreg.SaveKey(key, file_name)`200201Сохраняет указанный раздел и все его подразделы в указанный файл.202203*key* – уже открытый ключ или одна из предопределённых констант `HKEY_*`.204205*file\_name* – это имя файла, в который будут сохранены данные реестра. Этот файл не должен существовать. Если имя файла содержит расширение, его нельзя использовать в файловых системах с таблицей размещения файлов (FAT) методами [`LoadKey()`](https://python-all.ru/3.0/library/winreg.html#winreg.LoadKey), `ReplaceKey()` или `RestoreKey()`.206207Если *key* представляет раздел на удалённом компьютере, то путь, задаваемый *file\_name*, указывается относительно этого удалённого компьютера. Вызывающий этот метод должен обладать привилегией безопасности `SeBackupPrivilege`. Обратите внимание: привилегии отличаются от разрешений – подробнее см. в документации Win32.208209Эта функция передаёт NULL для *security\_attributes* в API.210211#### `[winreg.SetValue]winreg.SetValue(key, sub_key, type, value)`212213Связывает значение с указанным разделом.214215*key* – это уже открытый раздел или одна из предопределённых констант `HKEY_*`.216217*sub\_key* – это строка, задающая имя подраздела, с которым связано значение.218219*type* – это целое число, задающее тип данных. В настоящее время это должен быть `REG_SZ`, то есть поддерживаются только строки. Для работы с другими типами данных используйте функцию [`SetValueEx()`](https://python-all.ru/3.0/library/winreg.html#winreg.SetValueEx).220221*value* – это строка, задающая новое значение.222223Если раздел, указанный параметром *sub\_key*, не существует, функция SetValue создаёт его.224225Длина значений ограничена доступной памятью. Длинные значения (более 2048 байт) следует хранить в виде файлов, имена которых сохраняются в конфигурационном реестре. Это помогает реестру работать эффективно.226227Раздел, указанный параметром *key*, должен быть открыт с правом доступа `KEY_SET_VALUE`.228229#### `[winreg.SetValueEx]winreg.SetValueEx(key, value_name, reserved, type, value)`230231Сохраняет данные в поле значения открытого ключа реестра.232233*key* – это уже открытый раздел или одна из предопределённых констант `HKEY_*`.234235*value\_name* – это строка, задающая имя подраздела, с которым связано значение.236237*type* – это целое число, задающее тип данных. Это должна быть одна из следующих констант, определённых в данном модуле:238239| Константа | Значение |240| --- | --- |241| `REG_BINARY` | Двоичные данные в любом виде. |242| `REG_DWORD` | 32-битное число. |243| `REG_DWORD_LITTLE_ENDIAN` | 32-разрядное число в формате little-endian. |244| `REG_DWORD_BIG_ENDIAN` | 32-разрядное число в формате big-endian. |245| `REG_EXPAND_SZ` | Строка, завершающаяся нулевым символом, содержащая ссылки на переменные окружения (`%PATH%`). |246| `REG_LINK` | Символическая ссылка в Юникоде. |247| `REG_MULTI_SZ` | Последовательность строк, завершающихся нулевым символом, заканчивающаяся двумя нулевыми символами. (Python обрабатывает это завершение автоматически.) |248| `REG_NONE` | Неопределённый тип значения. |249| `REG_RESOURCE_LIST` | Список ресурсов драйвера устройства. |250| `REG_SZ` | Нуль-терминированная строка. |251252*reserved* может быть чем угодно – в API всегда передаётся ноль.253254*value* – это строка, задающая новое значение.255256Этот метод также может задавать дополнительные данные и информацию о типе для указанного раздела. Раздел, указанный параметром key, должен быть открыт с правом доступа `KEY_SET_VALUE`.257258Чтобы открыть раздел, используйте методы `CreateKeyEx()` или [`OpenKey()`](https://python-all.ru/3.0/library/winreg.html#winreg.OpenKey).259260Длина значений ограничена доступной памятью. Длинные значения (более 2048 байт) следует хранить в виде файлов, имена которых сохраняются в конфигурационном реестре. Это помогает реестру работать эффективно.261262## Объекты дескрипторов реестра263264Этот объект оборачивает объект Windows HKEY, автоматически закрывая его при уничтожении объекта. Чтобы гарантированно освободить ресурсы, можно вызвать либо метод `Close()` самого объекта, либо функцию [`CloseKey()`](https://python-all.ru/3.0/library/winreg.html#winreg.CloseKey).265266Все функции реестра в этом модуле возвращают один из таких объектов.267268Все функции реестра в этом модуле, принимающие объект дескриптора, также принимают целое число, однако рекомендуется использовать объект дескриптора.269270Объекты дескриптора поддерживают семантику [`__bool__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__bool__) – поэтому271272```python273if handle:274    print("Yes")275```276277будет выведено `Yes`, если дескриптор в текущий момент действителен (не был закрыт или отсоединён).278279Объект также поддерживает семантику сравнения, поэтому объекты дескрипторов будут сравниваться как равные, если оба ссылаются на одно и то же значение базового дескриптора Windows.280281Объекты дескриптора можно преобразовать в целое число (например, с помощью встроенной функции [`int()`](https://python-all.ru/3.0/library/functions.html#int)), в этом случае возвращается базовое значение дескриптора Windows. Также можно использовать метод `Detach()`, чтобы получить целочисленный дескриптор и отсоединить дескриптор Windows от объекта дескриптора.282283#### `[winreg.PyHKEY.Close]PyHKEY.Close()`284285Закрывает соответствующий дескриптор Windows.286287Если дескриптор уже закрыт, ошибка не возникает.288289#### `[winreg.PyHKEY.Detach]PyHKEY.Detach()`290291Отсоединяет дескриптор Windows от объекта дескриптора.292293Результат – целое число, содержащее значение дескриптора до его отсоединения. Если дескриптор уже отсоединён или закрыт, возвращается ноль.294295После вызова этой функции дескриптор фактически становится недействительным, но дескриптор не закрывается. Эту функцию следует вызывать, когда требуется, чтобы базовый дескриптор Win32 существовал дольше, чем время жизни объекта дескриптора.296297#### `[winreg.PyHKEY.__enter__]PyHKEY.__enter__()`298299#### `PyHKEY.__exit__(*exc_info)`300301Объект HKEY реализует [`__enter__()`](https://python-all.ru/3.0/library/winreg.html#winreg.PyHKEY.__enter__) и [`__exit__()`](https://python-all.ru/3.0/library/winreg.html#winreg.PyHKEY.__exit__) и, таким образом, поддерживает протокол контекстного менеджера для оператора [`with`](https://python-all.ru/3.0/reference/compound_stmts.html#with):302303```python304with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:305    # ... работа с разделом ...306```307308автоматически закроет *key*, когда управление покинет блок [`with`](https://python-all.ru/3.0/reference/compound_stmts.html#with).309