Merge pull request #158 from khaeru/enh/typing

Improve .types, type hinting

.github/workflows/pytest.yaml

@@ -31,7 +31,7 @@ jobs:
         - {version: "3.11", extras: ".[sparse]"}
         - {version: "3.12", extras: ".[sparse]"}
         # Latest release / latest supported by genno / testable on GHA
-        - {version: "3.13", extras: '"Pint > 0.24"'}
+        - {version: "3.13", extras: '".[sparse]"'}
 
         # For fresh releases and development versions of Python, compiled binary
         # wheels are not available for some dependencies, e.g. numpy, pandas.

.readthedocs.yml

@@ -10,3 +10,6 @@ python:
   - method: pip
     path: .
     extra_requirements: [docs,tests]
+
+sphinx:
+  configuration: doc/conf.py

doc/whatsnew.rst

@@ -1,8 +1,11 @@
 What's new
 **********
 
-.. Next release
-.. ============
+Next release
+============
+
+- :class:`.SparseDataArray` is tested on Python 3.13 (:pull:`158`).
+- :meth:`.AttrSeries.sum` supports the same use of :any:`Ellipsis` as :meth:`xarray.DataArray.sum`, for instance :py:`qty.sum(...)` (:pull:`158`)
 
 v1.27.1 (2024-11-12)
 ====================

genno/caching.py

@@ -1,11 +1,12 @@
 import json
 import logging
 import pickle
+from collections.abc import Callable
 from functools import partial, singledispatch, update_wrapper
 from hashlib import blake2b
 from inspect import getmembers, iscode
 from pathlib import Path
-from typing import TYPE_CHECKING, Callable, Optional, Union
+from typing import TYPE_CHECKING, Optional, Union
 
 import pandas as pd
 

genno/compat/graphviz.py

@@ -1,6 +1,7 @@
 import re
+from collections.abc import Mapping
 from os import PathLike
-from typing import Literal, Mapping, Optional, Union
+from typing import Literal, Optional, Union
 
 from genno.core.describe import is_list_of_keys, label
 

genno/compat/plotnine/plot.py

@@ -1,7 +1,8 @@
 import logging
 from abc import ABC, abstractmethod
+from collections.abc import Hashable, Sequence
 from pathlib import Path
-from typing import Any, Hashable, Optional, Sequence
+from typing import Any, Optional
 from warnings import warn
 
 import plotnine as p9

genno/compat/pyam/operator.py

@@ -1,16 +1,9 @@
 import logging
 import re
+from collections.abc import Callable, Collection, Iterable, Mapping
 from functools import partial
 from pathlib import Path
-from typing import (
-    TYPE_CHECKING,
-    Callable,
-    Collection,
-    Iterable,
-    Mapping,
-    Optional,
-    Union,
-)
+from typing import TYPE_CHECKING, Optional, Union
 from warnings import warn
 
 import pyam

genno/compat/pyam/util.py

@@ -1,9 +1,13 @@
 import logging
-from typing import Collection, Mapping, Sequence, Union
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING
 
 import pandas as pd
 import pint
 
+if TYPE_CHECKING:
+    from genno.types import IndexLabel
+
 log = logging.getLogger(__name__)
 
 
