nireports.assembler.data package

Nireports assembler data files

nireports.assembler.data.load(*segments) → Path

Load package files relative to nireports.assembler.data.

This package contains the following (top-level) files/directories:

• default.yml

• nipreps.json

• rating-widget/

• report.tpl

load.readable(*segments) → 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.

load.as_path(*segments) → 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.

load.cached(*segments) → Path

Ensure data 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 the cache is sensitive to the specific argument(s) passed.

class nireports.assembler.data.Loader(anchor: str | ModuleType)

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 nireports.assembler.data import Loader

load_data = Loader(__package__)

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 nireports.assembler.data 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)

readable(*segments) → 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.

as_path(*segments) → 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) → Path

Ensure data 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 the cache is sensitive to the specific argument(s) passed.