cobra-array 0.1.0__py3-none-any.whl

cobra_array/convert.py

@@ -0,0 +1,334 @@
+# src/cobra_array/convert.py
+# -*- coding: utf-8 -*-
+# Python version: 3.9
+# @TianZhen
+"""
+Conversion utilities for :pkg:`cobra_array`.
+
+Functions
+---------
+- :func:`to_numpy`: Convert an object to a `NumPy array`.
+- :func:`to_tensor`: Convert an object to a `PyTorch tensor`.
+- :func:`to_list`: Convert an object to a built-in `list`.
+- :func:`to_array_namespace` or :func:`to_xp`: Convert an array library name to a `array namespace` or return the `array namespace` directly if is a supported namespace.
+- :func:`as_array`: Convert an object to an array in the specified `array namespace`.
+"""
+
+from collections import abc
+import array_api_compat as api
+
+from .array_api import (numpy_xp, torch_xp, resolve_device)
+from ._utils import (warn, is_array_namespace, is_compat_namespace)
+from .exceptions import (
+    ParameterIgnoredWarning,
+    MissingDependencyError,
+    ConvertNoneTypeError,
+    UnsupportedNamespaceError,
+    UnsupportedArrayLibraryNameError,
+    ArrayConversionError,
+    NumPyConversionError,
+    TorchConversionError
+)
+
+__all__ = [
+    "to_numpy",
+    "to_tensor",
+    "to_list",
+    "to_xp",
+    "to_array_namespace",
+    "as_array"
+]
+
+
+def to_numpy(obj, /, *, dtype=None, copy=True):
+    """
+    Convert the given object to a `NumPy array` (i.e. :class:`np.ndarray` instance).
+
+    Parameters
+    ----------
+        obj : object
+            The object to be converted to a `NumPy array`.
+            - _torch.Tensor_(need :pkg:`torch`): Converted to a `NumPy array` after detaching and moving to CPU;
+            - _set_: Converted to a `NumPy array` containing the elements of the set (order is not guaranteed);
+            - _others_: Converted to a `NumPy array` directly.
+
+        dtype : Optional[DTypeT], default to `None`
+            The data type of the resulting `NumPy array`.
+            - `None`: Use the default data type of the object.
+
+        copy : bool, default to `True`
+            Control whether to create a copy of the object when converting to a `NumPy array`.
+            - `True`: Create a copy of the object;
+            - `False`: A copy will only be made if necessary.
+
+    Returns
+    -------
+        NDArray[Any]
+            The converted `NumPy array` representation of the object.
+
+    Raises
+    ------
+        MissingDependencyError
+            If `NumPy` is not installed when calling this function.
+        NumPyConversionError
+            If an error occurs during conversion to a `NumPy array`.
+    """
+    if numpy_xp is None:
+        raise MissingDependencyError("Dependency `NumPy` is required for `to_numpy()`.")
+
+    if torch_xp is not None and isinstance(obj, torch_xp.Tensor):
+        # as torch.Tensor
+        obj = obj.detach().cpu()
+    elif isinstance(obj, abc.Set):
+        # as set
+        obj = list(obj)
+    try:
+        if copy:
+            return numpy_xp.array(obj, dtype=dtype, copy=True)
+        return numpy_xp.asarray(obj, dtype=dtype)
+    except Exception as e:
+        raise NumPyConversionError(
+            "An error occurred during conversion to NumPy array."
+        ) from e
+
+
+def to_tensor(obj, /, *, dtype=None, device=None, copy=True):
+    """
+    Convert the given object to a `PyTorch tensor` (i.e. :class:`torch.Tensor` instance).
+
+    Parameters
+    ----------
+        obj : Any
+            The object to be converted to a `PyTorch tensor`.
+            - _set_: Converted to a `PyTorch tensor` containing the elements of the set (order is not guaranteed);
+            - `None`: Raises `ConvertNoneTypeError`;
+            - _others_: Converted to a `PyTorch tensor` directly.
+
+        dtype : Optional[DTypeT], default to `None`
+            The data type of the resulting `PyTorch tensor`.
+            - `None`: Use the default data type of the object.
+
+        device : Optional[DeviceT], default to `None`
+            The device on which the resulting `PyTorch tensor` will be allocated.
+            - `None`: Use the default device (usually `"cpu"`).
+
+        copy : bool, default to `True`
+            Control whether to create a copy of the object when converting to a `PyTorch tensor`.
+            - `True`: Create a copy of the object;
+            - `False`: A copy will only be made if necessary.
+
+    Returns
+    -------
+        torch.Tensor
+            The converted `PyTorch tensor` representation of the object.
+
+    Raises
+    ------
+        MissingDependencyError
+            If `PyTorch` is not installed when calling this function.
+        ConvertNoneTypeError
+            If `None` is passed as the object to be converted.
+        CUDAUnavailableError
+            If a non-CPU device is specified but CUDA is not available.
+        TorchConversionError
+            If an error occurs during conversion to a `PyTorch tensor`.
+    """
+    if obj is None:
+        raise ConvertNoneTypeError("Can not convert `NoneType` to a PyTorch tensor.")
+    if torch_xp is None:
+        raise MissingDependencyError("Dependency `PyTorch` is required for `to_tensor()`.")
+    device = resolve_device(device, xp="torch")
+
+    if isinstance(obj, torch_xp.Tensor):
+        # as torch.Tensor
+        return obj.to(dtype=dtype, device=device, copy=copy)
+
+    if isinstance(obj, abc.Set):
+        # as set
+        obj = list(obj)
+    try:
+        if copy:
+            return torch_xp.tensor(obj, dtype=dtype, device=device)
+        return torch_xp.as_tensor(obj, dtype=dtype, device=device)  # type: ignore
+    except Exception as e:
+        raise TorchConversionError(
+            "An error occurred during conversion to PyTorch tensor."
+        ) from e
+
+
+def to_list(obj, /, *, copy=True):
+    """
+    Convert the given object to a built-in `list`.
+
+    Parameters
+    ----------
+        obj : Any
+            The object to be converted to a `list`.
+            - _torch.Tensor_(need :pkg:`torch`): Converted to a `list` after detaching and moving to CPU;
+            - _np.ndarray_(need :pkg:`numpy`): Converted to a `list`;
+            - _Iterable_: Converted to a `list` containing the elements of the iterable (order is preserved);
+            - _scalar_(including _str_ and _bytes_): Converted to a `list` containing the scalar value as its single element;
+            - `None`: Raises `ConvertNoneTypeError`.
+
+        copy : bool, default to `True`
+            Control whether to create a copy when :param:`obj` is already a `list`. Other types of :param:`obj` will always be converted to a new `list`.
+
+    Returns
+    -------
+        List[Any]
+            The converted `list` representation of the object.
+
+    Raises
+    ------
+        ConvertNoneTypeError
+            If `None` is passed as the object to be converted.
+    """
+    if obj is None:
+        # as NoneType
+        raise ConvertNoneTypeError("Can not convert `NoneType` to a built-in list.")
+
+    if torch_xp is not None and isinstance(obj, torch_xp.Tensor):
+        # as torch.Tensor
+        return obj.detach().cpu().tolist()
+
+    if numpy_xp is not None and isinstance(obj, numpy_xp.ndarray):
+        # as numpy.ndarray
+        return obj.tolist()
+
+    if isinstance(obj, list):
+        # as list
+        return obj.copy() if copy else obj
+
+    if isinstance(obj, abc.Iterable) and not isinstance(obj, (str, bytes)):
+        # as iterable (not including str and bytes)
+        return list(obj)
+    # as scalar or others
+    return [obj]
+
+
+def to_xp(obj, /):
+    """
+    Convert an array library name or `compatibility namespace` to a `array namespace` or return the `array namespace` directly if is a supported namespace.
+
+    Parameters
+    ----------
+        obj : Union[Namespace, CompatNamespace, ArrayLibraryName]
+            The `array namespace` or array library name.
+            - _ArrayLibraryName_ (`"numpy"` or `"torch"`): Return the corresponding `array namespace` module;
+            - _Namespace_: Return the namespace module directly.
+            - _CompatNamespace_: Return the underlying `array namespace` module.
+
+    Returns
+    -------
+        Namespace
+            The `array namespace` module corresponding to the input.
+
+    Raises
+    ------
+        MissingDependencyError
+            If the required array library for the specified `array namespace` is not installed.
+        UnsupportedArrayLibraryNameError
+            If an unsupported `array namespace` name is specified.
+        UnsupportedNamespaceError
+            If the input is not a supported `array namespace` name or module.
+    """
+    if isinstance(obj, str):
+        if obj == "numpy":
+            if numpy_xp is None:
+                raise MissingDependencyError("Dependency `NumPy` is required for using array namespace.")
+            return numpy_xp
+
+        if obj == "torch":
+            if torch_xp is None:
+                raise MissingDependencyError("Dependency `PyTorch` is required for using array namespace.")
+            return torch_xp
+
+        raise UnsupportedArrayLibraryNameError(
+            "Parameter `obj` of `to_xp()` must be a supported array namespace "
+            f"name ('numpy', 'torch'), got {obj!r}."
+        )
+
+    if is_array_namespace(obj):
+        return obj  # type: ignore
+
+    if is_compat_namespace(obj):
+        return obj.xp  # type: ignore
+
+    raise UnsupportedNamespaceError(
+        f"Parameter `obj` of `to_xp()` is not a supported array namespace, got {obj!r}."
+    )
+
+
+to_array_namespace = to_xp  # alias of `to_xp()`
+
+
+def as_array(obj, xp, /, *, dtype=None, device=None, copy=False, arraylike_only=False):
+    """
+    Convert the given object to an array in the specified `array namespace` (e.g., `NumPy` or `PyTorch`).
+
+    Parameters
+    ----------
+        obj : object
+            The object to be converted to an array.
+
+        xp : Union[object, ArrayLibraryName]
+            The target `array namespace` or array library name for the conversion.
+            - _ArrayLibraryName_ (`"numpy"` or `"torch"`): Converted to a `NumPy array` or `PyTorch tensor` respectively using the corresponding conversion functions;
+            - _Namespace_ or _CompatNamespace_: Converted to an array using the `asarray()` function provided by the namespace module, which must be compatible with the array API standard.
+
+        dtype : Optional[DTypeT], default to `None`
+            The data type of the resulting array.
+            - `None`: Use the default data type of the object.
+
+        device : Optional[DeviceT], default to `None`
+            The device on which the resulting array will be allocated (only if `array namespace` supports it).
+
+        copy : bool, default to `False`
+            Control whether to create a copy of the object when converting to an array.
+
+        arraylike_only : bool, default to `False`
+            Whether to only convert array-like objects to arrays in the specified `array namespace`, and return the object itself if it is not array-like.
+
+    Returns
+    -------
+        ArrayLike[Any]
+            The converted array representation of the object in the specified `array namespace`.
+        object
+            If :param:`arraylike_only` is `True` and the object is not array-like.
+
+    Raises
+    ------
+        Refer to :func:`convert.to_xp`, :func:`convert.to_numpy` and :func:`convert.to_tensor` for possible exceptions.
+
+        AttributeError
+            If an unsupported `array namespace` is specified.
+        ArrayConversionError
+            If an error occurs during array conversion in the specified `array namespace`.
+    """
+    if arraylike_only and not api.is_array_api_obj(obj):
+        return obj
+
+    arr_xp = to_xp(xp)
+    if api.is_numpy_namespace(arr_xp):
+        # as NumPy array
+        if device is not None and device != "cpu":
+            warn(
+                "NumPy array does not support setting a non-CPU device. "
+                f"Parameter `device` is ignored, got {device!r}.",
+                category=ParameterIgnoredWarning
+            )
+        return to_numpy(obj, dtype=dtype, copy=copy)
+    if api.is_torch_namespace(arr_xp):
+        # as PyTorch tensor
+        return to_tensor(obj, dtype=dtype, device=device, copy=copy)
+    # as other namespace object
+    try:
+        return arr_xp.asarray(obj, dtype=dtype, device=device, copy=copy)  # type: ignore
+    except AttributeError:
+        raise AttributeError(
+            f"Parameter `xp` of `as_array()` is not a supported array namespace: {xp!r}"
+        ) from None
+    except Exception as e:
+        raise ArrayConversionError(
+            f"An error occurred during array conversion in the specified array namespace {xp!r}"
+        ) from e

