Enable strict mypy settings

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v1.14.1
+  rev: v1.16.0
   hooks:
   - id: mypy
     pass_filenames: false
@@ -11,11 +11,12 @@ repos:
     - nbclient
     - pandas-stubs
     - pytest
+    - pytest_httpserver
     - Sphinx
     - werkzeug
     - xarray
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.9.1
+  rev: v0.11.13
   hooks:
   - id: ruff
   - id: ruff-format

RELEASE_NOTES.rst

@@ -1,11 +1,62 @@
 Next release
 ============
 
+Migration notes
+---------------
+
+- Replace calls to :meth:`.Scenario.items` with :py:`par_data=True`:
+
+  .. code-block:: python
+
+     for name, df in scenario.items(..., par_data=True):
+         ...
+
+  with:
+
+  .. code-block:: python
+
+     for name, df in scenario.iter_par_data(...):
+         ...
+
+- Replace use of the shorthand:
+
+  .. code-block:: python
+
+     scenario._backend("method_name", ...)
+
+  with:
+
+  .. code-block:: python
+
+     scenario.platform._backend.method_name(...)
+
 All changes
 -----------
 
+- Improve :class:`.IXMP4Backend` (:pull:`581`):
+
+  - Support creation and modification of 0-dimensional parameters (:class:`ixmp4.Scalar`).
+
+- New method :meth:`.Scenario.iter_par_data` (:pull:`581`).
+  :meth:`.Scenario.items` no longer supports iterating over item *contents*.
+- Improve type hinting in :mod:`ixmp` (:pull:`581`).
+  This supports more precise and complete type checking of downstream code that uses :mod:`ixmp`.
+
+  - New module :mod:`ixmp.types` containing types for annotating code that uses :mod:`ixmp`.
+  - New type guard function :func:`.util.ixmp4.is_ixmp4backend`.
+
+- Update :class:`.ItemType` (:pull:`581`):
+
+  - New method :meth:`~.ItemType.is_model_data`.
+  - Remove short aliases such as :py:`ItemType.S` for :attr:`~.ItemType.SET`.
+
+- New module/class :class:`ixmp.core.item.Item` and subclasses (:pull:`581`).
+  These encapsulate structural information about :ref:`data-model-data`.
 - Document (at :ref:`system-dependencies`) that JRE version ≥ 11 is required
   when using :class:`.JDBCBackend` with :mod:`jpype` version ≥ 1.6.0 (:pull:`586`).
+- The :meth:`.TimeSeries._backend` shorthand method is deprecated (:pull:`581`).
+  Calling this method emits :class:`DeprecationWarning`,
+  and the method will be removed in a future version of :mod:`ixmp`.
 
 .. _v3.11.1:
 

doc/api-backend.rst

@@ -111,6 +111,9 @@ IXMP4Backend
 
    IXMP4Backend supports storage in local, SQLite databases.
 
+.. automodule:: ixmp.util.ixmp4
+   :members:
+
 .. currentmodule:: ixmp.backend
 
 Backend API

doc/api.rst

@@ -231,8 +231,8 @@ Utilities for documentation
 
       https://github.com/{repo_slug}/blob/{remote_head}/path/to/source.py#L123-L456
 
-Utilities for testing
-~~~~~~~~~~~~~~~~~~~~~
+Utilities for testing and type checking
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. currentmodule:: ixmp.testing
 
@@ -245,3 +245,8 @@ Utilities for testing
 
 .. automodule:: ixmp.testing.data
    :members: DATA, HIST_DF, TS_DF
+
+.. currentmodule:: ixmp.types
+
+.. automodule:: ixmp.types
+   :members:

ixmp/__init__.py

@@ -1,11 +1,13 @@
 import logging
 import sys
 from importlib.metadata import PackageNotFoundError, version
+from typing import Any, Optional
 
 from ixmp._config import config
 from ixmp.backend.common import IAMC_IDX, ItemType
 from ixmp.core.platform import Platform
-from ixmp.core.scenario import Scenario, TimeSeries
+from ixmp.core.scenario import Scenario
+from ixmp.core.timeseries import TimeSeries
 from ixmp.model.base import ModelError
 from ixmp.report import Reporter
 from ixmp.util import DeprecatedPathFinder, show_versions
@@ -50,10 +52,11 @@
 log.setLevel(logging.WARNING)
 
 
-def __getattr__(name):
+# TODO What's the proper type hint for a Module?
+def __getattr__(name: str) -> Optional[Any]:
     if name == "utils":
         # Import via the old name to trigger DeprecatedPathFinder
