API Reference#

`importlib_resources` module#

Read resources contained within a package.

class importlib_resources.ResourceReader#

Bases: object

Abstract base class for loaders to provide resource reading support.

abstract contents() → Iterable[str]#: Return an iterable of entries in package.

abstract is_resource(path: str) → bool#

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

Files are resources, directories are not.

abstract 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.

abstract 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: module | 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.

abstract contents() → Iterable[str]#: Return an iterable of entries in package.

abstract is_resource(path: str) → bool#

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

Files are resources, directories are not.

abstract 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.

abstract 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.

abstract is_dir() → bool#: Return True if self is a directory

abstract is_file() → bool#: Return True if self is a file

abstract 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.

abstract 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.

read_bytes() → bytes#: Read contents of self as bytes

read_text(encoding: 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.

abstract 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]) → BufferedReader#

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.

abstract children() → List[SimpleReader]#: Obtain an iterable of SimpleReader for available child containers (e.g. directories).

property name#

abstract 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.

abstract 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.

API Reference#

importlib_resources module#

`importlib_resources` module#