importlib.resources.abc – Абстрактные базовые классы для ресурсов

Исходный код: Lib/importlib/resources/abc.py

class importlib.resources.abc.ResourceReader

Заменена классом TraversableResources

Абстрактный базовый класс для работы с ресурсами.

С точки зрения этого абстрактного базового класса, ресурс — это двоичный артефакт, поставляемый вместе с пакетом. Обычно это такой файл данных, который находится рядом с файлом __init__.py пакета. Цель этого класса — абстрагировать доступ к таким файлам данных, чтобы неважно было, хранятся ли пакет и его файлы данных, например, в файле zip или на файловой системе.

Для любого метода этого класса ожидается, что аргумент resource будет объектом, подобным пути, который концептуально представляет просто имя файла. Это означает, что пути к подкаталогам в аргументе resource включать не следует. Это потому, что расположение пакета, для которого предназначен читатель, выступает в роли «каталога». Отсюда метафора: пакеты — каталоги, ресурсы — имена файлов. Это также объясняет, почему экземпляры этого класса ожидается, что они напрямую соответствуют конкретному пакету (вместо потенциального представления нескольких пакетов или модуля).

Загрузчики, которые хотят поддерживать чтение ресурсов, должны предоставить метод get_resource_reader(fullname), который возвращает объект, реализующий интерфейс этого абстрактного базового класса. Если модуль, указанный параметром fullname, не является пакетом, этот метод должен возвращать None. Объект, совместимый с этим абстрактным базовым классом, должен возвращаться только тогда, когда указанный модуль является пакетом.

Устарело начиная с версии 3.12, будет удалено в версии 3.14: Используйте importlib.resources.abc.TraversableResources вместо этого.

abstractmethod open_resource(resource)

Возвращает открытый объект, подобный файлу для двоичного чтения ресурса.

Если ресурс не найден, возникает исключение FileNotFoundError.

abstractmethod resource_path(resource)

Возвращает путь к ресурсу в файловой системе.

Если ресурс конкретно не существует в файловой системе, возникает исключение FileNotFoundError.

abstractmethod is_resource(name)

Возвращает True, если указанное имя name считается ресурсом. Если name не существует, возникает исключение FileNotFoundError.

abstractmethod contents()

Возвращает итерируемый объект строк с содержимым пакета. Обратите внимание, что не требуется, чтобы все имена, возвращаемые итератором, были фактическими ресурсами, например, допустимо возвращать имена, для которых is_resource() будет ложным.

Разрешение возвращать не-ресурсные имена позволяет ситуациями, когда способ хранения пакета и его ресурсов известен заранее, и не-ресурсные имена могут быть полезны. Например, допускается возвращать имена подкаталогов, чтобы, если известно, что пакет и ресурсы хранятся в файловой системе, эти имена подкаталогов можно было использовать напрямую.

Абстрактный метод возвращает итерируемый объект без элементов.

class importlib.resources.abc.Traversable

Объект с подмножеством методов pathlib.Path, подходящих для обхода каталогов и открытия файлов.

Для представления объекта в файловой системе используйте importlib.resources.as_file().

name

Абстрактное. Базовое имя этого объекта без ссылок на родительские элементы.

abstractmethod iterdir()

Возвращает итерируемый объект Traversable-объектов в self.

abstractmethod is_dir()

Возвращает True, если self является каталогом.

abstractmethod is_file()

Возвращает True, если self является файлом.

abstractmethod joinpath(*pathsegments)

Обходит каталоги по pathsegments и возвращает результат как Traversable.

Каждый аргумент pathsegments может содержать несколько имён, разделённых косыми чертами (/, posixpath.sep). Например, следующие варианты эквивалентны:

files.joinpath('subdir', 'subsuddir', 'file.txt')
files.joinpath('subdir/subsuddir/file.txt')

Обратите внимание, что некоторые реализации Traversable могут быть не обновлены до последней версии протокола. Для совместимости с такими реализациями передавайте в каждый вызов joinpath один аргумент без разделителей путей. Например:

files.joinpath('subdir').joinpath('subsubdir').joinpath('file.txt')

Изменено в версии 3.11: joinpath принимает несколько аргументов pathsegments, и эти сегменты могут содержать косые черты в качестве разделителей путей. Ранее принимался только один аргумент child.

abstractmethod __truediv__(child)

Возвращает дочерний элемент Traversable в self. Эквивалентно joinpath(child).

abstractmethod open(mode='r', *args, **kwargs)

mode может быть ‘r’ или ‘rb’ для открытия как текстового или двоичного файла. Возвращает обработчик, подходящий для чтения (аналогично pathlib.Path.open).

При открытии в текстовом формате принимаются параметры кодировки, такие как те, которые принимает io.TextIOWrapper.

read_bytes()

Считывает содержимое self в виде байтов.

read_text(encoding=None)

Считывает содержимое self в виде текста.

class importlib.resources.abc.TraversableResources

Абстрактный базовый класс для читателей ресурсов, способных обслуживать интерфейс importlib.resources.files(). Подклассы ResourceReader и предоставляют конкретные реализации абстрактных методов ResourceReader. Поэтому любой загрузчик, предоставляющий TraversableResources, также предоставляет ResourceReader.

Загрузчики, которые хотят поддерживать чтение ресурсов, должны реализовать этот интерфейс.

abstractmethod files()

Возвращает importlib.resources.abc.Traversable-объект для загруженного пакета.