API Reference

importlib_resources module

Read resources contained within a package.

This codebase is shared between importlib.resources in the stdlib and importlib_resources in PyPI. See https://github.com/python/importlib_metadata/wiki/Development-Methodology for more detail.

class importlib_resources.ResourceReader

Bases: object

Abstract base class for loaders to provide resource reading support.

abstractmethod contents() → Iterable[str]

Return an iterable of entries in package.

abstractmethod is_resource(path: str) → bool

Return True if the named ‘path’ is a resource.

Files are resources, directories are not.

abstractmethod open_resource(resource: str) → BinaryIO

Return an opened, file-like object for binary reading.

The ‘resource’ argument is expected to represent only a file name. If the resource cannot be found, FileNotFoundError is raised.

abstractmethod resource_path(resource: str) → str

Return the file system path to the specified resource.

The ‘resource’ argument is expected to represent only a file name. If the resource does not exist on the file system, raise FileNotFoundError.

importlib_resources.as_file(path)

importlib_resources.as_file(path: Path)

Given a Traversable object, return that object as a path on the local file system in a context manager.

importlib_resources.contents(anchor, *path_names)

Return an iterable over the named resources within the package.

The iterable returns str resources (e.g. files). The iterable does not recurse into subdirectories.

importlib_resources.files(anchor: ModuleType | str | None = None) → Traversable

Get a Traversable resource for an anchor.

importlib_resources.is_resource(anchor, *path_names)

Return True if there is a resource named name in the package,

Otherwise returns False.

importlib_resources.open_binary(anchor, *path_names)

Open for binary reading the resource within package.

importlib_resources.open_text(anchor, *path_names, encoding=_MISSING, errors='strict')

Open for text reading the resource within package.

importlib_resources.path(anchor, *path_names)

Return the path to the resource as an actual file system path.

importlib_resources.read_binary(anchor, *path_names)

Read and return contents of resource within package as bytes.

importlib_resources.read_text(anchor, *path_names, encoding=_MISSING, errors='strict')

Read and return contents of resource within package as str.

class importlib_resources.abc.ResourceReader

Bases: object

Abstract base class for loaders to provide resource reading support.

abstractmethod contents() → Iterable[str]

Return an iterable of entries in package.

abstractmethod is_resource(path: str) → bool

Return True if the named ‘path’ is a resource.

Files are resources, directories are not.

abstractmethod open_resource(resource: str) → BinaryIO

Return an opened, file-like object for binary reading.

The ‘resource’ argument is expected to represent only a file name. If the resource cannot be found, FileNotFoundError is raised.

abstractmethod resource_path(resource: str) → str

Return the file system path to the specified resource.

The ‘resource’ argument is expected to represent only a file name. If the resource does not exist on the file system, raise FileNotFoundError.

class importlib_resources.abc.Traversable(*args, **kwargs)

Bases: Protocol

An object with a subset of pathlib.Path methods suitable for traversing directories and opening files.

Any exceptions that occur when accessing the backing resource may propagate unaltered.

abstractmethod is_dir() → bool

Return True if self is a directory

abstractmethod is_file() → bool

Return True if self is a file

abstractmethod iterdir() → Iterator[Traversable]

Yield Traversable objects in self

joinpath(*descendants: str | PathLike[str]) → Traversable

Return Traversable resolved with any descendants applied.

Each descendant should be a path segment relative to self and each may contain multiple levels separated by posixpath.sep (/).

abstract property name: str

The base name of this object without any parent references.

abstractmethod open(mode: Literal['r'] = 'r', *args: Any, **kwargs: Any) → TextIO

abstractmethod open(mode: Literal['rb'], *args: Any, **kwargs: Any) → BinaryIO

mode may be ‘r’ or ‘rb’ to open as text or binary. Return a handle suitable for reading (same as pathlib.Path.open).

When opening as text, accepts encoding parameters such as those accepted by io.TextIOWrapper.

read_bytes() → bytes

Read contents of self as bytes

read_text(encoding: str | None = None, errors: str | None = None) → str

Read contents of self as text

class importlib_resources.abc.TraversableResources

Bases: ResourceReader

The required interface for providing traversable resources.

contents() → Iterator[str]

Return an iterable of entries in package.

abstractmethod files() → Traversable

