sdcflows.data package¶

SDCFlows data files

sdcflows.data.load(*segments: str) → Path¶

Load package files relative to sdcflows.data.

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

affine.json
flirtsch/
fmap-any_registration.json
fmap-any_registration_testing.json
fmap_atlas.nii.gz
fmap_atlas_2_MNI152NLin2009cAsym_affine.mat
sd_syn.json
sd_syn_sloppy.json
translation_rigid.json

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

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

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

class sdcflows.data.Loader(anchor: str | ModuleType)[source]¶

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)

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)

readable(*segments: str) → Traversable[source]¶