cobra_array/convert.pyi

@@ -0,0 +1,73 @@
+# src/cobra_array/convert.py
+# -*- coding: utf-8 -*-
+# Python version: 3.9
+# @TianZhen
+
+from __future__ import annotations
+from numpy.typing import NDArray
+from torch import Tensor
+from array_api_compat.common._typing import Namespace
+from typing import (Any, Literal, Optional, List, Iterable, Union, overload)
+
+from .types import (
+    T, StringT,
+    DTypeT, dtypeT, DType, Device,
+    ArrayLike, ArrayLibraryName
+)
+
+
+@overload
+def to_numpy(obj: NDArray[dtypeT], /, *, dtype: None = ..., copy: bool = ...) -> NDArray[dtypeT]: ...
+@overload
+def to_numpy(obj: ArrayLike[dtypeT], /, *, dtype: None = ..., copy: bool = ...) -> NDArray[dtypeT]: ...
+@overload
+def to_numpy(obj: object, /, *, dtype: None = ..., copy: bool = ...) -> NDArray[Any]: ...
+@overload
+def to_numpy(obj: object, /, *, dtype: DTypeT, copy: bool = ...) -> NDArray[DTypeT]: ...
+def to_numpy(obj: object, /, *, dtype: Optional[DType] = None, copy: bool = True) -> NDArray[Any]: ...
+
+
+def to_tensor(obj: object, /, *, dtype: Optional[DType] = None, device: Optional[Device] = None, copy: bool = True) -> Tensor: ...
+
+
+@overload
+def to_list(obj: List[T], /, *, copy: bool = ...) -> List[T]: ...
+@overload
+def to_list(obj: StringT, /, *, copy: bool = ...) -> List[StringT]: ...
+@overload
+def to_list(obj: NDArray[dtypeT], /, *, copy: bool = ...) -> List[dtypeT]: ...
+@overload
+def to_list(obj: ArrayLike[dtypeT], /, *, copy: bool = ...) -> List[dtypeT]: ...
+@overload
+def to_list(obj: Iterable[T], /, *, copy: bool = ...) -> List[T]: ...
+@overload
+def to_list(obj: T, /, *, copy: bool = ...) -> List[T]: ...
+@overload
+def to_list(obj: object, /, *, copy: bool = ...) -> List[Any]: ...
+def to_list(obj: object, /, *, copy: bool = True) -> List[Any]: ...
+
+
+def to_xp(obj: Union[object, ArrayLibraryName], /) -> Namespace: ...
+
+
+@overload
+def as_array(obj: NDArray[dtypeT], xp: Literal["numpy"], /, *, dtype: None = ..., device: Optional[Device] = ..., copy: bool = ..., arraylike_only: bool = ...) -> NDArray[dtypeT]: ...
+@overload
+def as_array(obj: ArrayLike[dtypeT], xp: Literal["numpy"], /, *, dtype: None = ..., device: Optional[Device] = ..., copy: bool = ..., arraylike_only: bool = ...) -> NDArray[dtypeT]: ...
+@overload
+def as_array(obj: object, xp: Literal["numpy"], /, *, dtype: None = ..., device: Optional[Device] = ..., copy: bool = ..., arraylike_only: Literal[False] = ...) -> NDArray[Any]: ...
+@overload
+def as_array(obj: object, xp: Literal["numpy"], /, *, dtype: DTypeT, device: Optional[Device] = ..., copy: bool = ..., arraylike_only: Literal[False] = ...) -> NDArray[DTypeT]: ...
+@overload
+def as_array(obj: object, xp: Literal["torch"], /, *, dtype: Optional[DType] = ..., device: Optional[Device] = ..., copy: bool = ..., arraylike_only: Literal[False] = ...) -> Tensor: ...
+@overload
+def as_array(obj: NDArray[dtypeT], xp: Union[object, ArrayLibraryName], /, *, dtype: None = ..., device: Optional[Device] = ..., copy: bool = ..., arraylike_only: bool = ...) -> ArrayLike[dtypeT]: ...
+@overload
+def as_array(obj: ArrayLike[dtypeT], xp: Union[object, ArrayLibraryName], /, *, dtype: None = ..., device: Optional[Device] = ..., copy: bool = ..., arraylike_only: bool = ...) -> ArrayLike[dtypeT]: ...
+@overload
+def as_array(obj: object, xp: Union[object, ArrayLibraryName], /, *, dtype: None = ..., device: Optional[Device] = ..., copy: bool = ..., arraylike_only: Literal[False] = ...) -> ArrayLike[Any]: ...
+@overload
+def as_array(obj: object, xp: Union[object, ArrayLibraryName], /, *, dtype: DTypeT, device: Optional[Device] = ..., copy: bool = ..., arraylike_only: Literal[False] = ...) -> ArrayLike[DTypeT]: ...
+@overload
+def as_array(obj: T, xp: Union[object, ArrayLibraryName], /, *, dtype: Optional[DType] = ..., device: Optional[Device] = ..., copy: bool = ..., arraylike_only: Literal[True]) -> T: ...
+def as_array(obj: object, xp: Union[object, ArrayLibraryName], /, *, dtype: Optional[DType] = None, device: Optional[Device] = None, copy: bool = False, arraylike_only: bool = False) -> Any: ...

