Merge pull request #83 from khaeru/enh/2023-W17

Miscellaneous enhancements for 2023-W17

.github/workflows/lint.yaml

@@ -13,4 +13,10 @@ jobs:
       # If the "Latest version testable on GitHub Actions" in pytest.yaml
       # is not the latest 3.x stable version, adjust here to match:
       python-version: "3.10"
-      type-hint-packages: pytest ixmp types-PyYAML types-setuptools xarray
+      type-hint-packages: >-
+        importlib_resources
+        nbclient
+        pint
+        pytest
+        types-PyYAML
+        xarray

.github/workflows/pytest.yaml

@@ -13,9 +13,6 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
-env:
-  depth: 100  # Depth of history to clone, for setuptools-scm
-
 jobs:
   pytest:
     strategy:
@@ -24,50 +21,50 @@ jobs:
         - macos-latest
         - ubuntu-latest
         - windows-latest
-        python-version:
-        - "3.8"  # Earliest version supported by genno; matches xarray/setup.cfg
-        - "3.9"
-        - "3.10" # Latest release / latest supported by genno / testable on GHA
 
-        # For fresh releases and development versions of Python, compiled
-        # binary wheels are not available for some dependencies, e.g. llvmlite,
-        # numba, numpy, and/or pandas. Compiling these on the job runner
-        # requires a more elaborate build environment, currently out of scope
-        # for genno. Exclude these versions from CI.
-        # - "3.11.0-alpha.2"  # Development version
+        python:
+        # llvmlite (thus numba, thus sparse) usually lags the latest Python
+        # release. Only test SparseDataArray where possible.
+        # Earliest version supported by genno; matches xarray/setup.cfg
+        - {version: "3.8", extras: ",sparse"}
+        - {version: "3.9", extras: ",sparse"}
+        - {version: "3.10", extras: ",sparse"}
+        # Latest release / latest supported by genno / testable on GHA
+        - {version: "3.11", extras: ""}
+
+        # For fresh releases and development versions of Python, compiled binary
+        # wheels are not available for some dependencies, e.g. numpy, pandas.
+        # Compiling these on the job runner requires a more elaborate build
+        # environment, currently out of scope for genno. Exclude these versions
+        # from CI.
+        # - {version: "3.12.0-alpha.2", extras: ""}  # Development version
 
       fail-fast: false
 
     runs-on: ${{ matrix.os }}
-    name: ${{ matrix.os }}-py${{ matrix.python-version }}
+    name: ${{ matrix.os }}-py${{ matrix.python.version }}
 
     steps:
     - uses: actions/checkout@v3
       with:
         fetch-depth: ${{ env.depth }}
 
-    - name: Fetch tags (for setuptools-scm)
-      run: git fetch --tags --depth=${{ env.depth }}
-
     - uses: actions/setup-python@v4
       with:
-        python-version: ${{ matrix.python-version }}
+        python-version: ${{ matrix.python.version }}
         cache: pip
         cache-dependency-path: "**/pyproject.toml"
 
     - uses: ts-graphviz/setup-graphviz@v1
 
     - name: Install the Python package and dependencies
-      # TEMPORARY install ixmp from `main` branch pending iiasa/ixmp#477
-      run: |
-        pip install "ixmp @ git+https://github.com/iiasa/ixmp.git@main"
-        pip install --upgrade --upgrade-strategy=eager .[docs,tests]
+      run: pip install --upgrade --upgrade-strategy=eager .[docs,tests${{ matrix.python.extras }}]
 
     - name: Run test suite using pytest
       run: pytest genno --trace-config --color=yes --verbose --cov-report=xml --cov-report=term --numprocesses auto
 
     - name: Test documentation build using Sphinx
-      if: ${{ startsWith(matrix.os, 'ubuntu') }}
+      if: startsWith(matrix.os, 'ubuntu')
       run: make -C doc html
 
     - name: Upload test coverage to Codecov.io

.readthedocs.yml

@@ -1,11 +1,12 @@
 version: 2
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
 python:
-  version: 3.8
   install:
   - method: pip
     path: .
-    extra_requirements:
-    - docs
-    - tests
-  - requirements: ci/requirements.rtd
+    extra_requirements: [docs,tests]

doc/api.rst

@@ -3,10 +3,6 @@ API reference
 
 .. currentmodule:: genno
 
-.. contents::
-   :local:
-   :depth: 3
-
 Top-level classes and functions
 ===============================
 

doc/cache.rst

@@ -1,10 +1,6 @@
 Caching
 *******
 
-.. contents::
-   :local:
-   :backlinks: none
-
 Basics
 ======
 

doc/compat-plotnine.rst

@@ -7,6 +7,12 @@ Plotnine (:mod:`.compat.plotnine`)
 
 To use :class:`.Plot`:
 
+.. ipython:: python
+   :suppress:
+
+   import matplotlib
+   matplotlib.use("svg")
+
 .. ipython::
 
    In [1]:    from pathlib import Path
@@ -55,7 +61,7 @@ To use :class:`.Plot`:
    .. ipython::
 
       In [1]: c.get("plot")
-      Out[1]: ./test.svg
+      Out[1]: PosixPath("plotnine-demo.svg")
 
    .. image:: ./plotnine-demo.svg
       :alt: Demonstration output from genno.compat.plotnine.

doc/conf.py

@@ -39,8 +39,17 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for a list of
 # builtin themes.
