Merge pull request #204 from csiro-coasts/pep-695-generics

Use PEP 695 generics

Author: mx-moth

docs/api/conventions/interface.rst

@@ -7,6 +7,8 @@ Convention interface
 .. contents::
    :local:
 
+.. currentmodule:: emsarray.conventions
+
 Each supported convention implements
 the :class:`~emsarray.conventions.Convention` interface.
 
@@ -25,8 +27,37 @@ the :class:`~emsarray.conventions.Convention` interface.
 .. autoclass:: emsarray.conventions.SpatialIndexItem
    :members:
 
-.. autodata:: emsarray.conventions._base.GridKind
-.. autodata:: emsarray.conventions._base.Index
+.. type:: GridKind
+
+    Some type that can enumerate the different :ref:`grid types <grids>`
+    present in a dataset.
+    This can be an :class:`enum.Enum` listing each different kind of grid.
+
+    :type:`Index` values will be included in the feature properties
+    of exported geometry from :mod:`emsarray.operations.geometry`.
+    If the index type includes the grid kind,
+    the grid kind needs to be JSON serializable.
+    The easiest way to achieve this is to make your GridKind type subclass :class:`str`:
+
+    .. code-block:: python
+
+        class MyGridKind(str, enum.Enum):
+            face = 'face'
+            edge = 'edge'
+            node = 'node'
+
+    For cases where the convention only supports a single grid,
+    a singleton enum can be used.
+
+    More esoteric cases involving datasets with a potentially unbounded numbers of grids
+    can use a type that supports this instead.
+
+.. type:: Index
+
+    An :ref:`index <indexing>` to a specific point on a grid in this convention.
+    For conventions with :ref:`multiple grids <grids>` (e.g. cells, edges, and nodes),
+    this should be a tuple whos first element is :type:`.GridKind`.
+    For conventions with a single grid, :type:`.GridKind` is not required.
 
 .. autoclass:: emsarray.conventions.Specificity
    :members:

docs/concepts/grids.rst

@@ -19,7 +19,7 @@ from one face to another.
 These edges represent another grid.
 Some conventions also define variables on face vertices, called *nodes*.
 Nodes represent a third grid.
-This is represented by the :data:`~.conventions._base.GridKind` type variable.
+This is represented by the :type:`~.conventions.GridKind` type variable.
 
 Each of the faces, edges, and nodes define an area, line, or point.
 These areas, lines, or points exist at some geographic location.

docs/concepts/indexing.rst

@@ -16,7 +16,7 @@ As each geometry convention may define a different number of grids,
 each convention has a different method of indexing data in these grids.
 These are the *convention native indexes*.
 Each :class:`~.conventions.Convention` implementation
-has its own :data:`~.conventions._base.Index` type.
+has its own :type:`~.conventions.Index` type.
 
 :mod:`CF grid datasets <.conventions.grid>` have only one grid - faces.
 Each face can be indexed using two numbers *x* and *y*.

docs/releases/development.rst

@@ -18,3 +18,9 @@ Next release (in development)
   ``spatial_index()``, ``get_grid_kind_and_size()``,
   and ``NonIntersectingPoints.indices``
   (:pr:`202`).
+* Use `PEP 695 <https://peps.python.org/pep-0695/>`_ style type parameters.
+  This drops the `Index` and `GridKind` type variables
+  which were exported in `emsarray.conventions`,
+  which is a backwards incompatible change
+  but is difficult to add meaningful backwards compatible support
+  (:issue:`109`, :pr:`203`)

src/emsarray/cli/commands/plot.py

@@ -3,23 +3,30 @@
 import logging
 from collections.abc import Callable
 from pathlib import Path
-from typing import Any, TypeVar
+from typing import Any, overload
 
 import emsarray
 from emsarray.cli import BaseCommand, CommandException
 
-T = TypeVar('T')
-
 logger = logging.getLogger(__name__)
 
 
