transformnd 0.2.1__tar.gz → 0.3.0__tar.gz

{transformnd-0.2.1 → transformnd-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: transformnd
-Version: 0.2.1
+Version: 0.3.0
 Summary: ND coordinate transformations
 Author: Chris Barnes
 Author-email: Chris Barnes <chris.barnes@gerbi-gmb.de>

{transformnd-0.2.1 → transformnd-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "transformnd"
-version = "0.2.1"
+version = "0.3.0"
 description = "ND coordinate transformations"
 readme = "README.md"
 authors = [{ name = "Chris Barnes", email = "chris.barnes@gerbi-gmb.de" }]
@@ -56,6 +56,7 @@ lint = [
     "mypy",
     "prek>=0.3.9",
     "types-shapely>=2.1.0.20260408",
+    "pydoclint>=0.8.6",
 ]
 doc = [
     "pdoc>=16.0.0",
@@ -80,3 +81,13 @@ check_untyped_defs = true
 [tool.pytest]
 testpaths = ["tests", "bench"]
 addopts = ["--benchmark-skip"]
+
+[tool.pydoclint]
+arg-type-hints-in-docstring = false
+allow-init-docstring = true
+
+[tool.ruff]
+lint.external = [
+    "DOC",  # pydoclint
+    "D",  # pydocstyle
+]

{transformnd-0.2.1 → transformnd-0.3.0}/src/transformnd/adapters/base.py

@@ -14,22 +14,27 @@ ObjectT = TypeVar("ObjectT")
 
 
 class BaseAdapter[ObjectT, ArrayT](ABC):
+    """Base class for adapters that transform non-array objects."""
+
     @abstractmethod
     def apply(self, transform: Transform[ArrayT], obj: ObjectT) -> ObjectT:
         """Apply the given transformation to a non-array object.
 
         Parameters
         ----------
-        transform : Transform
-        obj : T
+        transform
+            The transformation to apply.
+        obj
+            The object to transform.
 
         Returns
         -------
-        T
+        ObjectT
+            The transformed object.
         """
         pass
 
-    def partial(self, *args, **kwargs) -> Callable[..., ObjectT]:
+    def partial(self, *args: Any, **kwargs: Any) -> Callable[..., ObjectT]:
         """Create a partial function with frozen arguments.
 
         Useful for applying the same transform to many objects,
@@ -37,9 +42,17 @@ class BaseAdapter[ObjectT, ArrayT](ABC):
         or for adapters with additional arguments,
         using the same config repeatedly.
 
+        Parameters
+        ----------
+        *args
+            Positional arguments to freeze.
+        **kwargs
+            Keyword arguments to freeze.
+
         Returns
         -------
-        Callable
+        Callable[..., ObjectT]
+            A partial function with the given arguments frozen.
         """
         return partial(self.apply, *args, **kwargs)
 
@@ -52,15 +65,16 @@ class NullAdapter(BaseAdapter[ArrayT, ArrayT]):
 
 
 class FnAdapter(BaseAdapter[ObjectT, ArrayT]):
-    def __init__(self, fn: Callable[[Transform[ArrayT], ObjectT], ObjectT]):
-        """Adapter which simply wraps a function, for typing purposes.
+    """Adapter which simply wraps a function, for typing purposes.
 
-        Parameters
-        ----------
-        fn : Callable[[Transform, T], T]
-            Function which takes the object,
-            and applies the transformation to it.
-        """
+    Parameters
+    ----------
+    fn
+        Function which takes the object,
+        and applies the transformation to it.
+    """
+
+    def __init__(self, fn: Callable[[Transform[ArrayT], ObjectT], ObjectT]):
         self.fn = fn
 
     def apply(self, transform: Transform[ArrayT], obj: ObjectT) -> ObjectT:
@@ -68,18 +82,19 @@ class FnAdapter(BaseAdapter[ObjectT, ArrayT]):
 
 
 class AttrAdapter(BaseAdapter[ObjectT, ArrayT]):
-    def __init__(self, **kwargs: BaseAdapter[Any, ArrayT] | None) -> None:
-        """Adapter which transforms an object by applying transforms to its attributes.
+    """Adapter which transforms an object by applying transforms to its attributes.
+
+    Parameters
+    ----------
+    **kwargs
+        Keys are attribute names, values are adapters with which
+        to apply the transform to those attributes.
+        `None` is shorthand for `NullAdapter()`;
+        i.e. the attribute is an array and can be transformed
+        without being adapted.
+    """
 
-        Parameters
-        ----------
-        adapters : Dict[str, Optional[BaseAdapter]]
-            Keys are attribute names, values are adapters with which
-            to apply the transform to those attributes.
-            `None` is shorthand for `NullAdapter()`;
-            i.e. the attribute is an array and can be transformed
-            without being adapted.
-        """
+    def __init__(self, **kwargs: BaseAdapter[Any, ArrayT] | None) -> None:
         self.adapters = {
             k: NullAdapter[ArrayT]() if v is None else v for k, v in kwargs.items()
         }
@@ -91,15 +106,23 @@ class AttrAdapter(BaseAdapter[ObjectT, ArrayT]):
 
         Parameters
         ----------
-        transform : Transform
-        obj : T
-        in_place : bool, optional
+        transform
+            The transformation to apply.
+        obj
+            The object to transform.
+        in_place
             Whether to mutate the given object in place,
             by default False (i.e. make a deep copy of it).
 
         Returns
         -------
-        T
+        ObjectT
+            The transformed object.
+
+        Raises
+        ------
+        TypeError
+            If the adapter does not support the in_place argument.
         """
         if not in_place:
             obj = deepcopy(obj)
@@ -147,7 +170,7 @@ class ReshapeAdapter(BaseAdapter[ArrayT, ArrayT]):
 
         Parameters
         ----------
-        dim_axis : int, optional
+        dim_axis
             Which axis contains the coordinates' dimensions,
             by default -1 (last)
         """

{transformnd-0.2.1 → transformnd-0.3.0}/src/transformnd/adapters/pandas.py

@@ -15,7 +15,7 @@ class PandasAdapter(BaseAdapter[pd.DataFrame, np.ndarray]):
 
         Parameters
         ----------
-        columns : list of keys
+        columns
             Keys for columns containing coordinates, e.g. `["x", "y", "z"]`
         """
         self.columns = columns
@@ -27,16 +27,18 @@ class PandasAdapter(BaseAdapter[pd.DataFrame, np.ndarray]):
 
         Parameters
         ----------
-        transform : Transform
-        df : pd.DataFrame
-
-        in_place : bool, optional
+        transform
+            The transformation to apply.
+        df
+            The DataFrame to transform.
+        in_place
             Whether to mutate the dataframe in place,
             by default False (i.e. make a copy of it).
 
         Returns
         -------
-        pandas.DataFrame
+        pd.DataFrame
+            The transformed DataFrame.
         """
         coords = df[self.columns].to_numpy()
         transformed = transform.apply(coords)

{transformnd-0.2.1 → transformnd-0.3.0}/src/transformnd/adapters/polars.py

@@ -13,7 +13,7 @@ class PolarsAdapter(BaseAdapter[pl.DataFrame, np.ndarray]):
 
         Parameters
         ----------
-        columns : list of keys
+        columns
             Keys for columns containing coordinates, e.g. `["x", "y", "z"]`
         """
         self.columns = columns
@@ -25,16 +25,18 @@ class PolarsAdapter(BaseAdapter[pl.DataFrame, np.ndarray]):
 
         Parameters
         ----------
-        transform : Transform
-        df : pl.DataFrame
-
-        in_place : bool, optional
+        transform
+            The transformation to apply.
+        df
+            The DataFrame to transform.
+        in_place
             Whether to mutate the dataframe in place,
             by default False (i.e. make a copy of it).
 
         Returns
         -------
-        pandas.DataFrame
+        pl.DataFrame
+            The transformed DataFrame.
         """
         coords = df[self.columns].to_numpy()
         transformed = transform.apply(coords)

{transformnd-0.2.1 → transformnd-0.3.0}/src/transformnd/adapters/shapely.py

@@ -96,19 +96,25 @@ class GeometryAdapter(BaseAdapter[BaseGeometry, ArrayT]):
     ) -> BaseGeometry:
         """Transform the shapely geometry.
 
-        See the other `apply_*` methods if you already know what type of geometry you're working with;
-        this may be a bit faster.
+        See the other `apply_*` methods if you already know what type of geometry
+        you're working with; this may be a bit faster.
 
         Parameters
         ----------
-        transform : Transform
-        obj : BaseGeometry
+        transform
+            The transformation to apply.
+        obj
             Some shapely geometry in 2 or 3D
 
         Returns
         -------
         BaseGeometry
             An object of the same type as the input.
+
+        Raises
+        ------
+        ValueError
+            If the geometry type is not supported.
         """
         if isinstance(obj, BaseMultipartGeometry):
             return self.apply_multipart(transform, obj)

{transformnd-0.2.1 → transformnd-0.3.0}/src/transformnd/base.py

@@ -6,6 +6,7 @@ from abc import ABC, abstractmethod
 from collections.abc import Iterator, Sequence
 from copy import copy
 from typing import Self, TYPE_CHECKING
+from types import ModuleType
 
 from array_api_compat import array_namespace
 
@@ -35,6 +36,8 @@ class Transform[ArrayT](ABC):
         """
         Parameters
         ----------
+        ndims
+            Source and target dimensionality.
         spaces
             Optional source and target spaces
         """
@@ -50,7 +53,7 @@ class Transform[ArrayT](ABC):
 
         Returns
         -------
-        Transform | None:
+        Affine[ArrayT] | None
             The affine transformation, if conversion is possible.
             None otherwise.
         """
@@ -63,9 +66,14 @@ class Transform[ArrayT](ABC):
 
         Parameters
         ----------
-        coords : ArrayT
+        coords
             NxD array of N D-dimensional coordinates.
 
+        Returns
+        -------
+        ArrayT
+            The validated coordinates.
+
         Raises
         ------
         ValueError
@@ -87,12 +95,12 @@ class Transform[ArrayT](ABC):
 
         Parameters
         ----------
-        coords : ArrayT
+        coords
             NxD array of N D-dimensional coordinates.
 
         Returns
         -------
-        np.ndarray
+        ArrayT
             Transformed coordinates in the same shape.
         """
         pass
@@ -116,7 +124,7 @@ class Transform[ArrayT](ABC):
             return NotImplemented
         return t
 
-    def to_device(self, xp, device=None) -> Self:  # noqa: ARG002
+    def to_device(self, xp: ModuleType, device: str | None = None) -> Self:  # noqa: ARG002
         """Return a copy of this transform with array parameters placed on the given device.
 
         Useful for pre-allocating parameters on GPU before a tight apply() loop,
@@ -124,15 +132,15 @@ class Transform[ArrayT](ABC):
 
         Parameters
         ----------
-        xp : array namespace
+        xp
             The target array namespace (e.g. jax.numpy, torch).
-        device : device object, optional
+        device
             Target device (e.g. from array_api_compat.device(array)).
             If None, uses xp's default device.
 
         Returns
         -------
-        Transform
+        Self
             A new transform instance with parameters on the target device,
             or NotImplemented if the subclass does not support device placement.
         """
@@ -145,11 +153,13 @@ class Transform[ArrayT](ABC):
 
         Parameters
         ----------
-        other : Transform
+        other
+            The transform to compose with.
 
         Returns
         -------
-        TransformSequence
+        TransformSequence[ArrayT]
+            The composed transform sequence.
         """
         if not isinstance(other, Transform):
             return NotImplemented
@@ -166,11 +176,13 @@ class Transform[ArrayT](ABC):
 
         Parameters
         ----------
-        other : Transform
+        other
+            The transform to compose with.
 
         Returns
         -------
-        TransformSequence
+        TransformSequence[ArrayT]
+            The composed transform sequence.
         """
         if not isinstance(other, Transform):
             return NotImplemented
@@ -205,9 +217,13 @@ class TransformWrapper(Transform[ArrayT]):
 
         Parameters
         ----------
-        fn : TransformSignature
+        fn
             Callable.
-        spaces : tuple[SpaceRef, SpaceRef]
+        in_ndim
+            Dimensionality of the input coordinates.
+        out_ndim
+            Dimensionality of the output coordinates.
+        spaces
             Optional source and target spaces
         """
         super().__init__(NDims(in_ndim, out_ndim), spaces=spaces)
@@ -331,22 +347,23 @@ class TransformSequence(Transform[ArrayT], Sequence[Transform[ArrayT]]):
             coords = t.apply(coords)
         return coords
 
-    def to_device(self, xp, device=None) -> Self:
+    def to_device(self, xp: ModuleType, device: str | None = None) -> Self:
         result = copy(self)
         result.transforms = [t.to_device(xp, device) for t in self.transforms]
         return result
 
-    def list_spaces(self, skip_none=False) -> list[SpaceRef]:
+    def list_spaces(self, skip_none: bool = False) -> list[SpaceRef]:
         """List spaces in this transform.
 
         Parameters
         ----------
-        skip_none : bool, optional
+        skip_none
             Whether to skip undefined spaces, default False.
 
         Returns
         -------
-        List[SpaceRef]
+        list[SpaceRef]
+            The list of spaces.
         """
         spaces = [self.spaces.source] + [t.spaces.target for t in self.transforms]
         if skip_none: