Merge pull request #524 from iiasa/enh/2024-W13

Housekeeping for 2024-W13

.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+updates:
+- package-ecosystem: "github-actions"
+  # Only update major versions
+  ignore:
+  - dependency-name: "*"
+    update-types:
+    - "version-update:semver-minor"
+    - "version-update:semver-patch"
+  # Below config mirrors the example at
+  # https://github.com/dependabot/dependabot-core/blob/main/.github/dependabot.yml
+  directory: "/"
+  schedule:
+    interval: "weekly"
+    day: "sunday"
+    time: "16:00"
+  groups:
+    all-actions:
+      patterns: [ "*" ]
+  assignees:
+  - "glatterf42"
+  - "khaeru"
+  labels:
+  - "dependencies"
+  reviewers:
+  - "glatterf42"
+  - "khaeru"

.github/pull_request_template.md

@@ -1,27 +1,32 @@
 <!--
+Delete each of these comments as you fill out the PR description.
+This confirms you have given enough information for others to understand what
+the PR does.
 
-Delete each of these instruction comments as you complete it.
-
-Title: use a short, declarative statement similar to a commit message,
-e.g. “Change [thing X] to [fix solve bug|enable feature Y]”
-
+Title: use a short, declarative statement similar to a commit message.
+For example: “Change [thing X] to [fix solve bug|enable feature Y]”
 -->
 
 **Required:** write a single sentence that describes the changes made by this PR.
 
-<!-- Optional: write a longer description to help a reviewer understand the PR in ~3 minutes. -->
+<!--
+Optional:
+
+- Write a ≤3 minute summary so a reviewer can understand the PR.
+- Write a longer, exhaustive description.
+-->
 
 ## How to review
 
 **Required:** describe specific things that reviewer(s) must do, in order to ensure that the PR achieves its goal.
-If no review is required, write “No review:” and describe why.
+If no review is required, write “No review: …” and describe why.
 
 <!--
 For example, one or more of:
 
 - Read the diff and note that the CI checks all pass.
 - Run a specific code snippet or command and check the output.
-- Build the documentation and look at a certain page.
+- View the preview build of the documentation and look at a certain page.
 - Ensure that changes/additions are self-documenting, i.e. that another
   developer (someone like the reviewer) will be able to understand what the code
   does in the future.
@@ -31,23 +36,24 @@ For example, one or more of:
 
 <!-- This item is always required. -->
 - [ ] Continuous integration checks all ✅
-  <!--
-  The following items are all *required* if the PR results in changes to user-
-  facing behaviour, e.g. new features or fixes to existing behaviour. They are
-  *optional* if the changes are solely to documentation, CI configuration, etc.
-  
-  In ambiguous cases, strike them out and add a short explanation, e.g.
-  
-  - ~Add or expand tests.~ No change in behaviour, simply refactoring.
-  -->
+<!--
+The following items are *required* if the PR results in changes to user-facing
+behaviour—such as new features, or fixes to existing behaviour.
+
+They are *optional* if the changes are solely to documentation, test/CI
+configuration, etc. In such cases, strike them out and add a short explanation,
+for example:
+
+- ~Add or expand tests.~ No change in behaviour, simply refactoring.
+-->
 - [ ] Add or expand tests; coverage checks both ✅
 - [ ] Add, expand, or update documentation.
 - [ ] Update release notes.
   <!--
   To do this, add a single line at the TOP of the “Next release” section of
   RELEASE_NOTES.rst, where '999' is the GitHub pull request number:
 
-  - :pull:`999`: Title or single-sentence description from above.
+  - Title or single-sentence description from above (:pull:`999`:).
 
   Commit with a message like “Add #999 to release notes”
   -->

.github/workflows/pytest.yaml

@@ -141,12 +141,11 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - uses: actions/setup-python@v5
-      with:
-        python-version: "3.x"
+      with: { python-version: "3.12" }
 
     - name: Force recreation of pre-commit virtual environment for mypy
       if: github.event_name == 'schedule'
       run: gh cache list -L 999 | cut -f2 | grep pre-commit | xargs -I{} gh cache delete "{}" || true
       env: { GH_TOKEN: "${{ github.token }}" }
 
-    - uses: pre-commit/[email protected].0
+    - uses: pre-commit/[email protected].1

.pre-commit-config.yaml

@@ -10,16 +10,17 @@ repos:
     language: python
     entry: bash -c ". ${PRE_COMMIT_MYPY_VENV:-/dev/null}/bin/activate 2>/dev/null; mypy $0 $@"
     additional_dependencies:
-    - mypy >= 1.8.0
+    - mypy >= 1.9.0
     - genno
     - GitPython
     - nbclient
+    - pandas-stubs
     - pytest
     - sphinx
     - xarray
     args: ["."]
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.1.14
+  rev: v0.3.4
   hooks:
   - id: ruff
   - id: ruff-format

doc/conf.py

@@ -19,7 +19,7 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions coming
 # with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
-    "ixmp.util.sphinx_linkcode_github",
+    # First party
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.coverage",
@@ -29,6 +29,9 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
+    # Others
+    "ixmp.util.sphinx_linkcode_github",
+    "genno.compat.sphinx.rewrite_refs",
     "sphinxcontrib.bibtex",
 ]
 
