RF: Purge pkg_resources, add data loader

.circleci/config.yml

@@ -1,12 +1,12 @@
 version: 2.1
 orbs:
-  docker: circleci/docker@2.2.0
-  codecov: codecov/codecov@3.2.4
+  docker: circleci/docker@2.4.0
+  codecov: codecov/codecov@3.3.0
 
 jobs:
   test_pytest:
-    docker: # executor type
-      - image: nipreps/miniconda:py39_2209.01
+    docker:
+      - image: cimg/python:3.12
         auth:
           username: $DOCKER_USER
           password: $DOCKER_PAT
@@ -16,14 +16,13 @@ jobs:
       - TEMPLATEFLOW_HOME: /tmp/templateflow
     steps:
       - checkout
+      - run:
+          name: Install package
+          command: pip install .[test]
 
       - restore_cache:
           keys:
-            - tf-v0-{{ .Branch }}-{{ .Revision }}
-            - tf-v0--{{ .Revision }}
-            - tf-v0-{{ .Branch }}-
-            - tf-v0-master-
-            - tf-v0-
+            - tf-v0
           paths:
             - /tmp/templateflow
 
@@ -34,7 +33,7 @@ jobs:
             python -c "from templateflow.api import get; get('MNI152NLin6Asym', resolution=2, desc='LR', suffix='T1w')"
 
       - save_cache:
-         key: tf-v0-{{ .Branch }}-{{ .Revision }}
+         key: tf-v0
          paths:
             - /tmp/templateflow
 
@@ -59,37 +58,6 @@ jobs:
           flags: unittests
 
 
-  build_docs:
-    docker: # executor type
-      - image: nipreps/miniconda:py39_2209.01
-        auth:
-          username: $DOCKER_USER
-          password: $DOCKER_PAT
-
-    environment:
-      - FSLOUTPUTTYPE: NIFTI
-      - SUBJECTS_DIR: /tmp/subjects
-    steps:
-      - checkout
-      - run:
-          name: Create subjects folder
-          command: mkdir -p $SUBJECTS_DIR
-      - run:
-          name: Install deps
-          command: |
-            python -m pip install --no-cache-dir -U "pip>=20.3"
-      - run:
-          name: Install Nireports
-          command: |
-            python -m pip install .[docs]
-      - run:
-          name: Build only this commit
-          command: |
-            BRANCH=$( echo $CIRCLE_BRANCH | sed 's+/+_+g' )
-            make -C docs SPHINXOPTS="-W" BUILDDIR="/tmp/docs" OUTDIR=${CIRCLE_TAG:-$BRANCH} html
-      - store_artifacts:
-          path: /tmp/docs
-
 workflows:
   version: 2
   build_test_deploy:
@@ -103,11 +71,3 @@ workflows:
             branches:
               ignore:
                 - /docs?\/.*/
-
-      - build_docs:
-          filters:
-            branches:
-              ignore:
-                - /tests?\/.*/
-            tags:
-              only: /.*/

.github/workflows/build_test_deploy.yml

@@ -52,7 +52,7 @@ jobs:
       matrix:
         #os: ['ubuntu-latest', 'windows-latest', 'macos-latest']
         os: ['ubuntu-latest']
-        python-version: [3.8, 3.9, '3.10']
+        python-version: [3.8, 3.9, '3.10', '3.11', '3.12']
         architecture: ['x64', 'x86']
         package: ['.', 'dist/*.whl', 'dist/*.tar.gz']
         exclude:
@@ -80,24 +80,19 @@ jobs:
       TEMPLATEFLOW_HOME: /tmp/templateflow
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Fetch packages
         uses: actions/download-artifact@v3
         with:
           name: dist
           path: dist/
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           architecture: ${{ matrix.architecture }}
       - name: Display Python version
         run: python -c "import sys; print(sys.version)"
-      - name: Generate requirements file and install them
-        run: |
-          python -m pip install --upgrade pip-tools
-          python -m piptools compile --output-file=requirements.txt pyproject.toml
-          pip install -r requirements.txt
 
       - name: Install package
         run: pip install $PACKAGE

