Home · Quickstart · User Guide and Examples · Interfaces Index · Developers · About · Nipy

# nipype.acres module

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 nipype.acres.Loader(anchor: str | ModuleType)

  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)

  `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

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

  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.