cobra-array 0.1.2__tar.gz → 0.1.4__tar.gz

{cobra_array-0.1.2/src/cobra_array.egg-info → cobra_array-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cobra-array
-Version: 0.1.2
+Version: 0.1.4
 Summary: A backend-agnostic array utility library that unifies array conversion, context control, and cross-library operations across `NumPy`/`PyTorch`-style ecosystems.
 Author-email: Zhen Tian <zhen.tian.cs@gmail.com>
 Project-URL: Homepage, https://github.com/tinchen777/cobra-array.git

{cobra_array-0.1.2 → cobra_array-0.1.4}/src/cobra_array/__init__.py

@@ -12,6 +12,7 @@ Modules
 - :mod:`cobra_array.convert`: Utilities for converting between different array types and namespaces.
 - :mod:`cobra_array.default`: Default utilities for array specifications and namespaces.
 - :mod:`cobra_array.array_api`: Utilities for working with array namespaces and devices.
+
 Functions
 ---------
 - :func:`array_spec`: Get the array specification of an object.
@@ -83,7 +84,7 @@ from ._utils import (
 )
 
 __author__ = "Zhen Tian"
-__version__ = "0.1.2"
+__version__ = "0.1.4"
 
 __all__ = [
     "array_spec",

{cobra_array-0.1.2 → cobra_array-0.1.4}/src/cobra_array/_core.py

@@ -15,7 +15,6 @@ from .default import (ArraySpec, default_spec)
 from .exceptions import (
     NoArrayInputsError,
     GetArrayNamespaceError,
-    MissingDependencyError,
     NotArrayAPIObjectError
 )
 
@@ -25,11 +24,19 @@ if TYPE_CHECKING:
     from .types import (T, dtypeT, DType, AnyDevice, ArrayLike, ArrayLibraryName)
 
 
+def _fallback_default_spec(fallback: bool, exc: Exception, /, from_: Optional[BaseException] = None) -> ArraySpec:
+    """Return the default array specification when fallback is enabled, otherwise re-raise the original exception."""
+    if fallback:
+        return default_spec()
+    raise exc from from_
+
+
 def array_spec(
     *arrays: object,
     kw_arrays: Optional[Dict[str, object]] = None,
     ref: Optional[Union[str, int]] = None,
     filter_arraylike: bool = False,
+    fallback: bool = False,
     api_version: Optional[str] = None,
     use_compat: Optional[bool] = None
 ) -> ArraySpec:
@@ -53,6 +60,11 @@ def array_spec(
         filter_arraylike : bool, default to `False`
             Whether to filter the provided inputs to all array-likes via :func:`array_api_compat.is_array_api_obj` when determining the `compatibility namespace`.
 
+        fallback : bool, default to `False`
+            Whether to fall back to the default `compatibility namespace` when failing to determine the `compatibility namespace` from the provided inputs or the reference array.
+            - `True`: Return the default `compatibility namespace` from :func:`default.default_spec` when an error occurs;
+            - `False`: Raise the original exception when an error occurs.
+
         api_version : Optional[str], default to `None`
             The target array API version for the returned `compatibility namespace`. See also :param:`api_version` in :func:`array_api_compat.array_namespace`.
 
@@ -73,18 +85,22 @@ def array_spec(
 
     Raises
     ------
+        Refer to :func:`default.default_spec` for possible exceptions.
+
         NoArrayInputsError
-            If no array inputs are provided in `arrays` and `kw_arrays`.
+            If no array inputs are provided in `arrays` and `kw_arrays`, and :param:`fallback` is `False`.
         GetArrayNamespaceError
-            If an error occurs while determining the `compatibility namespace` from the provided inputs or the reference array.
+            If an error occurs while determining the `compatibility namespace` from the provided inputs or the reference array, and :param:`fallback` is `False`.
         KeyError
-            If `ref` is a string but not a key in `kw_arrays`.
+            If `ref` is a string but not a key in `kw_arrays`, and :param:`fallback` is `False`.
         IndexError
-            If `ref` is an integer but out of range for the array inputs.
+            If `ref` is an integer but out of range for the array inputs, and :param:`fallback` is `False`.
+        ValueError
+            If `ref` is an integer but negative.
         TypeError
             If `ref` is not `None`, a string, or an integer.
         NotArrayAPIObjectError
-            If the reference array determined by `ref` is not an array API compatible array object.
+            If the reference array determined by `ref` is not an array API compatible array object, and :param:`fallback` is `False`.
 
     Examples
     --------
@@ -116,7 +132,10 @@ def array_spec(
 
     if len(arrays) == 0 and len(kw_arrays) == 0:
         # no arrays provided
-        raise NoArrayInputsError("Expected at least one array input.")
+        return _fallback_default_spec(
+            fallback,
+            NoArrayInputsError("Expected at least one array input.")
+        )
 
     # iterator of all arrays
     all_arrays = chain(arrays, kw_arrays.values())
@@ -134,37 +153,48 @@ def array_spec(
                 ), None, None
             )
         except Exception as e:
-            raise GetArrayNamespaceError(
-                "Failed to determine the `compatibility namespace` from the provided inputs."
-            ) from e
+            return _fallback_default_spec(
+                fallback,
+                GetArrayNamespaceError(
+                    "Failed to determine the `compatibility namespace` from "
+                    "the provided inputs."
+                ), from_=e
+            )
 
     if isinstance(ref, str):
         # use the specified kw_array as reference array to determine the namespace
         try:
             ref_arr = kw_arrays[ref]
         except KeyError:
-            raise KeyError(
-                f"Parameter `ref` of `array_spec()` must be a key in `kw_arrays`, got {ref!r}."
-            ) from None
+            return _fallback_default_spec(
+                fallback,
+                KeyError(
+                    "Parameter `ref` of `array_spec()` must be a key in "
+                    f"`kw_arrays`, got {ref!r}."
+                )
+            )
     elif isinstance(ref, int):
         # use the specified array as reference array to determine the namespace
         try:
             ref_arr = next(islice(all_arrays, ref, ref + 1))
         except ValueError:
-            raise IndexError(
+            raise ValueError(
                     "Parameter `ref` of `array_spec()` must be a "
                     f"non-negative index for the array inputs, got {ref!r}."
                 ) from None
         except StopIteration:
-            if filter_arraylike:
+            try:
+                if filter_arraylike:
+                    raise IndexError(
+                        "Parameter `ref` of `array_spec()` is out of range "
+                        f"for the array-like inputs, got {ref!r}."
+                    ) from None
                 raise IndexError(
-                    "Parameter `ref` of `array_spec()` is out of range "
-                    f"for the array-like inputs, got {ref!r}."
+                    "Parameter `ref` of `array_spec()` must be in the range "
+                    f"[0, {len(arrays) + len(kw_arrays)}) for the array inputs, got {ref!r}."
                 ) from None
-            raise IndexError(
-                "Parameter `ref` of `array_spec()` must be in the range "
-                f"[0, {len(arrays) + len(kw_arrays)}) for the array inputs, got {ref!r}."
-            ) from None
+            except IndexError as e:
+                return _fallback_default_spec(fallback, e)
     else:
         raise TypeError(
             "Parameter `ref` of `array_spec()` must be `str`, "
@@ -172,8 +202,11 @@ def array_spec(
         )
 
     if not filter_arraylike and not api.is_array_api_obj(ref_arr):
-        raise NotArrayAPIObjectError(
-            f"Reference array must be an array API compatible array object, got {ref_arr!r}."
+        return _fallback_default_spec(
+            fallback,
+            NotArrayAPIObjectError(
+                f"Reference array must be an array API compatible array object, got {ref_arr!r}."
+            )
         )
 
     dtype = getattr(ref_arr, "dtype", None)
@@ -187,19 +220,28 @@ def array_spec(
             ), dtype, device
         )
     except Exception as e:
-        raise GetArrayNamespaceError(
-            "Failed to determine the `compatibility namespace` from the reference array."
-        ) from e
+        return _fallback_default_spec(
+            fallback,
+            GetArrayNamespaceError(
+                f"Failed to determine the `compatibility namespace` from the reference array {ref_arr!r}."
+            ), from_=e
+        )
 
 
 # initialize the context variable for array specification
 _arr_spec_var = ContextVar("arr_spec")
 
 
-def context_spec() -> ArraySpec:
+def context_spec(fallback: bool = True) -> ArraySpec:
     """
     Get the `compatibility namespace`, `dtype` and `device` associated with the most recent :func:`unify_array_args`-decorated function call in the current context.
-    If there is no such function call in the current context, return the default `compatibility namespace`, `dtype` and `device` from :func:`default.default_spec`.
+
+    Parameters
+    ----------
+        fallback : bool, default to `True`
+            Whether to fall back to the default `compatibility namespace` when there is no such function call in the current context.
+            - `True`: Return the default `compatibility namespace` from :func:`default.default_spec` when the error occurs;
+            - `False`: Raise `LookupError` when the error occurs.
 
     Returns
     -------
@@ -209,23 +251,26 @@ def context_spec() -> ArraySpec:
     Raises
     ------
         Refer to :func:`default.default_spec` for possible exceptions.
+
+        LookupError
+            If there is no :func:`unify_array_args`-decorated function call in the current context, and :param:`fallback` is `False`.
     """
     try:
         return _arr_spec_var.get()
-    except LookupError:
-        return default_spec()
+    except LookupError as e:
+        return _fallback_default_spec(fallback, e)
 
 
 @overload
-def as_context(obj: NDArray[dtypeT], /, *, unify_dtype: Literal[False], unify_device: bool = ..., copy: bool = ..., arraylike_only: bool = ...) -> CompatArray[dtypeT, Literal["cpu"]]: ...
+def as_context(obj: NDArray[dtypeT], /, *, unify_dtype: Literal[False], unify_device: bool = ..., copy: bool = ..., arraylike_only: bool = ..., fallback: bool = ...) -> CompatArray[dtypeT, Literal["cpu"]]: ...
 @overload
-def as_context(obj: ArrayLike[dtypeT], /, *, unify_dtype: Literal[False], unify_device: bool = ..., copy: bool = ..., arraylike_only: bool = ...) -> CompatArray[dtypeT, AnyDevice]: ...
+def as_context(obj: ArrayLike[dtypeT], /, *, unify_dtype: Literal[False], unify_device: bool = ..., copy: bool = ..., arraylike_only: bool = ..., fallback: bool = ...) -> CompatArray[dtypeT, AnyDevice]: ...
 @overload
-def as_context(obj: ArrayLike[Any], /, *, unify_dtype: Literal[True] = ..., unify_device: bool = ..., copy: bool = ..., arraylike_only: bool = ...) -> CompatArray[Any, AnyDevice]: ...
+def as_context(obj: ArrayLike[Any], /, *, unify_dtype: Literal[True] = ..., unify_device: bool = ..., copy: bool = ..., arraylike_only: bool = ..., fallback: bool = ...) -> CompatArray[Any, AnyDevice]: ...
 @overload
-def as_context(obj: object, /, *, unify_dtype: bool = ..., unify_device: bool = ..., copy: bool = ..., arraylike_only: Literal[False] = ...) -> CompatArray[Any, AnyDevice]: ...
+def as_context(obj: object, /, *, unify_dtype: bool = ..., unify_device: bool = ..., copy: bool = ..., arraylike_only: Literal[False] = ..., fallback: bool = ...) -> CompatArray[Any, AnyDevice]: ...
 @overload
-def as_context(obj: T, /, *, unify_dtype: bool = ..., unify_device: bool = ..., copy: bool = ..., arraylike_only: Literal[True]) -> T: ...
+def as_context(obj: T, /, *, unify_dtype: bool = ..., unify_device: bool = ..., copy: bool = ..., arraylike_only: Literal[True], fallback: bool = ...) -> T: ...
 
 
 def as_context(
@@ -234,7 +279,8 @@ def as_context(
     unify_dtype: bool = True,
     unify_device: bool = True,
     copy: bool = False,
-    arraylike_only: bool = False
+    arraylike_only: bool = False,
+    fallback: bool = True
 ) -> Any:
     """
     Convert the given object to a :class:`CompatArray` array in the current context `compatibility namespace`, with the `dtype` and `device` unified to the current context if specified.
@@ -256,6 +302,11 @@ def as_context(
         arraylike_only : bool, default to `False`
             Whether to only convert array-like objects to arrays in the current context namespace, and return the object itself if it is not array-like.
 
+        fallback : bool, default to `True`
+            Whether to fall back to the default `compatibility namespace` when there is no such function call in the current context.
+            - `True`: Return the default `compatibility namespace` from :func:`default.default_spec` when the error occurs;
+            - `False`: Raise `LookupError` when the error occurs.
+
     Returns
     -------
         CompatArray[Any, AnyDevice]
@@ -273,7 +324,7 @@ def as_context(
     >>> as_context([1, 2, 3])
     PyTorch_Array(tensor([1., 2., 3.], dtype=torch.float64))
     """
-    spec = context_spec()
+    spec = context_spec(fallback=fallback)
     return wrap_arraylike(as_array(
         obj, spec.cxp,
         dtype=spec.dtype if unify_dtype else None,
@@ -356,7 +407,7 @@ class array_context:
                 The target `device` for the context.
                 - `None`: Use the `device` from the context.
         """
-        spec = context_spec()
+        spec = context_spec(fallback=True)
         self.cur_spec = ArraySpec.create(
             to_xp(xp) if xp is not None else spec.cxp,
             dtype if dtype is not None else spec.dtype,
@@ -382,7 +433,7 @@ def unify_args(
     unify_dtype: bool = False,
     unify_device: bool = True,
     arraylike_only: bool = True,
-    strict: bool = True
+    fallback: bool = True
 ):
     """
     **Decorator** to unify arguments of a function to the same `compatibility namespace`, `dtype` and `device` determined by the provided array arguments and the reference array.
@@ -411,10 +462,10 @@ def unify_args(
         arraylike_only : bool, default to `True`
             Whether to only convert array-like objects to arrays in the determined namespace, and return the object itself if it is not array-like.
 
-        strict : bool, default to `True`
-            Whether to raise exceptions when failing to determine the `compatibility namespace`.
-            - `True`: Raise exceptions when failing to determine the `compatibility namespace` from the provided inputs or the reference array;
-            - `False`: Fall back to the default `compatibility namespace` if an error occurs. If all default array libraries are missing, just run the function without conversion.
+        fallback : bool, default to `True`
+            Whether to raise exceptions when failing to determine the `compatibility namespace` from the provided inputs or the reference array.
+            - `True`: Fall back to the default `compatibility namespace` from :func:`default.default_spec` when an error occurs;
+            - `False`: Just run the function without conversion when an error occurs.
 
     Raises
     ------
@@ -440,18 +491,13 @@ def unify_args(
                 spec = array_spec(
                     *args, kw_arrays=kwargs, ref=ref,
                     filter_arraylike=filter_arraylike,
+                    fallback=fallback,
                     api_version=api_version,
                     use_compat=use_compat
                 )
-            except Exception as e:
-                if strict:
-                    raise e
-                try:
-                    # fall back to the default namespace
-                    spec = default_spec()
-                except MissingDependencyError:
-                    # just run the function without conversion
-                    return func(*args, **kwargs)
+            except Exception:
+                # just run the function without conversion
+                return func(*args, **kwargs)
 
             with array_context.from_array_spec(spec):
                 out_args = tuple(

{cobra_array-0.1.2 → cobra_array-0.1.4}/src/cobra_array/compat/__init__.py

@@ -6,6 +6,7 @@ Functions
 ---------
 - :func:`wrap_arraylike`: Wraps an array-like object in a :class:`CompatArray` array if it is an array API object.
 - :func:`unwrap`: Unwraps a :class:`CompatArray` array to get the backend-specific array instance, or returns the object itself if it is not a :class:`CompatArray` array.
+
 Classes
 -------
 - :class:`CompatArray`: A backend-agnostic array abstraction compliant with the `Python Array API standard`.

{cobra_array-0.1.2 → cobra_array-0.1.4}/src/cobra_array/compat/_array.py

@@ -310,10 +310,17 @@ class CompatArray(Compat):
     @property
     def arr(self):
         """
-        The backend-specific array instance managed by :class:`CompatArray`.
+        The backend-specific array instance wrapped by `self`.
         """
         return self._arr
 
+    @property
+    def cxp(self):
+        """
+        The `compatibility namespace` associated with `self`.
+        """
+        return self._cxp
+
     @property
     def dtype(self):
         """

{cobra_array-0.1.2 → cobra_array-0.1.4}/src/cobra_array/compat/_array.pyi

@@ -8,6 +8,7 @@ from numpy.typing import NDArray
 from typing import (Union, List, Tuple, Optional, Any, Sequence, Generic, TypeVar, Literal, overload)
 
 from ._base import Compat
+from ._namespace import CompatNamespace
 from ..types import (
     T, DTypeT, DeviceT, dtypeT, deviceT, DType, AnyDevice,
     ArrayLike, ArrayLibraryName,
@@ -1750,6 +1751,8 @@ class CompatArray(Compat, Generic[TT, DT]):
     @property
     def arr(self) -> ArrayLike[TT]: ...
     @property
+    def cxp(self) -> CompatNamespace: ...
+    @property
     def dtype(self) -> TT: ...
     @property
     def device(self) -> DT: ...

{cobra_array-0.1.2 → cobra_array-0.1.4/src/cobra_array.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cobra-array
-Version: 0.1.2
+Version: 0.1.4
 Summary: A backend-agnostic array utility library that unifies array conversion, context control, and cross-library operations across `NumPy`/`PyTorch`-style ecosystems.
 Author-email: Zhen Tian <zhen.tian.cs@gmail.com>
 Project-URL: Homepage, https://github.com/tinchen777/cobra-array.git

{cobra_array-0.1.2 → cobra_array-0.1.4}/tests/test_backend.py

@@ -86,21 +86,24 @@ def test_as_context_arraylike_only_passthrough():
 
 
 def test_unify_args_strict_true_raises_for_non_array_inputs():
-    @unify_args(filter_arraylike=True, strict=True)
+    @unify_args(filter_arraylike=True, fallback=False)
     def fn(a, b):
         return a, b
 
-    with pytest.raises(IndexError):
-        fn("x", {"y": 1})
+    a, b = fn("x", {"y": 1})
+    assert a == "x"
+    assert b == {"y": 1}
 
 
 def test_unify_args_strict_false_fallback_and_convert():
-    @unify_args(filter_arraylike=True, strict=False, arraylike_only=False)
+    @unify_args(filter_arraylike=True, fallback=True, arraylike_only=False)
     def fn(a):
-        return a, context_spec().cxp.xp_name
+        return a, default_spec().cxp.xp_name
 
     out, xp_name = fn([1, 2, 3])
+
     assert isinstance(out, CompatArray)
+    assert out.cxp.xp_name == xp_name
     assert xp_name in ("NumPy", "PyTorch")
 
 
@@ -123,17 +126,18 @@ def test_resolve_device_torch_checks():
 
 
 if __name__ == "__main__":
-    test_array_context_override_and_restore()
-    test_as_context_converts_under_current_context()
-    test_as_context_arraylike_only_passthrough()
-    test_unify_args_strict_true_raises_for_non_array_inputs()
-    test_unify_args_strict_false_fallback_and_convert()
-    test_resolve_device_basic_and_numpy_constraints()
-    test_resolve_device_torch_checks()
-    test_array_context_override_and_restore()
-    test_as_context_converts_under_current_context()
-    test_as_context_arraylike_only_passthrough()
-    test_unify_args_strict_true_raises_for_non_array_inputs()
+    # test_array_context_override_and_restore()
+    # test_as_context_converts_under_current_context()
+    # test_as_context_arraylike_only_passthrough()
+    # test_unify_args_strict_true_raises_for_non_array_inputs()
+    # test_unify_args_strict_false_fallback_and_convert()
+    # test_resolve_device_basic_and_numpy_constraints()
+    # test_resolve_device_torch_checks()
+    # test_array_context_override_and_restore()
+    # test_as_context_converts_under_current_context()
+    # test_as_context_arraylike_only_passthrough()
+    # test_unify_args_strict_true_raises_for_non_array_inputs()
+    # test_unify_args_strict_false_fallback_and_convert()
+    # test_resolve_device_basic_and_numpy_constraints()
+    # test_resolve_device_torch_checks()
     test_unify_args_strict_false_fallback_and_convert()
-    test_resolve_device_basic_and_numpy_constraints()
-    test_resolve_device_torch_checks()

{cobra_array-0.1.2 → cobra_array-0.1.4}/tests/test_compat.py

@@ -251,3 +251,11 @@ def test_some_pyi_annotated_methods_via_dynamic_dispatch():
 
     assert r.shape == (4,)
     assert t.shape == (2, 1)
+
+
+def test_cxp_of_compatarray_matches_array_namespace():
+    a = _arr_1d()
+    cxp = a.cxp
+
+    assert cxp is not None
+    assert cxp.xp_name == a.xp_name