nireports/__init__.py

@@ -27,11 +27,10 @@
 try:
     from ._version import __version__
 except ModuleNotFoundError:
-    from pkg_resources import DistributionNotFound, get_distribution
-
+    from importlib.metadata import version, PackageNotFoundError
     try:
-        __version__ = get_distribution(__packagename__).version
-    except DistributionNotFound:
-        __version__ = "unknown"
-    del get_distribution
-    del DistributionNotFound
+        __version__ = version(__packagename__)
+    except PackageNotFoundError:
+        __version__ = "0+unknown"
+    del version
+    del PackageNotFoundError

nireports/assembler/data/__init__.py

@@ -0,0 +1,182 @@
+"""Nireports assembler data files
+
+.. autofunction:: load
+
+.. automethod:: load.readable
+
+.. automethod:: load.as_path
+
+.. automethod:: load.cached
+
+.. autoclass:: Loader
+"""
+from __future__ import annotations
+
+import atexit
+import os
+from contextlib import AbstractContextManager, ExitStack
+from functools import cached_property
+from pathlib import Path
+from types import ModuleType
+from typing import Union
+
+try:
+    from functools import cache
+except ImportError:  # PY38
+    from functools import lru_cache as cache
+
+try:  # Prefer backport to leave consistency to dependency spec
+    from importlib_resources import as_file, files
+except ImportError:
+    from importlib.resources import as_file, files  # type: ignore
+
+try:  # Prefer stdlib so Sphinx can link to authoritative documentation
+    from importlib.resources.abc import Traversable
+except ImportError:
+    from importlib_resources.abc import Traversable
+
+__all__ = ["load"]
+
+
+class Loader:
+    """A loader for package files relative to a module
+
+    This class wraps :mod:`importlib.resources` to provide a getter
+    function with an interpreter-lifetime scope. For typical packages
+    it simply passes through filesystem paths as :class:`~pathlib.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__)
+
+    :class:`~Loader` objects implement the :func:`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    | :meth:`cached`   |
+    +---------------+----------------+------------------+
+    | `True`        | `with` context | :meth:`as_path`  |
+    +---------------+----------------+------------------+
+    | `False`       | n/a            | :meth:`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)
+
+    .. automethod:: readable
+
+    .. automethod:: as_path
+
+    .. automethod:: cached
+    """
+
+    def __init__(self, anchor: Union[str, ModuleType]):
+        self._anchor = anchor
+        self.files = files(anchor)
+        self.exit_stack = ExitStack()
+        atexit.register(self.exit_stack.close)
+        # Allow class to have a different docstring from instances
+        self.__doc__ = self._doc
+
+    @cached_property
+    def _doc(self):
+        """Construct docstring for instances
+
+        Lists the public top-level paths inside the location, where
+        non-public means has a `.` or `_` prefix or is a 'tests'
+        directory.
+        """
+        top_level = sorted(
+            os.path.relpath(p, self.files) + "/"[: p.is_dir()]
+            for p in self.files.iterdir()
+            if p.name[0] not in (".", "_") and p.name != "tests"
+        )
+        doclines = [
+            f"Load package files relative to ``{self._anchor}``.",
+            "",
+            "This package contains the following (top-level) files/directories:",
+            "",
+            *(f"* ``{path}``" for path in top_level),
+        ]
+
+        return "\n".join(doclines)
+
+    def readable(self, *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.
+        """
+        return self.files.joinpath(*segments)
+
+    def as_path(self, *segments) -> AbstractContextManager[Path]:
+        """Ensure data is available as a :class:`~pathlib.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.
+        """
+        return as_file(self.files.joinpath(*segments))
+
+    @cache
+    def cached(self, *segments) -> Path:
+        """Ensure data is available as a :class:`~pathlib.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.
+        """
+        return self.exit_stack.enter_context(as_file(self.files.joinpath(*segments)))
+
+    __call__ = cached
+
+
+load = Loader(__package__)