-        import ixmp.utils as util  # type: ignore [import-not-found]
+        import ixmp.utils as util
 
         return util
     else:

ixmp/_config.py

@@ -1,10 +1,14 @@
 import json
 import logging
 import os
+from collections.abc import Generator
 from copy import copy
-from dataclasses import asdict, dataclass, field, fields, make_dataclass
+from dataclasses import Field, asdict, dataclass, field, fields, make_dataclass
 from pathlib import Path
-from typing import Any, Optional
+from typing import TYPE_CHECKING, Any, Optional, Union
+
+if TYPE_CHECKING:
+    from ixmp.types import PlatformInitKwargs
 
 log = logging.getLogger(__name__)
 
@@ -15,13 +19,13 @@ class _JSONEncoder(json.JSONEncoder):
     The default JSONEncoder does not automatically convert pathlib.Path objects.
     """
 
-    def default(self, o):
+    def default(self, o: Any) -> Any:
         if isinstance(o, Path):
             return str(o)
         return json.JSONEncoder.default(self, o)
 
 
-def _iter_config_paths():
+def _iter_config_paths() -> Generator[tuple[str, Path], Any, None]:
     """Yield recognized configuration paths, in order of priority."""
     try:
         yield "environment (IXMP_DATA)", Path(os.environ["IXMP_DATA"]).resolve()
@@ -39,7 +43,7 @@ def _iter_config_paths():
     yield "default", Path.home().joinpath(".local", "share", "ixmp")
 
 
-def _locate(filename=None):
+def _locate(filename: Optional[str] = None) -> Path:
     """Locate an existing director or `filename` in the ixmp configuration directory.
 
     If `filename` is :obj:`None` (the default), only directories are located.
@@ -59,7 +63,7 @@ def _locate(filename=None):
     )
 
 
-def _platform_default():
+def _platform_default() -> dict[str, Union[str, "PlatformInitKwargs"]]:
     """Default values for the `platform` setting on BaseValues."""
     try:
         from ixmp.util.ixmp4 import configure_logging_and_warnings
@@ -96,15 +100,19 @@ def _platform_default():
 class BaseValues:
     """Base class for storing configuration values."""
 
-    platform: dict = field(default_factory=_platform_default)
+    platform: dict[str, Union[str, "PlatformInitKwargs"]] = field(
+        default_factory=_platform_default
+    )
 
-    def __getitem__(self, name):
+    def __getitem__(self, name: str) -> Any:
         return getattr(self, name.replace(" ", "_"))
 
-    def __setitem__(self, name, value):
+    def __setitem__(self, name: str, value: Any) -> None:
         setattr(self, name.replace(" ", "_"), value)
 
