arraybridge 0.3.0__tar.gz → 0.3.2__tar.gz

{arraybridge-0.3.0 → arraybridge-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arraybridge
-Version: 0.3.0
+Version: 0.3.2
 Summary: Unified API for NumPy, CuPy, PyTorch, TensorFlow, JAX, and pyclesperanto with automatic memory type conversion
 Project-URL: Homepage, https://github.com/OpenHCSDev/arraybridge
 Project-URL: Documentation, https://arraybridge.readthedocs.io
@@ -23,6 +23,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: metaclass-registry>=0.1.5
 Requires-Dist: numpy>=1.20
+Requires-Dist: python-introspect>=0.1.11
 Provides-Extra: all
 Requires-Dist: cupy>=10.0; extra == 'all'
 Requires-Dist: jax>=0.3; extra == 'all'

{arraybridge-0.3.0 → arraybridge-0.3.2}/docs/source/api_reference.rst

@@ -12,6 +12,11 @@ Public imports
 ``detect_memory_type`` and ``convert_memory``
   Detection and explicit conversion.
 
+``ArrayGeometry``
+  Framework-neutral shape inspection for arrays and nominal ``ArrayPayload``
+  values. Geometry inspection reads declared shape metadata and does not move
+  device data to host memory.
+
 ``memory_types``, ``numpy``, ``cupy``, ``torch``, ``tensorflow``, ``jax``, ``pyclesperanto``
   Callable memory declarations and wrappers.
 

{arraybridge-0.3.0 → arraybridge-0.3.2}/docs/source/conf.py

@@ -22,7 +22,7 @@ sys.path.insert(0, str(PACKAGE_ROOT / "src"))
 project = 'arraybridge'
 copyright = '2025, Tristan Simas'
 author = 'Tristan Simas'
-release = '0.3.0'
+release = '0.3.1'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

{arraybridge-0.3.0 → arraybridge-0.3.2}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arraybridge"
-version = "0.3.0"
+version = "0.3.2"
 description = "Unified API for NumPy, CuPy, PyTorch, TensorFlow, JAX, and pyclesperanto with automatic memory type conversion"
 authors = [{name = "Tristan Simas", email = "tristan.simas@mail.mcgill.ca"}]
 license = {text = "MIT"}
@@ -25,7 +25,11 @@ classifiers = [
 ]
 keywords = ["numpy", "cupy", "pytorch", "tensorflow", "jax", "gpu", "array", "tensor", "conversion"]
 
-dependencies = ["numpy>=1.20", "metaclass-registry>=0.1.5"]
+dependencies = [
+    "numpy>=1.20",
+    "metaclass-registry>=0.1.5",
+    "python-introspect>=0.1.11",
+]
 
 [project.optional-dependencies]
 cupy = ["cupy>=10.0"]

{arraybridge-0.3.0 → arraybridge-0.3.2}/src/arraybridge/__init__.py

@@ -5,9 +5,10 @@ This package provides automatic memory type conversion, declarative decorators,
 and unified utilities for working with multiple array/tensor frameworks.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"
 
 from . import decorators as _decorators
+from .array_geometry import ArrayGeometry
 from .array_payload import ArrayPayload
 from .converters import convert_memory, detect_memory_type
 from .dtype_scaling import SCALING_FUNCTIONS
@@ -39,6 +40,7 @@ __all__ = [
     "MemoryType",
     "MemoryContractAttribute",
     "ArrayPayload",
+    "ArrayGeometry",
     "CPU_MEMORY_TYPES",
     "GPU_MEMORY_TYPES",
     "SUPPORTED_MEMORY_TYPES",

arraybridge-0.3.2/src/arraybridge/array_geometry.py

@@ -0,0 +1,57 @@
+"""Framework-neutral array geometry inspection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+from arraybridge.array_payload import ArrayPayload
+
+
+@dataclass(frozen=True, slots=True)
+class ArrayGeometry:
+    """Concrete shape metadata without moving array data between frameworks."""
+
+    shape: tuple[int, ...]
+
+    @property
+    def ndim(self) -> int:
+        """Return the rank derived from the canonical shape."""
+
+        return len(self.shape)
+
+    @classmethod
+    def from_value(cls, value: Any) -> ArrayGeometry | None:
+        """Inspect an array or nominal payload without forcing host conversion."""
+
+        data = value.array_payload_data() if isinstance(value, ArrayPayload) else value
+        declared_shape = getattr(data, "shape", None)
+        if declared_shape is not None:
+            try:
+                return cls(tuple(int(axis_size) for axis_size in declared_shape))
+            except (TypeError, ValueError):
+                return None
+
+        try:
+            array = np.asarray(data)
+        except (TypeError, ValueError):
+            return None
+        return cls(tuple(int(axis_size) for axis_size in array.shape))
+
+    @classmethod
+    def require_from_value(
+        cls,
+        value: Any,
+        *,
+        value_name: str = "Value",
+    ) -> ArrayGeometry:
+        """Return concrete geometry or reject a value without an array shape."""
+
+        geometry = cls.from_value(value)
+        if geometry is None:
+            raise TypeError(
+                f"{value_name} requires concrete array geometry, got " f"{type(value).__name__}."
+            )
+        return geometry

{arraybridge-0.3.0 → arraybridge-0.3.2}/src/arraybridge/decorators.py

@@ -23,6 +23,7 @@ from typing import Any, ClassVar, TypeVar, cast
 
 import numpy as np
 from metaclass_registry import AutoRegisterMeta, RegistryFamily, RegistryKeyAttribute
+from python_introspect import RuntimeParameterDeclarationABC
 
 from arraybridge.array_payload import ArrayPayload
 from arraybridge.oom_recovery import _execute_with_oom_recovery
@@ -60,7 +61,7 @@ class DtypeConversion(Enum):
         return dtype_map.get(self, None)
 
 
-class DtypeConversionConfig(ABC):
+class DtypeConversionConfig(RuntimeParameterDeclarationABC):
     """Nominal dtype conversion config surface consumed by decorators."""
 
     @property
@@ -90,7 +91,7 @@ class DtypeConversionConfig(ABC):
         )
 
 
-class SliceBySliceRuntimeParameter:
+class SliceBySliceRuntimeParameter(RuntimeParameterDeclarationABC):
     """Nominal slice-by-slice execution parameter consumed by decorators."""
 
     preserve_for_execution = True

arraybridge-0.3.2/tests/test_array_geometry.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from arraybridge import ArrayGeometry, ArrayPayload
+
+
+class DeviceArray:
+    """Array-shaped value that rejects implicit host conversion."""
+
+    shape = (2, 3, 4)
+
+    def __array__(self, dtype=None):
+        del dtype
+        raise TypeError("implicit host conversion is forbidden")
+
+
+class DevicePayload(ArrayPayload):
+    def __init__(self, data):
+        self.data = data
+
+    def array_payload_data(self):
+        return self.data
+
+    def with_data(self, data):
+        return type(self)(data)
+
+
+def test_array_geometry_reads_declared_device_shape_without_host_conversion() -> None:
+    assert ArrayGeometry.from_value(DeviceArray()) == ArrayGeometry((2, 3, 4))
+
+
+def test_array_geometry_unwraps_nominal_array_payload() -> None:
+    assert ArrayGeometry.from_value(DevicePayload(DeviceArray())) == ArrayGeometry((2, 3, 4))
+
+
+def test_array_geometry_falls_back_for_python_array_inputs() -> None:
+    assert ArrayGeometry.from_value([[1, 2], [3, 4]]) == ArrayGeometry((2, 2))
+    assert ArrayGeometry.from_value(np.zeros((4, 5))) == ArrayGeometry((4, 5))
+
+
+def test_array_geometry_requires_concrete_shape() -> None:
+    class UnshapedValue:
+        def __array__(self, dtype=None):
+            del dtype
+            raise TypeError("not an array")
+
+    with pytest.raises(TypeError, match="Runtime output requires concrete array geometry"):
+        ArrayGeometry.require_from_value(
+            UnshapedValue(),
+            value_name="Runtime output",
+        )

{arraybridge-0.3.0 → arraybridge-0.3.2}/tests/test_decorators.py

@@ -6,6 +6,7 @@ from typing import Any
 
 import numpy as np
 import pytest
+from python_introspect import RuntimeParameterDeclarationABC
 
 from arraybridge import ArrayPayload
 from arraybridge.decorators import (
@@ -33,6 +34,13 @@ class TestDtypeConversion:
         assert DtypeConversion.UINT8.value == "uint8"
         assert DtypeConversion.UINT16.value == "uint16"
         assert DtypeConversion.INT16.value == "int16"
+
+    def test_runtime_parameters_are_nominal_declarations(self):
+        assert issubclass(DtypeConversionConfig, RuntimeParameterDeclarationABC)
+        assert issubclass(
+            SliceBySliceRuntimeParameter,
+            RuntimeParameterDeclarationABC,
+        )
         assert DtypeConversion.INT32.value == "int32"
         assert DtypeConversion.FLOAT32.value == "float32"
         assert DtypeConversion.FLOAT64.value == "float64"