refactor: fix deprecation warnings and typo in encoders

- Remove module warning, use lazy imports, fix stacklevels
- Rename calc_pariwise_coo_indices → calc_pairwise_coo_indices
- Zero warnings for normal usage, proper warnings for deprecated code

Author: theo-barfoot

torchsparsegradutils/encoders/__init__.py

@@ -1,14 +1,44 @@
 # Import from the new pairwise_encoder module (recommended)
 from .pairwise_encoder import PairwiseEncoder, calc_pairwise_coo_indices_nd
 
-# Import from the deprecated pairwise_voxel_encoder module for backward compatibility
-from .pairwise_voxel_encoder import PairwiseVoxelEncoder, calc_pariwise_coo_indices
+
+def __getattr__(name):
+    """Lazy-load deprecated aliases to avoid import-time warnings."""
+    if name == "PairwiseVoxelEncoder":
+        # Import without warning here - the class itself will warn when instantiated
+        from .pairwise_voxel_encoder import PairwiseVoxelEncoder
+
+        return PairwiseVoxelEncoder
+    elif name == "calc_pairwise_coo_indices":
+        import warnings
+
+        warnings.warn(
+            "calc_pairwise_coo_indices is deprecated and will be removed in a future version. "
+            "Use calc_pairwise_coo_indices_nd instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from .pairwise_encoder import calc_pairwise_coo_indices
+
+        return calc_pairwise_coo_indices
+    elif name == "calc_pariwise_coo_indices":
+        import warnings
+
+        warnings.warn(
+            "calc_pariwise_coo_indices (typo) is deprecated and will be removed in a future version. "
+            "Use calc_pairwise_coo_indices_nd instead. "
+            "Note: This function name contains a typo; use calc_pairwise_coo_indices for the corrected spelling.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from .pairwise_encoder import calc_pariwise_coo_indices
+
+        return calc_pariwise_coo_indices
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
 
 __all__ = [
     # New recommended classes and functions
     "PairwiseEncoder",
     "calc_pairwise_coo_indices_nd",
-    # Deprecated but maintained for backward compatibility
-    "PairwiseVoxelEncoder",
-    "calc_pariwise_coo_indices",
 ]

torchsparsegradutils/encoders/pairwise_encoder.py

@@ -505,7 +505,7 @@ def calc_pairwise_coo_indices_nd(
     return indices
 
 
-def calc_pariwise_coo_indices(
+def calc_pairwise_coo_indices(
     radius: float,
     volume_shape: Tuple[int, int, int, int],
     diag: bool = False,
@@ -548,13 +548,17 @@ def calc_pariwise_coo_indices(
     """
     # Validate 4D shape for backward compatibility
     if not (len(volume_shape) == 4 and all(isinstance(dim, int) and dim > 0 for dim in volume_shape)):
-        raise ValueError("volume_shape must be a 4D tuple of positive integers for backward compatibility")
+        raise ValueError("`volume_shape` must be a 4D tuple of positive integers, representing [C, H, D, W]")
 
     out = calc_pairwise_coo_indices_nd(radius, volume_shape, diag, upper, channel_voxel_relation, dtype, device)
     # Narrow key type for static checker (all offsets have length 4 here)
     return {tuple(k): v for k, v in out.items()}  # type: ignore[return-value]
 
 
+# Keep the typo version for backward compatibility
+calc_pariwise_coo_indices = calc_pairwise_coo_indices  # type: ignore[misc]
+
+
 class PairwiseEncoder(torch.nn.Module):
     r"""Encode pairwise spatial–channel neighborhoods as sparse tensors.
 

torchsparsegradutils/encoders/pairwise_voxel_encoder.py

@@ -3,24 +3,17 @@
 
 import torch
 
-# Deprecation warning for the entire module
-warnings.warn(
-    "The 'pairwise_voxel_encoder' module is deprecated and will be removed in a future version. "
-    "Please use 'pairwise_encoder' instead, which provides the same functionality with support for arbitrary N-dimensional spatial relationships.",
-    DeprecationWarning,
-    stacklevel=2,
-)
-
 # Import everything from the new module for backward compatibility
+from .pairwise_encoder import calc_pariwise_coo_indices  # typo version for backward compatibility
 from .pairwise_encoder import (
     PairwiseEncoder,
     _gen_coords,
     _gen_coords_nd,
     _gen_offsets,
     _gen_offsets_nd,
     _trim_nd,
+    calc_pairwise_coo_indices,
     calc_pairwise_coo_indices_nd,
-    calc_pariwise_coo_indices,
 )
 
 
@@ -105,7 +98,7 @@ def __init__(
             "PairwiseVoxelEncoder is deprecated and will be removed in a future version. "
             "Use PairwiseEncoder instead, which supports arbitrary N-dimensional spatial relationships.",
             DeprecationWarning,
-            stacklevel=2,
+            stacklevel=3,
         )
 
         # Validate input for backward compatibility