-    def add_field(self, name, type_, default, **kwargs):
+    def add_field(
+        self, name: str, type_: Any, default: Any, **kwargs: Any
+    ) -> tuple[type, "BaseValues"]:
         # Check `name`
         name = name.replace(" ", "_")
         if (
@@ -123,7 +131,7 @@ def add_field(self, name, type_, default, **kwargs):
         # Re-use current values and any defaults for the new fields
         return new_cls, new_cls(**asdict(self))
 
-    def delete_field(self, name):
+    def delete_field(self, name: str) -> tuple[type, "BaseValues"]:
         # Check `name`
         name = self.munge(name)
         if name in BaseValues.__dataclass_fields__:
@@ -132,7 +140,7 @@ def delete_field(self, name):
         # Create a new dataclass, removing `name`
         fields = []
         for f in self.__dataclass_fields__.values():
-            if f.name == name or f in BaseValues.__dataclass_fields__:
+            if f.name == name or f in BaseValues.__dataclass_fields__.values():
                 continue
             fields.append((f.name, f.type, f))
         new_cls = make_dataclass("Values", fields, bases=(BaseValues,))
@@ -145,7 +153,7 @@ def delete_field(self, name):
     def keys(self) -> tuple[str, ...]:
         return tuple(map(lambda f: f.name.replace("_", " "), fields(self)))
 
-    def set(self, name: str, value: Any, strict: bool = True):
+    def set(self, name: str, value: Any, strict: bool = True) -> None:
         f = self.get_field(name)
         if strict and f is None:
             raise KeyError(name)
@@ -165,15 +173,17 @@ def set(self, name: str, value: Any, strict: bool = True):
 
     # Utilities
 
-    def get_field(self, name):
+    def get_field(self, name: str) -> Optional[Field[Any]]:
         """For `name` = "field name", retrieve a field "field_name", if any."""
         for f in fields(self):
             if f.name in (name, name.replace(" ", "_")):
                 return f
+        return None
 
-    def munge(self, name):
+    def munge(self, name: str) -> str:
         """Return a field name matching `name`."""
-        return self.get_field(name).name or name
+        field = self.get_field(name)
+        return field.name if field else name
 
 
 class Config:
@@ -247,7 +257,7 @@ def __init__(self, read: bool = True):
         if read:
             self.read()
 
-    def read(self):
+    def read(self) -> None:
         """Try to read configuration keys from file.
 
         If successful, the attribute :attr:`path` is set to the path of the file.
@@ -286,7 +296,9 @@ def keys(self) -> tuple[str, ...]:
         """Return the names of all registered configuration keys."""
         return self.values.keys()
 
-    def register(self, name: str, type_: type, default: Optional[Any] = None, **kwargs):
+    def register(
+        self, name: str, type_: type, default: Optional[Any] = None, **kwargs: Any
+    ) -> None:
         """Register a new configuration key.
 
         Parameters
@@ -312,7 +324,7 @@ def unregister(self, name: str) -> None:
         """Unregister and clear the configuration key `name`."""
         self._ValuesClass, self.values = self.values.delete_field(name)
 
-    def set(self, name: str, value: Any, _strict: bool = True):
+    def set(self, name: str, value: Any, _strict: bool = True) -> None:
         """Set configuration key `name` to `value`.
 
         Parameters
@@ -325,11 +337,11 @@ def set(self, name: str, value: Any, _strict: bool = True):
 
         self.values.set(name, value, _strict)
 
-    def clear(self):
+    def clear(self) -> None:
         """Clear all configuration keys by setting empty or default values."""
         self.values = self._ValuesClass()
 
-    def save(self):
+    def save(self) -> None:
         """Write configuration keys to file.
 
         ``config.json`` is created in the first of the ixmp configuration directories
@@ -353,7 +365,7 @@ def save(self):
         # Update the path attribute to match the written file
         self.path = path
 
-    def add_platform(self, name: str, *args, **kwargs):
+    def add_platform(self, name: str, *args: Union[str, Path], **kwargs: Any) -> None:
         """Add or overwrite information about a platform.
 
         Parameters
@@ -375,7 +387,7 @@ def add_platform(self, name: str, *args, **kwargs):
         """
         if name == "default":
             assert len(args) == 1
-            info = args[0]
+            info: Union[str, Path, dict[str, Any]] = args[0]
 
             if info not in self.values["platform"]:
                 raise ValueError(f"Cannot set unknown {repr(info)} as default platform")
@@ -387,6 +399,7 @@ def add_platform(self, name: str, *args, **kwargs):
             try:
                 # Get the backend class
                 cls = _args.pop(0)
+                assert isinstance(cls, str)
                 backend_class = get_class(cls)
             except IndexError:
                 raise ValueError("Must give at least 1 arg: backend class")
@@ -402,7 +415,7 @@ def add_platform(self, name: str, *args, **kwargs):
 
         self.values["platform"][name] = info
 
-    def get_platform_info(self, name: str) -> tuple[str, dict[str, Any]]:
+    def get_platform_info(self, name: str) -> tuple[str, "PlatformInitKwargs"]:
         """Return information on configured Platform `name`.
 
         Parameters
@@ -436,7 +449,7 @@ def get_platform_info(self, name: str) -> tuple[str, dict[str, Any]]:
                 f"\nfrom {self.path}"
             ) from None
 
-    def remove_platform(self, name: str):
+    def remove_platform(self, name: str) -> None:
         """Remove the configuration for platform `name`."""
         self.values["platform"].pop(name)
 

ixmp/backend/__init__.py

@@ -1,11 +1,12 @@
 """Backend API."""
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Union
 
 from .common import ItemType
 
 if TYPE_CHECKING:
-    import ixmp.backend.base
+    from ixmp.backend.ixmp4 import IXMP4Backend
+    from ixmp.backend.jdbc import JDBCBackend
 
 __all__ = [
     "ItemType",
@@ -15,10 +16,10 @@
 
 #: Mapping from names to available backends. To register additional backends, add
 #: entries to this dictionary.
-BACKENDS: dict[str, type["ixmp.backend.base.Backend"]] = {}
+BACKENDS: dict[str, Union[type["IXMP4Backend"], type["JDBCBackend"]]] = {}
 
 
-def get_class(name: str) -> type["ixmp.backend.base.Backend"]:
+def get_class(name: str) -> Union[type["IXMP4Backend"], type["JDBCBackend"]]:
     """Return a reference to a :class:`~.base.Backend` subclass.
 
     Note that unlike :func:`.model.get_class`, this function does not create a new