`importlib.resources.md`

158 строк · 15.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.12/library/importlib.resources.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `importlib.resources` – чтение, открытие и доступ к ресурсам пакетов89**Исходный код:** [Lib/importlib/resources/\_\_init\_\_.py](https://python-all.ru/src/3.12/Lib/importlib/resources/__init__.py)1011---1213Добавлено в версии 3.7.1415Этот модуль использует систему импорта Python для обеспечения доступа к *ресурсам* внутри *пакетов*.1617«Ресурсы» – это файлоподобные ресурсы, связанные с модулем или пакетом в Python. Ресурсы могут находиться непосредственно в пакете, в подкаталоге внутри этого пакета или рядом с модулями вне пакета. Ресурсы могут быть текстовыми или двоичными. Как следствие, исходные файлы модулей Python (.py) пакета и артефакты компиляции (pycache) технически являются де-факто ресурсами этого пакета. Однако на практике ресурсами считаются в первую очередь те не-Python артефакты, которые явно предоставляются автором пакета.1819Ресурсы можно открывать или читать как в двоичном, так и в текстовом режиме.2021Ресурсы примерно аналогичны файлам в каталогах, хотя важно помнить, что это всего лишь метафора. Ресурсы и пакеты **не** обязаны существовать в виде физических файлов и каталогов в файловой системе: например, пакет и его ресурсы могут быть импортированы из zip-файла с помощью [`zipimport`](https://python-all.ru/3.12/library/zipimport.html#module-zipimport).2223> **Примечание**24>25> Этот модуль предоставляет функциональность, аналогичную [pkg\_resources](https://python-all.ru/3.12/library/importlib.resources.html) [Базовый доступ к ресурсам](https://python-all.ru/3.12/library/importlib.resources.html) без накладных расходов на производительность, присущих тому пакету. Это упрощает чтение ресурсов, входящих в состав пакетов, обеспечивая более стабильную и последовательную семантику.26>27> Автономный бэкпорт этого модуля предоставляет дополнительную информацию об [использовании importlib.resources](https://python-all.ru/3.12/library/importlib.resources.html) и [миграции с pkg\_resources на importlib.resources](https://python-all.ru/3.12/library/importlib.resources.html).2829[`Loaders`](https://python-all.ru/3.12/library/importlib.html#importlib.abc.Loader), которые хотят поддерживать чтение ресурсов, должны реализовать метод `get_resource_reader(fullname)`, как указано в [`importlib.resources.abc.ResourceReader`](https://python-all.ru/3.12/library/importlib.resources.abc.html#importlib.resources.abc.ResourceReader).3031#### `class importlib.resources.Anchor`3233Представляет привязку (anchor) для ресурсов: либо [`module object`](https://python-all.ru/3.12/library/types.html#types.ModuleType), либо имя модуля в виде строки. Определяется как `Union[str, ModuleType]`.3435#### `importlib.resources.files(anchor: Anchor | None = None)`3637Возвращает объект [`Traversable`](https://python-all.ru/3.12/library/importlib.resources.abc.html#importlib.resources.abc.Traversable), представляющий контейнер ресурсов (по аналогии с каталогом) и его ресурсы (по аналогии с файлами). Traversable может содержать другие контейнеры (по аналогии с подкаталогами).3839*anchor* – это необязательный [`Anchor`](https://python-all.ru/3.12/library/importlib.resources.html#importlib.resources.Anchor). Если anchor является пакетом, ресурсы разрешаются относительно этого пакета. Если модулем, ресурсы разрешаются рядом с этим модулем (в том же пакете или корне пакета). Если anchor опущен, используется модуль вызывающего.4041Добавлено в версии 3.9.4243Изменено в версии 3.12: Параметр *package* был переименован в *anchor*. *anchor* теперь может быть модулем, не являющимся пакетом, и если он опущен, по умолчанию используется модуль вызывающего. *package* по-прежнему принимается для совместимости, но вызовет [`DeprecationWarning`](https://python-all.ru/3.12/library/exceptions.html#DeprecationWarning). Рассмотрите возможность передачи anchor по позиции или использования `importlib_resources >= 5.10` для совместимого интерфейса на старых версиях Python.4445#### `importlib.resources.as_file(traversable)`4647Получив объект [`Traversable`](https://python-all.ru/3.12/library/importlib.resources.abc.html#importlib.resources.abc.Traversable), представляющий файл или каталог, обычно из [`importlib.resources.files()`](https://python-all.ru/3.12/library/importlib.resources.html#importlib.resources.files), возвращает менеджер контекста для использования в операторе [`with`](https://python-all.ru/3.12/reference/compound_stmts.html#with). Менеджер контекста предоставляет объект [`pathlib.Path`](https://python-all.ru/3.12/library/pathlib.html#pathlib.Path).4849Выход из менеджера контекста удаляет любые временные файлы или каталоги, созданные при извлечении ресурса, например, из zip-файла.5051Используйте `as_file`, когда методов Traversable (`read_text` и т.д.) недостаточно и требуется реальный файл или каталог в файловой системе.5253Добавлено в версии 3.9.5455Изменено в версии 3.12: Добавлена поддержка *traversable*, представляющего каталог.5657## Функциональное API5859Набор функций, ранее объявленных устаревшими, по-прежнему доступен. Их главный недостаток – отсутствие поддержки каталогов: они предполагают, что все ресурсы находятся непосредственно внутри *пакета*.6061#### `importlib.resources.Package`6263Если функция принимает аргумент `Package`, можно передать либо [`module object`](https://python-all.ru/3.12/library/types.html#types.ModuleType), либо имя модуля в виде строки. Можно передавать только объекты модулей, у которых `__spec__.submodule_search_locations` не равно `None`.6465Тип `Package` определён как `Union[str, ModuleType]`.6667#### `importlib.resources.Resource`6869Для аргументов *resource* в функциях ниже можно передать имя ресурса в виде строки или [`path-like object`](https://python-all.ru/3.12/library/os.html#os.PathLike).7071Тип `Resource` определён как `Union[str, os.PathLike]`.7273#### `importlib.resources.open_binary(package, resource)`7475Открывает *ресурс* внутри *пакета* для двоичного чтения.7677*package* – это либо имя, либо объект модуля, соответствующий требованиям `Package`. *resource* – имя ресурса для открытия внутри *package*; он не должен содержать разделителей пути и не может иметь подресурсов (т.е. не может быть каталогом). Эта функция возвращает экземпляр `typing.BinaryIO` – двоичный поток I/O, открытый для чтения.7879This function is roughly equivalent to:8081```python82files(package).joinpath(resource).open('rb')83```8485#### `importlib.resources.open_text(package, resource, encoding='utf-8', errors='strict')`8687Открывает *ресурс* внутри *пакета* для текстового чтения. По умолчанию ресурс открывается для чтения в кодировке UTF-8.8889*package* – это либо имя, либо объект модуля, соответствующий требованиям `Package`. *resource* – имя ресурса для открытия внутри *package*; он не должен содержать разделителей пути и не может иметь подресурсов (т.е. не может быть каталогом). *encoding* и *errors* имеют то же значение, что и во встроенной [`open()`](https://python-all.ru/3.12/library/functions.html#open).9091Эта функция возвращает экземпляр `typing.TextIO` – текстовый поток I/O, открытый для чтения.9293This function is roughly equivalent to:9495```python96files(package).joinpath(resource).open('r', encoding=encoding)97```9899#### `importlib.resources.read_binary(package, resource)`100101Читает и возвращает содержимое *ресурса* внутри *пакета* в виде `bytes`.102103*package* – это либо имя, либо объект модуля, соответствующий требованиям `Package`. *resource* – имя ресурса для открытия внутри *package*; он не должен содержать разделителей пути и не может иметь подресурсов (т.е. не может быть каталогом). Эта функция возвращает содержимое ресурса в виде [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes).104105This function is roughly equivalent to:106107```python108files(package).joinpath(resource).read_bytes()109```110111#### `importlib.resources.read_text(package, resource, encoding='utf-8', errors='strict')`112113Читает и возвращает содержимое *ресурса* внутри *пакета* в виде `str`. По умолчанию содержимое читается как строгий UTF-8.114115*package* – это либо имя, либо объект модуля, соответствующий требованиям `Package`. *resource* – имя ресурса для открытия внутри *package*; он не должен содержать разделителей пути и не может иметь подресурсов (т.е. не может быть каталогом). *encoding* и *errors* имеют то же значение, что и во встроенной [`open()`](https://python-all.ru/3.12/library/functions.html#open). Эта функция возвращает содержимое ресурса в виде [`str`](https://python-all.ru/3.12/library/stdtypes.html#str).116117This function is roughly equivalent to:118119```python120files(package).joinpath(resource).read_text(encoding=encoding)121```122123#### `importlib.resources.path(package, resource)`124125Возвращает путь к *ресурсу* в виде реального пути файловой системы. Эта функция возвращает менеджер контекста для использования в операторе [`with`](https://python-all.ru/3.12/reference/compound_stmts.html#with). Менеджер контекста предоставляет объект [`pathlib.Path`](https://python-all.ru/3.12/library/pathlib.html#pathlib.Path).126127При выходе из менеджера контекста удаляются все временные файлы, созданные при извлечении ресурса, например, из zip-файла.128129*package* – это либо имя, либо объект модуля, соответствующий требованиям `Package`. *resource* – имя ресурса для открытия внутри *package*; он не должен содержать разделителей пути и не может иметь подресурсов (т.е. не может быть каталогом).130131Эта функция примерно эквивалентна132133```python134as_file(files(package).joinpath(resource))135```136137#### `importlib.resources.is_resource(package, name)`138139Возвращает `True`, если в пакете существует ресурс с именем *name*, иначе `False`. Эта функция не считает каталоги ресурсами. *package* – это либо имя, либо объект модуля, соответствующий требованиям `Package`.140141This function is roughly equivalent to:142143```python144files(package).joinpath(resource).is_file()145```146147#### `importlib.resources.contents(package)`148149Возвращает итератор по именованным элементам внутри пакета. Итератор возвращает [`str`](https://python-all.ru/3.12/library/stdtypes.html#str) ресурсы (например, файлы) и не-ресурсы (например, каталоги). Итератор не заходит в подкаталоги.150151*package* – это либо имя, либо объект модуля, соответствующий требованиям `Package`.152153This function is roughly equivalent to:154155```python156(resource.name for resource in files(package).iterdir() if resource.is_file())157```158