API Reference

importlib_resources module

Read resources contained within a package.

importlib_resources.Resource

alias of str

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: pathlib.Path)

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

importlib_resources.contents(package: Union[module, str]) → Iterable[str]

Return an iterable of entries in package.

Note that not all entries are resources. Specifically, directories are not considered resources. Use is_resource() on each entry returned here to check if it is a resource or not.

importlib_resources.files(package: Union[module, str]) → importlib_resources.abc.Traversable

Get a Traversable resource from a package

importlib_resources.is_resource(package: Union[module, str], name: str) → bool

True if name is a resource inside package.

Directories are not resources.

importlib_resources.open_binary(package: Union[module, str], resource: str) → BinaryIO

Return a file-like object opened for binary reading of the resource.

importlib_resources.open_text(package: Union[module, str], resource: str, encoding: str = 'utf-8', errors: str = 'strict') → TextIO

Return a file-like object opened for text reading of the resource.

importlib_resources.path(package: Union[module, str], resource: str) → ContextManager[pathlib.Path]

A context manager providing a file path object to the resource.

If the resource does not already exist on its own on the file system, a temporary file will be created. If the file was created, the file will be deleted upon exiting the context manager (no exception is raised if the file was deleted prior to the context manager exiting).

importlib_resources.read_binary(package: Union[module, str], resource: str) → bytes

Return the binary contents of the resource.

importlib_resources.read_text(package: Union[module, str], resource: str, encoding: str = 'utf-8', errors: str = 'strict') → str

Return the decoded string of the resource.

The decoding-related arguments have the same semantics as those of bytes.decode().

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.

abstract is_dir() → bool

Return True if self is a directory

abstract is_file() → bool

Return True if self is a file

abstract iterdir()

Yield Traversable objects in self

abstract joinpath(child)

Return Traversable child in self

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()

Read contents of self as bytes

read_text(encoding=None)

Read contents of self as text

class importlib_resources.abc.TraversableResources

Bases: importlib_resources.abc.ResourceReader

The required interface for providing traversable resources.

contents()

Return an iterable of entries in package.

abstract files()

Return a Traversable object for the loaded package.

is_resource(path)

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

Files are resources, directories are not.

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.

resource_path(resource)

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: importlib_resources.abc.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: importlib_resources.abc.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(child)

Return Traversable child in self

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: importlib_resources.abc.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: importlib_resources.abc.TraversableResources

files()

Return a Traversable object for the loaded package.

is_resource(path)

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

Files are resources, directories are not.

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: importlib_resources.simple.SimpleReader)

Bases: importlib_resources.abc.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

joinpath(name)

Return Traversable child 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: importlib_resources.simple.ResourceContainer, name: str)

Bases: importlib_resources.abc.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 child in self

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

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

abstract children() → List[importlib_resources.simple.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

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: importlib_resources.abc.TraversableResources, importlib_resources.simple.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.