@@ -66,15 +70,15 @@ def collapse(
 
         df[target_col] = df[target_col].str.cat(entries, sep=sep)
 
-    return df.drop(to_drop, axis=1)
+    return df.drop(list(to_drop), axis=1)
 
 
 def _extra(obj):
     """Extra columns in `obj`."""
     return sorted(set(obj.columns) - IAMC_DIMS - {"value"})
 
 
-def drop(df: pd.DataFrame, columns: Union[Collection[str], str]) -> pd.DataFrame:
+def drop(df: pd.DataFrame, columns: "IndexLabel") -> pd.DataFrame:
     """Drop `columns` if given, or all non-IAMC columns."""
 
     if isinstance(columns, str):

genno/compat/sdmx/operator.py

@@ -1,4 +1,5 @@
-from typing import Hashable, Iterable, Mapping, Optional, Union
+from collections.abc import Hashable, Iterable, Mapping
+from typing import Optional, Union
 
 import genno
 from genno import Quantity

genno/compat/sphinx/rewrite_refs.py

@@ -4,7 +4,8 @@
 """
 
 import re
-from typing import TYPE_CHECKING, Mapping, Optional
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Optional
 
 from docutils.nodes import Text
 from sphinx.addnodes import pending_xref

genno/compat/xarray.py

@@ -1,19 +1,8 @@
 """Compatibility with :mod:`xarray`."""
 
 from abc import abstractmethod
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Callable,
-    Hashable,
-    Iterable,
-    Mapping,
-    Optional,
-    Protocol,
-    Sequence,
-    TypeVar,
-    Union,
-)
+from collections.abc import Callable, Hashable, Iterable, Mapping, Sequence
+from typing import TYPE_CHECKING, Any, Optional, Protocol, TypeVar, Union
 
 import numpy as np
 import pandas as pd

genno/config.py

@@ -1,18 +1,10 @@
 import logging
+from collections.abc import Callable, Iterable, Mapping, MutableMapping, Sequence
 from copy import copy
 from dataclasses import dataclass
 from functools import partial
 from pathlib import Path
-from typing import (
-    Any,
-    Callable,
-    Iterable,
-    Mapping,
-    MutableMapping,
-    Optional,
-    Sequence,
-    Union,
-)
+from typing import Any, Optional, Union
 from warnings import warn
 
 from genno import operator

genno/core/attrseries.py

@@ -1,18 +1,8 @@
 import logging
+from collections.abc import Callable, Hashable, Iterable, Mapping, Sequence
 from functools import partial
 from itertools import tee
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Callable,
-    Hashable,
-    Iterable,
-    Mapping,
-    Optional,
-    Sequence,
-    Union,
-    cast,
-)
+from typing import TYPE_CHECKING, Any, Optional, Union, cast
 
 import numpy as np
 import pandas as pd
@@ -533,8 +523,10 @@ def sum(
         if skipna is not None or min_count is not None:
             raise NotImplementedError
 
-        if dim is None or isinstance(dim, Hashable):
-            dim = tuple(filter(None, (dim,)))
+        if dim is Ellipsis:
+            dim = []
+        elif dim is None or isinstance(dim, Hashable):
+            dim = list(filter(None, (dim,)))
 
         # Check dimensions
         bad_dims = set(dim) - set(self.index.names)

genno/core/base.py

@@ -1,19 +1,8 @@
 import operator
 from abc import abstractmethod
+from collections.abc import Hashable, Mapping, MutableMapping, Sequence
 from numbers import Number
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Generic,
-    Hashable,
-    Mapping,
-    MutableMapping,
-    Optional,
-    Sequence,
-    TypeVar,
-    Union,
-    cast,
-)
+from typing import TYPE_CHECKING, Any, Generic, Optional, TypeVar, Union, cast
 
 import numpy as np
 import pandas as pd

genno/core/computer.py

@@ -1,24 +1,20 @@
 import logging
 import types
 from collections import deque
-from functools import lru_cache, partial
-from importlib import import_module
-from inspect import signature
-from itertools import compress
-from pathlib import Path
-from typing import (
-    TYPE_CHECKING,
-    Any,
+from collections.abc import (
     Callable,
     Hashable,
     Iterable,
     Mapping,
     MutableSequence,
-    Optional,
     Sequence,
-    Union,
-    cast,
 )
+from functools import lru_cache, partial
+from importlib import import_module
+from inspect import signature
+from itertools import compress
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Optional, Union, cast
 from warnings import catch_warnings, warn
 
 import dask

genno/core/describe.py

@@ -1,8 +1,8 @@
-from collections.abc import Hashable
+from collections.abc import Hashable, Mapping
 from functools import partial
 from itertools import chain
 from textwrap import shorten
-from typing import Any, Mapping
+from typing import Any
 
 import xarray as xr
 from dask.core import literal

genno/core/graph.py

@@ -1,7 +1,7 @@
-from collections.abc import Generator, Sequence
+from collections.abc import Generator, Iterable, Sequence
 from itertools import chain, tee
 from operator import itemgetter
-from typing import Any, Iterable, Optional, Union
+from typing import Any, Optional, Union
 
 from .key import Key, KeyLike
 

genno/core/key.py

@@ -1,20 +1,10 @@
 import logging
 import re
+from collections.abc import Callable, Generator, Hashable, Iterable, Iterator, Sequence
 from functools import partial, singledispatch
 from itertools import chain, compress
 from types import MappingProxyType
-from typing import (
-    TYPE_CHECKING,
-    Callable,
-    Generator,
-    Hashable,
-    Iterable,
-    Iterator,
-    Optional,
-    Sequence,
-    SupportsInt,
-    Union,
-)
+from typing import TYPE_CHECKING, Optional, SupportsInt, Union
 from warnings import warn
 
 from .attrseries import AttrSeries

genno/core/operator.py

@@ -1,6 +1,7 @@
+from collections.abc import Callable
 from functools import update_wrapper
 from inspect import signature
-from typing import Any, Callable, ClassVar, Optional, Union
+from typing import Any, ClassVar, Optional, Union
 from warnings import warn
 
 from .computer import Computer

genno/core/quantity.py

@@ -6,6 +6,7 @@
 from .sparsedataarray import SparseDataArray
 
 if TYPE_CHECKING:
+    # TODO Remove this block once Python 3.10 is the lowest supported version
     from typing import TypeAlias
 
 

genno/core/sparsedataarray.py

@@ -1,5 +1,6 @@
 import logging
-from typing import Any, Hashable, Mapping, Optional, Sequence, Union
+from collections.abc import Hashable, Mapping, Sequence
+from typing import Any, Optional, Union
 from warnings import filterwarnings
 
 import numpy as np

genno/operator.py

@@ -6,22 +6,12 @@
 import operator
 import os
 import re
+from collections.abc import Callable, Collection, Hashable, Iterable, Mapping
 from functools import partial, reduce, singledispatch
 from itertools import chain
 from os import PathLike
 from pathlib import Path
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Callable,
-    Collection,
-    Hashable,
-    Iterable,
-    Mapping,
-    Optional,
-    Union,
-    cast,
-)
+from typing import TYPE_CHECKING, Any, Optional, Union, cast
 
 import pandas as pd
 import pint
@@ -770,7 +760,7 @@ def _load_file_csv(
 
         # - Drop columns not mentioned in *dims*
         # - Rename columns according to *dims*
-        data = data.drop(columns=set(index_columns) - set(dims.keys())).rename(
+        data = data.drop(columns=list(set(index_columns) - set(dims.keys()))).rename(
             columns=dims
         )
 

genno/tests/core/test_quantity.py

@@ -583,6 +583,13 @@ def test_squeeze1(self, foo, dim, exc_type, match) -> None:
         with pytest.raises(exc_type, match=match):
             print(foo.squeeze(dim=dim))
 
+    def test_sum(self, foo) -> None:
+        """:meth:`.sum` handles :any:`Ellipsis`."""
+        assert_qty_equal(
+            foo.sum(["a", "b"]),
+            foo.sum(...),
+        )
+
     def test_to_dataframe(self, a) -> None:
         """Test Quantity.to_dataframe()."""
         # Returns pd.DataFrame

genno/tests/test_operator.py

@@ -1,9 +1,9 @@
 import logging
 import random
 import re
+from collections.abc import Hashable, Iterable, Mapping
 from contextlib import nullcontext
 from functools import partial
-from typing import Hashable, Iterable, Mapping
 
 import numpy as np
 import pandas as pd