-html_theme = "sphinx_rtd_theme"
-
+html_theme = "sphinx_book_theme"
+
+html_theme_options = dict(
+    path_to_docs="doc",
+    repository_url="https://github.com/khaeru/genno",
+    show_navbar_depth=2,
+    use_edit_page_button=True,
+    use_issues_button=True,
+    use_repository_button=True,
+    use_source_button=True,
+)
 
 # -- Options for sphinx.ext.extlinks ---------------------------------------------------
 

doc/config.rst

@@ -6,11 +6,6 @@ Configuration
 As shown in :ref:`Concepts and usage <describe-tasks>`, a :class:`.Computer` can be populated programmatically.
 :mod:`genno` can also read a simple **configuration format** in which settings and tasks are specified.
 
-.. contents::
-   :local:
-   :depth: 2
-   :backlinks: none
-
 Overview
 ========
 

doc/usage.rst

@@ -4,10 +4,6 @@ Concepts and usage
 This page introduces the essential concepts of :mod:`genno` and demonstrates basic usage.
 Click on the names of classes and methods to access complete descriptions in the :doc:`api`.
 
-.. contents::
-   :local:
-   :backlinks: none
-
 Quantity
 ========
 

doc/whatsnew.rst

@@ -1,16 +1,24 @@
 What's new
 **********
 
-.. contents::
-   :local:
-   :backlinks: none
-   :depth: 1
-
 Next release
 ============
 
+- genno supports and is tested on Python 3.11 (:pull:`83`).
+- Update dependencies (:pull:`83`):
+
+  - General: :mod:`importlib_resources` (the independent backport of :mod:`importlib.resources`) is added for Python 3.9 and earlier.
+  - ``genno[sparse]``: new set of optional dependencies, including :mod:`sparse`.
+    Install this set in order to use :class:`.SparseDataArray` for :class:`.Quantity`.
+
+    Note that sparse depends on :mod:`numba`, and thus :mod:`llvmlite`, and both of these package can lag new Python versions by several months.
+    For example, as of this release, they do not yet support Python 3.11, and thus :mod:`sparse` and :class:`genno.SparseDataArray` can only be used with Python 3.10 and earlier.
+  - ``genno[tests]``: :mod:`ixmp` is removed; :mod:`jupyter` and :mod:`nbclient` are added.
+    Testing utilities in :mod:`genno.testing.jupyter` are duplicated from :mod:`ixmp.testing.jupyter`.
+
 - Adjust :meth:`.AttrSeries.interp` for compatibility with pandas 2.0.0 (released 2023-04-03) (:pull:`81`).
 
+
 v1.15.0 (2023-04-02)
 ====================
 

genno/__init__.py

@@ -1,23 +1,10 @@
-import warnings
+from dask.core import quote
 
-# genno.core.sparsedataarray -> sparse 0.11.2 -> numba 0.52.0 -> numpy 1.20
-warnings.filterwarnings(
-    action="ignore",
-    message="`np.long` is a deprecated alias for `np.compat.long`",
-    module="numba.core",
-)
-
-from dask.core import quote  # noqa: E402
-
-from .config import configure  # noqa: E402
-from .core.computer import Computer  # noqa: E402
-from .core.exceptions import (  # noqa: E402
-    ComputationError,
-    KeyExistsError,
-    MissingKeyError,
-)
-from .core.key import Key  # noqa: E402
-from .core.quantity import Quantity  # noqa: E402
+from .config import configure
+from .core.computer import Computer
+from .core.exceptions import ComputationError, KeyExistsError, MissingKeyError
+from .core.key import Key
+from .core.quantity import Quantity
 
 __all__ = [
     "ComputationError",

genno/compat/pint.py

@@ -0,0 +1,26 @@
+"""Compatibility code for :mod:`pint`.
+
+Notes:
+
+- In unit expressions that contain multiple errors (e.g. undefined units *and* invalid
+  syntax), the exact exception raised by pint can sometimes vary between releases.
+- In pint 0.17, DefinitionSyntaxError is a subclass of SyntaxError.
+  In pint 0.20, it is a subclass of ValueError.
+"""
+from typing import Type
+
+import pint
+
+try:
+    PintError: Type[Exception] = pint.PintError
+    ApplicationRegistry: Type = pint.ApplicationRegistry
+except AttributeError:
+    # Older versions of pint, e.g. 0.17
+    PintError = type("PintError", (Exception,), {})
+    ApplicationRegistry = pint.UnitRegistry
+
+
+__all__ = [
+    "ApplicationRegistry",
+    "PintError",
+]

genno/computations.py

@@ -276,8 +276,7 @@ def broadcast_map(quantity, map, rename={}, strict=False):
     strict : bool, optional
         Require that each element of ``d2`` is mapped from exactly 1 element of ``d1``.
     """
-    # NB int() is for AttrSeries
-    if strict and int(map.sum()) != len(map.coords[map.dims[1]]):
+    if strict and int(map.sum().item()) != len(map.coords[map.dims[1]]):
         raise ValueError("invalid map")
 
     return product(quantity, map).sum(map.dims[0]).rename(rename)

genno/core/sparsedataarray.py

@@ -2,7 +2,13 @@
 
 import numpy as np
 import pandas as pd
-import sparse
+
+try:
+    import sparse
+
+    HAS_SPARSE = True
+except ImportError:
+    HAS_SPARSE = False
 import xarray as xr
 from xarray.core import dtypes
 from xarray.core.utils import either_dict_or_kwargs