Return a Traversable object for the loaded package.

is_resource(path: str | PathLike[str]) → bool

Return True if the named ‘path’ is a resource.

Files are resources, directories are not.

open_resource(resource: str | PathLike[str]) → BinaryIO

Return an opened, file-like object for binary reading.

The ‘resource’ argument is expected to represent only a file name. If the resource cannot be found, FileNotFoundError is raised.

resource_path(resource: Any) → NoReturn

Return the file system path to the specified resource.

The ‘resource’ argument is expected to represent only a file name. If the resource does not exist on the file system, raise FileNotFoundError.

class importlib_resources.readers.FileReader(loader)

Bases: TraversableResources

files()

Return a Traversable object for the loaded package.

resource_path(resource)

Return the file system path to prevent resources.path() from creating a temporary copy.

class importlib_resources.readers.MultiplexedPath(*paths)

Bases: Traversable

Given a series of Traversable objects, implement a merged version of the interface across all objects. Useful for namespace packages which may be multihomed at a single name.

is_dir()

Return True if self is a directory

is_file()

Return True if self is a file

iterdir()

Yield Traversable objects in self

joinpath(*descendants)

Return Traversable resolved with any descendants applied.

Each descendant should be a path segment relative to self and each may contain multiple levels separated by posixpath.sep (/).

property name

The base name of this object without any parent references.

open(*args, **kwargs)

mode may be ‘r’ or ‘rb’ to open as text or binary. Return a handle suitable for reading (same as pathlib.Path.open).

When opening as text, accepts encoding parameters such as those accepted by io.TextIOWrapper.

read_bytes()

Read contents of self as bytes

read_text(*args, **kwargs)

Read contents of self as text

class importlib_resources.readers.NamespaceReader(namespace_path)

Bases: TraversableResources

files()

Return a Traversable object for the loaded package.

resource_path(resource)

Return the file system path to prevent resources.path() from creating a temporary copy.

class importlib_resources.readers.ZipReader(loader, module)

Bases: TraversableResources

files()

Return a Traversable object for the loaded package.

is_resource(path)

Workaround for zipfile.Path.is_file returning true for non-existent paths.

open_resource(resource)

Return an opened, file-like object for binary reading.

The ‘resource’ argument is expected to represent only a file name. If the resource cannot be found, FileNotFoundError is raised.

importlib_resources.readers.remove_duplicates(items)

Interface adapters for low-level readers.

class importlib_resources.simple.ResourceContainer(reader: SimpleReader)

Bases: Traversable

Traversable container for a package’s resources via its reader.

is_dir()

Return True if self is a directory

is_file()

Return True if self is a file

iterdir()

Yield Traversable objects in self

open(*args, **kwargs)

mode may be ‘r’ or ‘rb’ to open as text or binary. Return a handle suitable for reading (same as pathlib.Path.open).

When opening as text, accepts encoding parameters such as those accepted by io.TextIOWrapper.

class importlib_resources.simple.ResourceHandle(parent: ResourceContainer, name: str)

Bases: Traversable

Handle to a named resource in a ResourceReader.

is_dir()

Return True if self is a directory

is_file()

Return True if self is a file

joinpath(name)

Return Traversable resolved with any descendants applied.

Each descendant should be a path segment relative to self and each may contain multiple levels separated by posixpath.sep (/).

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

mode may be ‘r’ or ‘rb’ to open as text or binary. Return a handle suitable for reading (same as pathlib.Path.open).

When opening as text, accepts encoding parameters such as those accepted by io.TextIOWrapper.

class importlib_resources.simple.SimpleReader

Bases: ABC

The minimum, low-level interface required from a resource provider.

abstractmethod children() → List[SimpleReader]

Obtain an iterable of SimpleReader for available child containers (e.g. directories).

property name

abstractmethod open_binary(resource: str) → BinaryIO

Obtain a File-like for a named resource.

abstract property package: str

The name of the package for which this reader loads resources.

abstractmethod resources() → List[str]

Obtain available named resources for this virtual package.

class importlib_resources.simple.TraversableReader

Bases: TraversableResources, SimpleReader

A TraversableResources based on SimpleReader. Resource providers may derive from this class to provide the TraversableResources interface by supplying the SimpleReader interface.

files()

Return a Traversable object for the loaded package.