cobra_array/default.py

@@ -0,0 +1,142 @@
+# src/cobra_array/default.py
+# -*- coding: utf-8 -*-
+# Python version: 3.9
+# @TianZhen
+"""
+Default utilities for :pkg:`cobra_array`.
+
+Attributes
+----------
+- :attr:`DEFAULT_DTYPE`: The default data type for arrays.
+- :attr:`DEFAULT_DEVICE`: The default device for arrays.
+- :attr:`TORCH_COMPAT_NAMESPACE`: The `compatibility namespace` for `PyTorch`.
+- :attr:`NUMPY_COMPAT_NAMESPACE`: The `compatibility namespace` for `NumPy`.
+Functions
+---------
+- :func:`default_spec`: Get the default array specification.
+- :func:`as_default`: Convert an array-like object to a :class:`CompatArray` array in the default context.
+"""
+
+from __future__ import annotations
+from typing import (Any, Literal, TYPE_CHECKING, NamedTuple, overload)
+
+from .compat import (CompatNamespace, wrap_arraylike)
+from .convert import as_array
+from .array_api import (numpy_xp, torch_xp)
+from .exceptions import MissingDependencyError
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+    from .compat import CompatArray
+    from .types import (ArrayLike, DType, dtypeT, T)
+
+
+class ArraySpec(NamedTuple):
+    """
+    A named tuple to hold the specifications of an array.
+    - `cxp`: CompatNamespace
+    - `dtype`: DType
+    - `device`: Any
+    """
+    cxp: CompatNamespace
+    dtype: DType
+    device: Any
+
+    @classmethod
+    def create(cls, xp: object, dtype: Any, device: Any) -> ArraySpec:
+        """Create an `ArraySpec` instance, convert the `xp` to a :class:`CompatNamespace` instance if it is not already one."""
+        return cls(
+            cxp=CompatNamespace(xp),
+            dtype=dtype,
+            device=device,
+        )
+
+
+# get defaults
+DEFAULT_DTYPE = float
+DEFAULT_DEVICE = "cpu"
+NUMPY_COMPAT_NAMESPACE = CompatNamespace(numpy_xp) if numpy_xp is not None else None
+TORCH_COMPAT_NAMESPACE = CompatNamespace(torch_xp) if torch_xp is not None else None
+
+
+def default_spec() -> ArraySpec:
+    """
+    Try to get a suitable `compatibility namespace` from the available array libraries in order of `PyTorch` > `NumPy`, and return it along with the default `dtype` and `device`.
+
+    Returns
+    -------
+        ArraySpec
+            An :class:`ArraySpec` named tuple containing the default `cxp`(`compatibility namespace`), `dtype` and `device`.
+
+    Raises
+    ------
+        MissingDependencyError
+            If all default array libraries (`NumPy` and `PyTorch`) are missing.
+    """
+    default_xp = TORCH_COMPAT_NAMESPACE or NUMPY_COMPAT_NAMESPACE
+    if default_xp is None:
+        raise MissingDependencyError(
+            "Missing all default array libraries (`PyTorch` > `NumPy`)."
+        )
+    return ArraySpec(default_xp, DEFAULT_DTYPE, DEFAULT_DEVICE)
+
+
+@overload
+def as_default(obj: NDArray[dtypeT], /, *, unify_dtype: Literal[False], unify_device: bool = ..., copy: bool = ..., arraylike_only: bool = ...) -> CompatArray[dtypeT, Literal["cpu"]]: ...
+@overload
+def as_default(obj: ArrayLike[dtypeT], /, *, unify_dtype: Literal[False], unify_device: bool = ..., copy: bool = ..., arraylike_only: bool = ...) -> CompatArray[dtypeT, Any]: ...
+@overload
+def as_default(obj: ArrayLike[Any], /, *, unify_dtype: Literal[True] = ..., unify_device: bool = ..., copy: bool = ..., arraylike_only: bool = ...) -> CompatArray[Any, Any]: ...
+@overload
+def as_default(obj: object, /, *, unify_dtype: bool = ..., unify_device: bool = ..., copy: bool = ..., arraylike_only: Literal[False] = ...) -> CompatArray[Any, Any]: ...
+@overload
+def as_default(obj: T, /, *, unify_dtype: bool = ..., unify_device: bool = ..., copy: bool = ..., arraylike_only: Literal[True]) -> T: ...
+
+
+def as_default(
+    obj: object,
+    /, *,
+    unify_dtype: bool = True,
+    unify_device: bool = True,
+    copy: bool = False,
+    arraylike_only: bool = False
+) -> Any:
+    """
+    Convert an array-like object to a :class:`CompatArray` array in default `compatibility namespace` with the default `dtype` and `device` if specified.
+
+    Parameters
+    ----------
+        obj : object
+            The object to be converted to a :class:`CompatArray` array.
+
+        unify_dtype : bool, default to `True`
+            Whether to unify the `dtype` of the converted array to that of the default context.
+
+        unify_device : bool, default to `True`
+            Whether to unify the `device` of the converted array to that of the default context.
+
+        copy : bool, default to `False`
+            Whether to return a copy of the array if it is already in the default context namespace.
+
+        arraylike_only : bool, default to `False`
+            Whether to only convert array-like objects to arrays in the default context namespace, and return the object itself if it is not array-like.
+
+    Returns
+    -------
+        CompatArray[Any, Any]
+            The converted array representation of the object in the default context `compatibility namespace`, with the default `dtype` and `device` if specified.
+        object
+            If :param:`arraylike_only` is `True` and the object is not array-like.
+
+    Raises
+    ------
+        Refer to :func:`convert.as_array`, :func:`default.default_spec` for possible exceptions.
+    """
+    spec = default_spec()
+    return wrap_arraylike(as_array(
+        obj, spec.cxp,
+        dtype=spec.dtype if unify_dtype else None,
+        device=spec.device if unify_device else None,
+        copy=copy,
+        arraylike_only=arraylike_only
+    ), xp=spec.cxp)