@@ -77,6 +80,14 @@
 # The theme to use for HTML and HTML Help pages.
 html_theme = "sphinx_rtd_theme"
 
+# -- Options for genno.compat.sphinx.rewrite_refs --------------------------------------
+
+reference_aliases = {
+    r"(genno\.|)Quantity": "genno.core.attrseries.AttrSeries",
+    "AnyQuantity": ":data:`genno.core.quantity.AnyQuantity`",
+}
+
+
 # -- Options for sphinx.ext.extlinks ---------------------------------------------------
 
 extlinks = {
@@ -121,7 +132,7 @@ def local_inv(name: str, *parts: str) -> Optional[str]:
     "python": ("https://docs.python.org/3/", None),
     "sparse": ("https://sparse.pydata.org/en/stable/", None),
     "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
-    "xarray": ("https://xarray.pydata.org/en/stable/", None),
+    "xarray": ("https://docs.xarray.dev/en/stable", None),
 }
 
 # -- Options for sphinx.ext.linkcode / ixmp.util.sphinx_linkcode_github ----------------

doc/reporting.rst

@@ -143,44 +143,20 @@ Operators
 .. automodule:: ixmp.report.operator
    :members:
 
-   :mod:`ixmp.report` defines these operators:
+   More than 30 operators are defined by :mod:`genno.operator` and its compatibility modules including :mod:`genno.compat.plotnine` and :mod:`genno.compat.sdmx`.
+   See the genno documentation for details.
+
+   :mod:`ixmp.report` defines these additional operators:
 
    .. autosummary::
 
       data_for_quantity
       from_url
       get_ts
       map_as_qty
-      update_scenario
-      store_ts
       remove_ts
-
-   Basic operators are defined by :mod:`genno.operator` and its compatibility modules; see there for details:
-
-   .. autosummary::
-
-      ~genno.compat.plotnine.Plot
-      ~genno.operator.add
-      ~genno.operator.aggregate
-      ~genno.operator.apply_units
-      ~genno.compat.pyam.operator.as_pyam
-      ~genno.operator.broadcast_map
-      ~genno.operator.combine
-      ~genno.operator.concat
-      ~genno.operator.disaggregate_shares
-      ~genno.operator.div
-      ~genno.operator.group_sum
-      ~genno.operator.interpolate
-      ~genno.operator.load_file
-      ~genno.operator.mul
-      ~genno.operator.pow
-      ~genno.operator.product
-      ~genno.operator.relabel
-      ~genno.operator.rename_dims
-      ~genno.operator.ratio
-      ~genno.operator.select
-      ~genno.operator.sum
-      ~genno.operator.write_report
+      store_ts
+      update_scenario
 
 Utilities
 =========

ixmp/backend/__init__.py

@@ -1,4 +1,5 @@
 """Backend API."""
+
 from enum import IntFlag
 from typing import Dict, List, Type, Union
 

ixmp/backend/io.py

@@ -112,7 +112,9 @@ def s_write_excel(be, s, path, item_type, filters=None, max_row=None):
             sheet_name = name + (f"({sheet_num})" if sheet_num > 1 else "")
 
             # Subset the data (only on rows, if a DataFrame) and write
-            data.iloc[first_row:last_row].to_excel(writer, sheet_name, index=False)
+            data.iloc[first_row:last_row].to_excel(
+                writer, sheet_name=sheet_name, index=False
+            )
 
     # Discard entries that were not written
     for name in omitted:
@@ -172,7 +174,7 @@ def maybe_init_item(scenario, ix_type, name, new_idx, path):
             raise ValueError from None
 
 
-# FIXME reduce complexity from 26 to <=15
+# FIXME reduce complexity 22 → ≤13
 def s_read_excel(  # noqa: C901
     be, s, path, add_units=False, init_items=False, commit_steps=False
 ):

ixmp/backend/jdbc.py

@@ -965,7 +965,7 @@ def item_index(self, s, name, sets_or_names):
         jitem = self._get_item(s, "item", name, load=False)
         return list(getattr(jitem, f"getIdx{sets_or_names.title()}")())
 
-    # FIXME reduce complexity from 19 to <=15
+    # FIXME reduce complexity 18 → ≤13
     def item_get_elements(self, s, type, name, filters=None):  # noqa: C901
         if filters:
             # Convert filter elements to strings

ixmp/core/platform.py

@@ -9,7 +9,7 @@
 from ixmp.backend import BACKENDS, FIELDS, ItemType
 from ixmp.util import as_str_list
 
-if TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:
     from ixmp.backend.base import Backend
 
 
@@ -235,11 +235,11 @@ def export_timeseries_data(
                 "model or scenario."
             )
         filters = {
-            "model": as_str_list(model) or [],
-            "scenario": as_str_list(scenario) or [],
-            "variable": as_str_list(variable) or [],
-            "unit": as_str_list(unit) or [],
-            "region": as_str_list(region) or [],
+            "model": as_str_list(model),
+            "scenario": as_str_list(scenario),
+            "variable": as_str_list(variable),
+            "unit": as_str_list(unit),
+            "region": as_str_list(region),
             "default": default,
             "export_all_runs": export_all_runs,
         }