-def key_value(arg: str, value_type: Callable = str) -> dict[str, T]:
+@overload
+def key_value(arg: str) -> dict[str, str]: ...  # noqa: E704
+@overload
+def key_value[T](arg: str, value_type: Callable[[str], T]) -> dict[str, T]: ...  # noqa: E704
+
+
+def key_value[T](arg: str, value_type: Callable[[str], T] | None = None) -> dict[str, T] | dict[str, str]:
     try:
         name, value = arg.split("=", 2)
     except ValueError:
         raise argparse.ArgumentTypeError(
             "Coordinate / dimension indexes must be given as `name=value` pairs")
-    return {name: value_type(value)}
+    if value_type is None:
+        return {name: value}
+    else:
+        return {name: value_type(value)}
 
 
 class UpdateDict(argparse.Action):

src/emsarray/conventions/__init__.py

@@ -14,8 +14,7 @@
 Refer to each Convention implementation for details.
 """
 from ._base import (
-    Convention, DimensionConvention, GridKind, Index, SpatialIndexItem,
-    Specificity
+    Convention, DimensionConvention, SpatialIndexItem, Specificity
 )
 from ._registry import get_dataset_convention, register_convention
 from ._utils import open_dataset
@@ -25,7 +24,7 @@
 from .ugrid import UGrid
 
 __all__ = [
-    "Convention", "DimensionConvention", "GridKind", "Index",
+    "Convention", "DimensionConvention",
     "SpatialIndexItem", "Specificity",
     "get_dataset_convention", "register_convention",
     "open_dataset",

src/emsarray/conventions/_base.py

@@ -6,7 +6,7 @@
 import warnings
 from collections.abc import Callable, Hashable, Iterable, Sequence
 from functools import cached_property
-from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Literal, cast
 
 import numpy
 import shapely
@@ -38,39 +38,8 @@
 logger = logging.getLogger(__name__)
 
 
-#: Some type that can enumerate the different :ref:`grid types <grids>`
-#: present in a dataset.
-#: This can be an :class:`enum.Enum` listing each different kind of grid.
-#:
-#: :data:`Index` values will be included in the feature properties
-#: of exported geometry from :mod:`emsarray.operations.geometry`.
-#: If the index type includes the grid kind,
-#: the grid kind needs to be JSON serializable.
-#: The easiest way to achieve this is to make your GridKind type subclass :class:`str`:
-#:
-#: .. code-block:: python
-#:
-#:     class MyGridKind(str, enum.Enum):
-#:         face = 'face'
-#:         edge = 'edge'
-#:         node = 'node'
-#:
-#: For cases where the convention only supports a single grid,
-#: a singleton enum can be used.
-#:
-#: More esoteric cases involving datasets with a potentially unbounded numbers of grids
-#: can use a type that supports this instead.
-GridKind = TypeVar("GridKind")
-
-#: An :ref:`index <indexing>` to a specific point on a grid in this convention.
-#: For conventions with :ref:`multiple grids <grids>` (e.g. cells, edges, and nodes),
-#: this should be a tuple whos first element is :data:`.GridKind`.
-#: For conventions with a single grid, :data:`.GridKind` is not required.
-Index = TypeVar("Index")
-
-
 @dataclasses.dataclass
-class SpatialIndexItem(Generic[Index]):
+class SpatialIndexItem[Index]:
     """Information about an item in the :class:`~shapely.strtree.STRtree`
     spatial index for a dataset.
 
@@ -124,7 +93,7 @@ class Specificity(enum.IntEnum):
     HIGH = 30
 
 
-class Convention(abc.ABC, Generic[GridKind, Index]):
+class Convention[GridKind, Index](abc.ABC):
     """
     Each supported geometry convention represents data differently.
     The :class:`Convention` class abstracts these differences away,
@@ -1749,7 +1718,7 @@ def hash_geometry(self, hash: "hashlib._Hash") -> None:
             hash_attributes(hash, data_array.attrs)
 
 
-class DimensionConvention(Convention[GridKind, Index]):
+class DimensionConvention[GridKind, Index](Convention[GridKind, Index]):
     """
     A Convention subclass where different grid kinds
     are always defined on unique sets of dimension.