cobra_array/exceptions.py

@@ -0,0 +1,74 @@
+# src/cobra_array/exceptions.py
+"""
+Exceptions for :pkg:`cobra_array`.
+"""
+
+
+# === WARNING ===
+class CobraArrayWarning(Warning):
+    """Base warning class for :pkg:`cobra_array`."""
+
+
+class ParameterIgnoredWarning(CobraArrayWarning):
+    """Warning raised when a parameter is ignored."""
+
+
+# === ERROR ===
+class CobraArrayError(Exception):
+    """Base error class for :pkg:`cobra_array`."""
+
+
+class MissingDependencyError(CobraArrayError, ImportError):
+    """Raised when a required dependency is missing."""
+
+
+class ConvertNoneTypeError(CobraArrayError, TypeError):
+    """Raised when conversion of `NoneType` is attempted."""
+
+
+class UnsupportedNamespaceError(CobraArrayError, ValueError):
+    """Raised when an unsupported `array namespace` is specified."""
+
+
+class UnsupportedArrayLibraryNameError(CobraArrayError, ValueError):
+    """Raised when an unsupported `array namespace` name is specified."""
+
+
+class ArrayConversionError(CobraArrayError):
+    """Raised when an error occurs during array conversion in an `array namespace`."""
+
+
+class NumPyConversionError(CobraArrayError):
+    """Raised when an error occurs during array conversion in `NumPy`."""
+
+
+class TorchConversionError(CobraArrayError):
+    """Raised when an error occurs during array conversion in `PyTorch`."""
+
+
+class CUDAUnavailableError(CobraArrayError):
+    """Raised when CUDA is not available but a CUDA device is specified."""
+
+
+class DeviceNotSupportedError(CobraArrayError):
+    """Raised when a specified device is not supported by the current array library."""
+
+
+class NotArrayAPIObjectError(CobraArrayError, ValueError):
+    """Raised when an array is not an array API compatible array object."""
+
+
+class NoArrayInputsError(CobraArrayError, ValueError):
+    """Raised when no array inputs are provided."""
+
+
+class GetArrayNamespaceError(CobraArrayError):
+    """Raised when an error occurs while determining the `array namespace`."""
+
+
+class CompatNamespaceAttributeError(CobraArrayError, AttributeError):
+    """Raised when an attribute is not supported in :class:`CompatNamespace`."""
+
+
+class CompatArrayAttributeError(CobraArrayError, AttributeError):
+    """Raised when an attribute is not supported in :class:`CompatArray`."""

