importlib.resources – Package resource reading, opening and access

Source code:Lib/importlib/resources/__init__.py

New in version 3.7.

This module leverages Python’s import system to provide access toresourceswithinpackages. If you can import a package, you can access resourceswithin that package. Resources can be opened or read, in either binary ortext mode.

Resources are roughly akin to files inside directories, though it’s importantto keep in mind that this is just a metaphor. Resources and packagesdonot have to exist as physical files and directories on the file system:for example, a package and its resources can be imported from a zip file usingzipimport.

Note

This module provides functionality similar topkg_resourcesBasicResource Accesswithout the performance overhead of that package. This makes readingresources included in packages easier, with more stable and consistentsemantics.

The standalone backport of this module provides more informationonusing importlib.resources andmigrating from pkg_resources to importlib.resources.

Loaders that wish to support resource reading should implement aget_resource_reader(fullname) method as specified byimportlib.resources.abc.ResourceReader.

classimportlib.resources.Package

Whenever a function accepts aPackage argument, you can pass ineither amoduleobject or a module nameas a string. You can only pass module objects whose__spec__.submodule_search_locations is notNone.

ThePackage type is defined asUnion[str,ModuleType].

importlib.resources.files(package)

Returns aTraversable objectrepresenting the resource container for the package (think directory)and its resources (think files). A Traversable may contain othercontainers (think subdirectories).

package is either a name or a module object which conforms to thePackage requirements.

New in version 3.9.

importlib.resources.as_file(traversable)

Given aTraversable object representinga file, typically fromimportlib.resources.files(), returna context manager for use in awith statement.The context manager provides apathlib.Path object.

Exiting the context manager cleans up any temporary file created when theresource was extracted from e.g. a zip file.

Useas_file when the Traversable methods(read_text, etc) are insufficient and an actual file onthe file system is required.

New in version 3.9.

Deprecated functions

An older, deprecated set of functions is still available, but isscheduled for removal in a future version of Python.The main drawback of these functions is that they do not supportdirectories: they assume all resources are located directly within apackage.

importlib.resources.Resource

Forresource arguments of the functions below, you can pass inthe name of a resource as a string orapath-likeobject.

TheResource type is defined asUnion[str,os.PathLike].

importlib.resources.open_binary(package,resource)

Open for binary reading theresource withinpackage.

package is either a name or a module object which conforms to thePackage requirements.resource is the name of the resource to openwithinpackage; it may not contain path separators and it may not havesub-resources (i.e. it cannot be a directory). This function returns atyping.BinaryIO instance, a binary I/O stream open for reading.

Deprecated since version 3.11:Calls to this function can be replaced by:

files(package).joinpath(resource).open('rb')
importlib.resources.open_text(package,resource,encoding='utf-8',errors='strict')

Open for text reading theresource withinpackage. By default, theresource is opened for reading as UTF-8.

package is either a name or a module object which conforms to thePackage requirements.resource is the name of the resource to openwithinpackage; it may not contain path separators and it may not havesub-resources (i.e. it cannot be a directory).encoding anderrorshave the same meaning as with built-inopen().

This function returns atyping.TextIO instance, a text I/O stream openfor reading.

Deprecated since version 3.11:Calls to this function can be replaced by:

files(package).joinpath(resource).open('r',encoding=encoding)
importlib.resources.read_binary(package,resource)

Read and return the contents of theresource withinpackage asbytes.

package is either a name or a module object which conforms to thePackage requirements.resource is the name of the resource to openwithinpackage; it may not contain path separators and it may not havesub-resources (i.e. it cannot be a directory). This function returns thecontents of the resource asbytes.

Deprecated since version 3.11:Calls to this function can be replaced by:

files(package).joinpath(resource).read_bytes()
importlib.resources.read_text(package,resource,encoding='utf-8',errors='strict')

Read and return the contents ofresource withinpackage as astr.By default, the contents are read as strict UTF-8.

package is either a name or a module object which conforms to thePackage requirements.resource is the name of the resource to openwithinpackage; it may not contain path separators and it may not havesub-resources (i.e. it cannot be a directory).encoding anderrorshave the same meaning as with built-inopen(). This functionreturns the contents of the resource asstr.

Deprecated since version 3.11:Calls to this function can be replaced by:

files(package).joinpath(resource).read_text(encoding=encoding)
importlib.resources.path(package,resource)

Return the path to theresource as an actual file system path. Thisfunction returns a context manager for use in awith statement.The context manager provides apathlib.Path object.

Exiting the context manager cleans up any temporary file created when theresource needs to be extracted from e.g. a zip file.

package is either a name or a module object which conforms to thePackage requirements.resource is the name of the resource to openwithinpackage; it may not contain path separators and it may not havesub-resources (i.e. it cannot be a directory).

Deprecated since version 3.11:Calls to this function can be replaced usingas_file():

as_file(files(package).joinpath(resource))
importlib.resources.is_resource(package,name)

ReturnTrue if there is a resource namedname in the package,otherwiseFalse.This function does not consider directories to be resources.package is either a name or a module object which conforms to thePackage requirements.

Deprecated since version 3.11:Calls to this function can be replaced by:

files(package).joinpath(resource).is_file()
importlib.resources.contents(package)

Return an iterable over the named items within the package. The iterablereturnsstr resources (e.g. files) and non-resources(e.g. directories). The iterable does not recurse into subdirectories.

package is either a name or a module object which conforms to thePackage requirements.

Deprecated since version 3.11:Calls to this function can be replaced by:

(resource.nameforresourceinfiles(package).iterdir()ifresource.is_file())