src/emsarray/conventions/grid.py

@@ -9,7 +9,7 @@
 from collections.abc import Hashable, Sequence
 from contextlib import suppress
 from functools import cached_property
-from typing import Generic, TypeVar, cast
+from typing import cast
 
 import numpy
 import xarray
@@ -183,10 +183,7 @@ def size(self) -> int:
         return int(numpy.prod(self.shape))
 
 
-Topology = TypeVar('Topology', bound=CFGridTopology)
-
-
-class CFGrid(Generic[Topology], DimensionConvention[CFGridKind, CFGridIndex]):
+class CFGrid[Topology: CFGridTopology](DimensionConvention[CFGridKind, CFGridIndex]):
     """
     A base class for CF grid datasets.
     There are two concrete subclasses: :class:`CFGrid1D` and :class:`CFGrid2D`.

src/emsarray/operations/geometry.py

@@ -7,7 +7,7 @@
 import pathlib
 from collections.abc import Generator, Iterable, Iterator
 from contextlib import contextmanager
-from typing import IO, Any, Generic, TypeVar
+from typing import IO, Any
 
 import geojson
 import shapefile
@@ -16,10 +16,8 @@
 
 from emsarray.types import Pathish
 
-T = TypeVar('T')
 
-
-class _dumpable_iterator(Generic[T], list):
+class _dumpable_iterator[T](list):
     """
     Wrap an iterator / generator so it can be used in `json.dumps()`.
     No guarantees that it works for anything else!

src/emsarray/transect.py

@@ -1,7 +1,7 @@
 import dataclasses
 from collections.abc import Callable, Iterable
 from functools import cached_property
-from typing import Any, Generic, cast
+from typing import Any, cast
 
 import cfunits
 import numpy
@@ -16,7 +16,7 @@
 from matplotlib.figure import Figure
 from matplotlib.ticker import EngFormatter, Formatter
 
-from emsarray.conventions import Convention, Index
+from emsarray.conventions import Convention
 from emsarray.plot import _requires_plot, make_plot_title
 from emsarray.types import DataArrayOrName, Landmark
 from emsarray.utils import move_dimensions_to_end, name_to_data_array
@@ -86,7 +86,7 @@ class TransectPoint:
 
 
 @dataclasses.dataclass
-class TransectSegment(Generic[Index]):
+class TransectSegment:
     """
     A TransectSegment holds information about each intersecting segment of the
     transect path and the dataset cells.
@@ -96,7 +96,6 @@ class TransectSegment(Generic[Index]):
     intersection: shapely.LineString
     start_distance: float
     end_distance: float
-    index: Index
     linear_index: int
     polygon: shapely.Polygon
 
@@ -281,7 +280,7 @@ def points(
         return points
 
     @cached_property
-    def segments(self) -> list[TransectSegment[Index]]:
+    def segments(self) -> list[TransectSegment]:
         """
         A list of :class:`.TransectSegmens` for each intersecting segment of the transect line and the dataset geometry.
         Segments are listed in order from the start of the line to the end of the line.
@@ -293,7 +292,6 @@ def segments(self) -> list[TransectSegment[Index]]:
 
         for linear_index in intersecting_indexes:
             polygon = self.convention.polygons[linear_index]
-            index = self.convention.wind_index(linear_index)
             for intersection in self._intersect_polygon(polygon):
                 # The line will have two ends.
                 # The intersection starts and ends at these points.
@@ -314,7 +312,6 @@ def segments(self) -> list[TransectSegment[Index]]:
                     intersection=intersection,
                     start_distance=start[1],
                     end_distance=end[1],
-                    index=index,
                     linear_index=linear_index,
                     polygon=polygon,
                 ))