cobra_array/types.py

@@ -0,0 +1,68 @@
+# src/cobra_array/types.py
+"""
+Type definitions for :pkg:`cobra_array`.
+"""
+
+from __future__ import annotations
+import torch
+from typing import (Union, Protocol, TypeVar, Any, Literal, NamedTuple, Generic, TYPE_CHECKING)
+
+if TYPE_CHECKING:
+    from .compat._array import CompatArray
+
+# === Type Aliases ===
+Value = Union[int, float, complex, bool]
+
+T = TypeVar("T")
+StringT = TypeVar("StringT", str, bytes)
+ValueT = TypeVar("ValueT", bound=Value)
+
+# === DType and Device ===
+DType = Any
+# FIXME 无法推断
+DeviceLiteral = Literal["cpu", "cuda", "xpu", "mkldnn", "opengl", "opencl", "ideep", "hip", "ve", "ort", "mlc", "xla", "lazy", "vulkan", "meta", "hpu"]
+Device = Union[DeviceLiteral, torch.device, str]
+
+dtypeT = TypeVar("dtypeT", bound=DType)
+deviceT = TypeVar("deviceT", bound=Device)
+DTypeT = TypeVar("DTypeT", bound=DType)
+DeviceT = TypeVar("DeviceT", bound=Device)
+
+DTypeT_co = TypeVar("DTypeT_co", bound=DType, covariant=True)
+DeviceT_co = TypeVar("DeviceT_co", bound=Device, covariant=True)
+
+
+# === Array Protocols ===
+class ArrayLike(Protocol[DTypeT_co]):
+    @property
+    def dtype(self) -> DTypeT_co: ...
+    @property
+    def shape(self) -> Any: ...
+    def __array__(self) -> Any: ...
+
+
+ArrayLibraryName = Literal["numpy", "torch"]
+ArrayT = TypeVar("ArrayT", bound=ArrayLike[Any])
+ArrayOrAny = Union[ArrayLike[Any], int, float, complex, bool]
+ArrayOrScalar = Union[ArrayLike[Any], int, float, complex]
+ArrayOrReal = Union[ArrayLike[Any], int, float]
+ArrayOrIntLike = Union[ArrayLike[Any], int, bool]
+ArrayOrbool = Union[ArrayLike[Any], bool]
+ArrayOrInt = Union[ArrayLike[Any], int]
+
+
+class UniqueAllResult(NamedTuple, Generic[DTypeT_co, DeviceT_co]):
+    values: CompatArray[DTypeT_co, DeviceT_co]
+    indices: CompatArray[int, DeviceT_co]
+    inverse_indices: CompatArray[int, DeviceT_co]
+    counts: CompatArray[int, DeviceT_co]
+
+
+class UniqueCountsResult(NamedTuple, Generic[DTypeT_co, DeviceT_co]):
+    values: CompatArray[DTypeT_co, DeviceT_co]
+    counts: CompatArray[int, DeviceT_co]
+
+
+class UniqueInverseResult(NamedTuple, Generic[DTypeT_co, DeviceT_co]):
+    values: CompatArray[DTypeT_co, DeviceT_co]
+    inverse_indices: CompatArray[int, DeviceT_co]