`importlib.resources.md`

146 строк · 13.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.11/library/importlib.resources.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`importlib.resources`](https://python-all.ru/3.11/library/importlib.resources.html#module-importlib.resources) – чтение, открытие и доступ к ресурсам пакетов89**Исходный код:** [Lib/importlib/resources/\_\_init\_\_.py](https://python-all.ru/src/3.11/Lib/importlib/resources/__init__.py)1011---1213Добавлено в версии 3.7.1415Этот модуль использует систему импорта Python для предоставления доступа к *ресурсам* внутри *пакетов*. Если пакет можно импортировать, то можно получить доступ к ресурсам внутри этого пакета. Ресурсы можно открывать или читать в двоичном или текстовом режиме.1617Ресурсы примерно аналогичны файлам в каталогах, хотя важно помнить, что это всего лишь метафора. Ресурсы и пакеты **не** обязаны существовать в виде физических файлов и каталогов в файловой системе: например, пакет и его ресурсы могут быть импортированы из zip-файла с помощью [`zipimport`](https://python-all.ru/3.11/library/zipimport.html#module-zipimport).1819> **Примечание**20>21> Этот модуль предоставляет функциональность, аналогичную [pkg\_resources](https://python-all.ru/3.11/library/importlib.resources.html) [Базовый доступ к ресурсам](https://python-all.ru/3.11/library/importlib.resources.html) без накладных расходов на производительность, присущих тому пакету. Это упрощает чтение ресурсов, входящих в состав пакетов, обеспечивая более стабильную и последовательную семантику.22>23> Автономный бэкпорт этого модуля предоставляет дополнительную информацию об [использовании importlib.resources](https://python-all.ru/3.11/library/importlib.resources.html) и [миграции с pkg\_resources на importlib.resources](https://python-all.ru/3.11/library/importlib.resources.html).2425[`Loaders`](https://python-all.ru/3.11/library/importlib.html#importlib.abc.Loader), которые хотят поддерживать чтение ресурсов, должны реализовать метод `get_resource_reader(fullname)`, как указано в [`importlib.resources.abc.ResourceReader`](https://python-all.ru/3.11/library/importlib.resources.abc.html#importlib.resources.abc.ResourceReader).2627#### `class importlib.resources.Package`2829Если функция принимает аргумент `Package`, можно передать либо [`module object`](https://python-all.ru/3.11/library/types.html#types.ModuleType), либо имя модуля в виде строки. Можно передавать только объекты модулей, у которых `__spec__.submodule_search_locations` не равно `None`.3031Тип `Package` определён как `Union[str, ModuleType]`.3233#### `importlib.resources.files(package)`3435Возвращает объект [`Traversable`](https://python-all.ru/3.11/library/importlib.resources.abc.html#importlib.resources.abc.Traversable), представляющий контейнер ресурсов для пакета (аналог каталога) и его ресурсы (аналог файлов). Объект Traversable может содержать другие контейнеры (аналог подкаталогов).3637*package* – это либо имя, либо объект модуля, соответствующий требованиям [`Package`](https://python-all.ru/3.11/library/importlib.resources.html#importlib.resources.Package).3839Новое в версии 3.9.4041#### `importlib.resources.as_file(traversable)`4243Принимает объект [`Traversable`](https://python-all.ru/3.11/library/importlib.resources.abc.html#importlib.resources.abc.Traversable), представляющий файл (обычно из [`importlib.resources.files()`](https://python-all.ru/3.11/library/importlib.resources.html#importlib.resources.files)), и возвращает менеджер контекста для использования в операторе [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with). Менеджер контекста предоставляет объект [`pathlib.Path`](https://python-all.ru/3.11/library/pathlib.html#pathlib.Path).4445Выход из менеджера контекста удаляет все временные файлы, созданные при извлечении ресурса, например, из zip-файла.4647Используйте `as_file`, когда методов Traversable (`read_text` и т. д.) недостаточно и требуется реальный файл в файловой системе.4849Новое в версии 3.9.5051## Устаревшие функции5253Старый устаревший набор функций по-прежнему доступен, но запланирован к удалению в одной из будущих версий Python. Основной недостаток этих функций в том, что они не поддерживают каталоги: предполагается, что все ресурсы находятся непосредственно внутри *пакета*.5455#### `importlib.resources.Resource`5657Для аргументов *resource* в функциях ниже можно передать имя ресурса в виде строки или [`path-like object`](https://python-all.ru/3.11/library/os.html#os.PathLike).5859Тип `Resource` определён как `Union[str, os.PathLike]`.6061#### `importlib.resources.open_binary(package, resource)`6263Открывает *ресурс* внутри *пакета* для двоичного чтения.6465*package* – это либо имя, либо объект модуля, соответствующий требованиям `Package`. *resource* – имя ресурса для открытия внутри *package*; он не должен содержать разделителей пути и не может иметь подресурсов (т.е. не может быть каталогом). Эта функция возвращает экземпляр `typing.BinaryIO` – двоичный поток I/O, открытый для чтения.6667Устарело с версии 3.11: Вызовы этой функции можно заменить на:6869```python70files(package).joinpath(resource).open('rb')71```7273#### `importlib.resources.open_text(package, resource, encoding='utf-8', errors='strict')`7475Открывает *ресурс* внутри *пакета* для текстового чтения. По умолчанию ресурс открывается для чтения в кодировке UTF-8.7677*package* – это либо имя, либо объект модуля, соответствующий требованиям `Package`. *resource* – имя ресурса для открытия внутри *package*; он не должен содержать разделителей пути и не может иметь подресурсов (т.е. не может быть каталогом). *encoding* и *errors* имеют то же значение, что и во встроенной [`open()`](https://python-all.ru/3.11/library/functions.html#open).7879Эта функция возвращает экземпляр `typing.TextIO` – текстовый поток I/O, открытый для чтения.8081Устарело с версии 3.11: Вызовы этой функции можно заменить на:8283```python84files(package).joinpath(resource).open('r', encoding=encoding)85```8687#### `importlib.resources.read_binary(package, resource)`8889Читает и возвращает содержимое *ресурса* внутри *пакета* в виде `bytes`.9091*package* – это либо имя, либо объект модуля, соответствующий требованиям `Package`. *resource* – имя ресурса для открытия внутри *package*; он не должен содержать разделителей пути и не может иметь подресурсов (т.е. не может быть каталогом). Эта функция возвращает содержимое ресурса в виде [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes).9293Устарело с версии 3.11: Вызовы этой функции можно заменить на:9495```python96files(package).joinpath(resource).read_bytes()97```9899#### `importlib.resources.read_text(package, resource, encoding='utf-8', errors='strict')`100101Читает и возвращает содержимое *ресурса* внутри *пакета* в виде `str`. По умолчанию содержимое читается как строгий UTF-8.102103*package* – это либо имя, либо объект модуля, соответствующий требованиям `Package`. *resource* – имя ресурса для открытия внутри *package*; он не должен содержать разделителей пути и не может иметь подресурсов (т.е. не может быть каталогом). *encoding* и *errors* имеют то же значение, что и во встроенной [`open()`](https://python-all.ru/3.11/library/functions.html#open). Эта функция возвращает содержимое ресурса в виде [`str`](https://python-all.ru/3.11/library/stdtypes.html#str).104105Устарело с версии 3.11: Вызовы этой функции можно заменить на:106107```python108files(package).joinpath(resource).read_text(encoding=encoding)109```110111#### `importlib.resources.path(package, resource)`112113Возвращает путь к *ресурсу* в виде реального пути файловой системы. Эта функция возвращает менеджер контекста для использования в операторе [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with). Менеджер контекста предоставляет объект [`pathlib.Path`](https://python-all.ru/3.11/library/pathlib.html#pathlib.Path).114115При выходе из менеджера контекста удаляются все временные файлы, созданные при извлечении ресурса, например, из zip-файла.116117*package* – это либо имя, либо объект модуля, соответствующий требованиям `Package`. *resource* – имя ресурса для открытия внутри *package*; он не должен содержать разделителей пути и не может иметь подресурсов (т.е. не может быть каталогом).118119Устарело с версии 3.11: Вызовы этой функции можно заменить с помощью [`as_file()`](https://python-all.ru/3.11/library/importlib.resources.html#importlib.resources.as_file):120121```python122as_file(files(package).joinpath(resource))123```124125#### `importlib.resources.is_resource(package, name)`126127Возвращает `True`, если в пакете существует ресурс с именем *name*, иначе `False`. Эта функция не считает каталоги ресурсами. *package* – это либо имя, либо объект модуля, соответствующий требованиям `Package`.128129Устарело с версии 3.11: Вызовы этой функции можно заменить на:130131```python132files(package).joinpath(resource).is_file()133```134135#### `importlib.resources.contents(package)`136137Возвращает итератор по именованным элементам внутри пакета. Итератор возвращает [`str`](https://python-all.ru/3.11/library/stdtypes.html#str) ресурсы (например, файлы) и не-ресурсы (например, каталоги). Итератор не заходит в подкаталоги.138139*package* – это либо имя, либо объект модуля, соответствующий требованиям `Package`.140141Устарело с версии 3.11: Вызовы этой функции можно заменить на:142143```python144(resource.name for resource in files(package).iterdir() if resource.is_file())145```146