acres package¶

Data loading utility for Python packages.

This module provides a class that wraps importlib.resources to provide resource retrieval functions with commonly-needed scoping, including interpreter-lifetime caching.

class acres.Loader(anchor: str | ModuleType, *, list_contents: bool = False)¶

Bases: object

A loader for package files relative to a module

This class wraps importlib.resources to provide a getter function with an interpreter-lifetime scope. For typical packages it simply passes through filesystem paths as Path objects. For zipped distributions, it will unpack the files into a temporary directory that is cleaned up on interpreter exit.

This loader accepts a fully-qualified module name or a module object.

Expected usage:

'''Data package

.. autofunction:: load_data

.. automethod:: load_data.readable

.. automethod:: load_data.as_path

.. automethod:: load_data.cached
'''

from acres import Loader

load_data = Loader(__spec__.name, list_contents=True)

Loader objects implement the callable() interface and generate a docstring, and are intended to be treated and documented as functions.

For greater flexibility and improved readability over the importlib.resources interface, explicit methods are provided to access resources.

On-filesystem	Lifetime	Method
True	Interpreter	`cached()`
True	with context	`as_path()`
False	n/a	`readable()`

It is also possible to use Loader directly:

from acres import Loader

Loader(other_package).readable('data/resource.ext').read_text()

with Loader(other_package).as_path('data') as pkgdata:
    # Call function that requires full Path implementation
    func(pkgdata)

# contrast to

from importlib_resources import files, as_file

files(other_package).joinpath('data/resource.ext').read_text()

with as_file(files(other_package) / 'data') as pkgdata:
    func(pkgdata)

When creating a Loader as a module attribute, it is frequently useful for the docstring to list the contents of the package. There is a slight cost to updating the docstring, so this is disabled by default, for better performance in short-lived Loader instances.

as_path(*segments: str) → AbstractContextManager[Path]¶

Ensure data is available as a Path.

This method generates a context manager that yields a Path when entered.

This result is not cached, and any temporary files that are created are deleted when the context is exited.

cached(*segments: str) → Path¶

Ensure data resource is available as a Path.

Any temporary files that are created remain available throughout the duration of the program, and are deleted when Python exits.

Results are cached so that multiple calls do not unpack the same data multiple times, but directories and their contents being requested separately may result in some duplication.

readable(*segments: str) → Traversable¶

Provide read access to a resource through a Path-like interface.

This file may or may not exist on the filesystem, and may be efficiently used for read operations, including directory traversal.

This result is not cached or copied to the filesystem in cases where that would be necessary.

Submodules¶

acres.typ module¶

Typing symbols for the acres package.

This module aims to make the types used by the acres package available for type checking without requiring the original packages to be imported at runtime.

The expected usage is:

import acres.typ as at

def resource_using_function(resource: at.Traversable) -> ReturnType:
    ...

To get the runtime benefits of using this module, you should not import anything from it, but import the module and access symbols as attributes. For Python versions less than 3.14, from __future__ import annotations must be used to avoid eager loading of the types.

The primary use for this in downstream tools is the Traversable type, which will be imported from importlib.resources.abc or importlib.abc, based on the Python version. However, other types that are not directly used in acres are also available.

acres.typ.Traversable¶: alias of importlib.resources.abc.Traversable

acres.typ.AbstractContextManager¶: alias of contextlib.AbstractContextManager

acres.typ.Path¶: alias of pathlib.Path

acres.typ.ModuleType¶: alias of types.ModuleType