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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cobra-array
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -71,14 +71,11 @@ pip install cobra-array
 
     data = [[1, 2], [3, 4]]
 
-    arr_np = to_numpy(data, dtype=np.float32)
-    print(type(arr_np), arr_np.dtype)  # numpy.ndarray float32
+    arr_np = to_numpy(data, dtype=np.float32)  # numpy.ndarray float32
 
     arr_torch = to_tensor(data, device="cpu")
-    print(type(arr_torch), arr_torch.device)
 
-    back_to_list = to_list(arr_np)
-    print(back_to_list)  # [[1.0, 2.0], [3.0, 4.0]]
+    back_to_list = to_list(arr_np)  # [[1.0, 2.0], [3.0, 4.0]]
     ```
 
 - Context-based conversion:
@@ -91,8 +88,6 @@ pip install cobra-array
         x = as_context([1, 2, 3])
         y = as_context(np.array([4, 5]))
         spec = context_spec()
-        print(spec.cxp.xp_name, spec.dtype, spec.device)
-        print(x, y)
     ```
 
 - Auto-unify function arguments:
@@ -107,7 +102,6 @@ pip install cobra-array
         return c.mean()
 
     out = add_and_mean(np.array([1, 2, 3]), [4, 5, 6])
-    print(out)
     ```
 
 - Default backend strategy:
@@ -116,10 +110,8 @@ pip install cobra-array
     from cobra_array.default import as_default, default_spec
 
     spec = default_spec()
-    print(spec.cxp.xp_name, spec.dtype, spec.device)
 
     x = as_default([1, 2, 3], unify_dtype=True, unify_device=True)
-    print(x, x.dtype)
     ```
 
 ## Requirements

{cobra_array-0.1.0 → cobra_array-0.1.2}/README.md

@@ -46,14 +46,11 @@ pip install cobra-array
 
     data = [[1, 2], [3, 4]]
 
-    arr_np = to_numpy(data, dtype=np.float32)
-    print(type(arr_np), arr_np.dtype)  # numpy.ndarray float32
+    arr_np = to_numpy(data, dtype=np.float32)  # numpy.ndarray float32
 
     arr_torch = to_tensor(data, device="cpu")
-    print(type(arr_torch), arr_torch.device)
 
-    back_to_list = to_list(arr_np)
-    print(back_to_list)  # [[1.0, 2.0], [3.0, 4.0]]
+    back_to_list = to_list(arr_np)  # [[1.0, 2.0], [3.0, 4.0]]
     ```
 
 - Context-based conversion:
@@ -66,8 +63,6 @@ pip install cobra-array
         x = as_context([1, 2, 3])
         y = as_context(np.array([4, 5]))
         spec = context_spec()
-        print(spec.cxp.xp_name, spec.dtype, spec.device)
-        print(x, y)
     ```
 
 - Auto-unify function arguments:
@@ -82,7 +77,6 @@ pip install cobra-array
         return c.mean()
 
     out = add_and_mean(np.array([1, 2, 3]), [4, 5, 6])
-    print(out)
     ```
 
 - Default backend strategy:
@@ -91,10 +85,8 @@ pip install cobra-array
     from cobra_array.default import as_default, default_spec
 
     spec = default_spec()
-    print(spec.cxp.xp_name, spec.dtype, spec.device)
 
     x = as_default([1, 2, 3], unify_dtype=True, unify_device=True)
-    print(x, x.dtype)
     ```
 
 ## Requirements

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

@@ -25,23 +25,20 @@ Functions
 
 Examples
 --------
-Basic conversions::
+- Basic conversions::
 
     import numpy as np
     from cobra_array.convert import to_numpy, to_tensor, to_list
 
     data = [[1, 2], [3, 4]]
 
-    arr_np = to_numpy(data, dtype=np.float32)
-    print(type(arr_np), arr_np.dtype)  # numpy.ndarray float32
+    arr_np = to_numpy(data, dtype=np.float32)  # numpy.ndarray float32
 
     arr_torch = to_tensor(data, device="cpu")
-    print(type(arr_torch), arr_torch.device)
 
-    back_to_list = to_list(arr_np)
-    print(back_to_list)  # [[1.0, 2.0], [3.0, 4.0]]
+    back_to_list = to_list(arr_np)  # [[1.0, 2.0], [3.0, 4.0]]
 
-Context-based conversion::
+- Context-based conversion::
 
     import numpy as np
     from cobra_array import array_context, as_context, context_spec
@@ -50,10 +47,8 @@ Context-based conversion::
         x = as_context([1, 2, 3])
         y = as_context(np.array([4, 5]))
         spec = context_spec()
-        print(spec.cxp.xp_name, spec.dtype, spec.device)
-        print(x, y)
 
-Auto-unify function arguments::
+- Auto-unify function arguments::
 
     import numpy as np
     from cobra_array import unify_args
@@ -64,17 +59,14 @@ Auto-unify function arguments::
         return c.mean()
 
     out = add_and_mean(np.array([1, 2, 3]), [4, 5, 6])
-    print(out)
 
-Default backend strategy::
+- Default backend strategy::
 
     from cobra_array.default import as_default, default_spec
 
     spec = default_spec()
-    print(spec.cxp.xp_name, spec.dtype, spec.device)
 
     x = as_default([1, 2, 3], unify_dtype=True, unify_device=True)
-    print(x, x.dtype)
 """
 
 from ._core import (
@@ -91,7 +83,7 @@ from ._utils import (
 )
 
 __author__ = "Zhen Tian"
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 __all__ = [
     "array_spec",

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

@@ -22,7 +22,7 @@ from .exceptions import (
 if TYPE_CHECKING:
     from numpy.typing import NDArray
     from .compat import CompatArray
-    from .types import (T, dtypeT, DType, Device, ArrayLike, ArrayLibraryName)
+    from .types import (T, dtypeT, DType, AnyDevice, ArrayLike, ArrayLibraryName)
 
 
 def array_spec(
@@ -88,7 +88,29 @@ def array_spec(
 
     Examples
     --------
-    
+    Infer namespace from positional arrays:
+
+    >>> import numpy as np
+    >>> spec = array_spec(np.asarray([1, 2]), np.asarray([3, 4]))
+    >>> spec.cxp.xp_name
+    'NumPy'
+    >>> spec.dtype is None and spec.device is None
+    True
+
+    Use a keyword argument as reference to carry dtype and device:
+
+    >>> ref_arr = np.asarray([1, 2], dtype=np.float32)
+    >>> spec = array_spec(kw_arrays={"x": ref_arr}, ref="x")
+    >>> str(spec.dtype)
+    'float32'
+    >>> str(spec.device)
+    'cpu'
+
+    Filter non-array-like inputs when selecting reference by index:
+
+    >>> spec = array_spec("skip", np.asarray([1, 2]), ref=0, filter_arraylike=True)
+    >>> spec.cxp.xp_name
+    'NumPy'
     """
     kw_arrays = kw_arrays or {}
 
@@ -197,11 +219,11 @@ def context_spec() -> ArraySpec:
 @overload
 def as_context(obj: NDArray[dtypeT], /, *, unify_dtype: Literal[False], unify_device: bool = ..., copy: bool = ..., arraylike_only: 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, Any]: ...
+def as_context(obj: ArrayLike[dtypeT], /, *, unify_dtype: Literal[False], unify_device: bool = ..., copy: bool = ..., arraylike_only: 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, Any]: ...
+def as_context(obj: ArrayLike[Any], /, *, unify_dtype: Literal[True] = ..., unify_device: bool = ..., copy: bool = ..., arraylike_only: bool = ...) -> CompatArray[Any, AnyDevice]: ...
 @overload
-def as_context(obj: object, /, *, unify_dtype: bool = ..., unify_device: bool = ..., copy: bool = ..., arraylike_only: Literal[False] = ...) -> CompatArray[Any, Any]: ...
+def as_context(obj: object, /, *, unify_dtype: bool = ..., unify_device: bool = ..., copy: bool = ..., arraylike_only: Literal[False] = ...) -> CompatArray[Any, AnyDevice]: ...
 @overload
 def as_context(obj: T, /, *, unify_dtype: bool = ..., unify_device: bool = ..., copy: bool = ..., arraylike_only: Literal[True]) -> T: ...
 
@@ -236,7 +258,7 @@ def as_context(
 
     Returns
     -------
-        CompatArray[Any, Any]
+        CompatArray[Any, AnyDevice]
             The converted array representation of the object in the current context `compatibility namespace`, with the current context `dtype` and `device` if specified.
         object
             If :param:`arraylike_only` is `True` and the object is not array-like.
@@ -244,6 +266,12 @@ def as_context(
     Raises
     ------
         Refer to :func:`convert.as_array`, :func:`context_spec` for possible exceptions.
+
+    Examples
+    --------
+    >>> from cobra_array import as_context
+    >>> as_context([1, 2, 3])
+    PyTorch_Array(tensor([1., 2., 3.], dtype=torch.float64))
     """
     spec = context_spec()
     return wrap_arraylike(as_array(
@@ -258,6 +286,40 @@ def as_context(
 class array_context:
     """
     **Context Manager** to set the context `compatibility namespace`, `dtype` and `device` for the enclosed block of code.
+
+    Examples
+    --------
+    Set a temporary context explicitly:
+
+    >>> from cobra_array import array_context
+    >>> with array_context(xp="numpy", dtype=None, device="cpu") as spec:
+    ...     spec.cxp.xp_name
+    'NumPy'
+
+    Convert data in the active context:
+
+    >>> with array_context(xp="numpy", dtype=None, device="cpu"):
+    ...     as_context([1, 2, 3], unify_dtype=False)
+    NumPy_Array([1 2 3])
+
+    Build a context from :class:`ArraySpec`:
+
+    >>> import numpy as np
+    >>> spec = array_spec(np.asarray([1, 2], dtype=np.float32), ref=0)
+    >>> with array_context.from_array_spec(spec) as cur:
+    ...     str(cur.dtype)
+    'float32'
+
+    Nested contexts override temporarily and then restore outer context:
+
+    >>> from cobra_array import context_spec
+    >>> with array_context(xp="numpy", dtype=None, device="cpu"):
+    ...     before = context_spec().dtype
+    ...     with array_context(dtype=float):
+    ...         middle = context_spec().dtype
+    ...     after = context_spec().dtype
+    ...     (before is None, middle is float, after is None)
+    (True, True, True)
     """
     @classmethod
     def from_array_spec(cls, arr_spec: ArraySpec, /):
@@ -275,7 +337,7 @@ class array_context:
         self,
         xp: Optional[Union[object, ArrayLibraryName]] = None,
         dtype: Optional[DType] = None,
-        device: Optional[Device] = None
+        device: Optional[AnyDevice] = None
     ):
         """
         Initialize the context manager with the specified `array namespace`, `dtype` and `device`.
@@ -286,11 +348,11 @@ class array_context:
                 The target `array namespace` or array library name for the context.
                 - `None`: Use the `compatibility namespace` from the context;
 
-            dtype : Optional[DTypeT], default to `None`
+            dtype : Optional[DType], default to `None`
                 The target `dtype` for the context.
                 - `None`: Use the `dtype` from the context.
 
-            device : Optional[DeviceT], default to `None`
+            device : Optional[AnyDevice], default to `None`
                 The target `device` for the context.
                 - `None`: Use the `device` from the context.
         """
@@ -313,7 +375,7 @@ class array_context:
 
 def unify_args(
     ref: Optional[Union[str, int]] = 0,
-    /,
+    /, *,
     filter_arraylike: bool = True,
     api_version: Optional[str] = None,
     use_compat: Optional[bool] = None,
@@ -357,6 +419,18 @@ def unify_args(
     Raises
     ------
         Refer to :func:`default.default_spec`, :func:`as_context` for possible exceptions.
+
+    Examples
+    --------
+    Use `unify_args` as a decorator to normalize array arguments before the function body runs:
+
+    >>> import numpy as np
+    >>> from cobra_array import unify_args
+    >>> @unify_args(ref=0, unify_dtype=False, unify_device=False)
+    ... def add(x, y):
+    ...     return x + y
+    >>> add(np.asarray([1, 2]), y=np.asarray([3, 4]))
+    NumPy_Array([4 6])
     """
     def decorator(func):
         @wraps(func)

{cobra_array-0.1.0 → cobra_array-0.1.2}/src/cobra_array/_utils.py

@@ -43,7 +43,7 @@ def array_namespace_alias(xp: object) -> str:
     Raises
     ------
         UnsupportedNameSpaceError
-            If the input object is not a supported namespace.
+            If the input object is not a supported `array namespace`.
     """
     if isinstance(xp, ModuleType):
         if api.is_numpy_namespace(xp):

{cobra_array-0.1.0 → cobra_array-0.1.2}/src/cobra_array/array_api.py

@@ -15,6 +15,24 @@ Attributes
 Functions
 ---------
 - :func:`resolve_device`: Get the device string from an object or a device specification string, and check if it is compatible with the specified `array namespace` if provided.
+
+Examples
+--------
+- Basic usage::
+
+    from cobra_array.array_api import resolve_device, torch_xp, numpy_xp
+
+    r = resolve_device("cpu")        # "cpu"
+    r = resolve_device("cuda:0")     # "cuda:0"
+
+    if numpy_xp is not None:
+        r = resolve_device("cpu", xp="numpy")
+
+    if torch_xp is not None:
+        r = resolve_device("cpu", xp="torch")
+
+    if torch_xp is not None:
+        r = resolve_device("cpu", xp=torch_xp)
 """
 
 from __future__ import annotations
@@ -61,7 +79,7 @@ def resolve_device(
         obj : object
             The input object or device specification string to extract the device information from.
 
-        xp : Optional[Union[Namespace, CompatNamespace, ArrayLibraryName]], default is `None`
+        xp : Optional[Union[Any, ArrayLibraryName]], default is `None`
             The `array namespace` to check the device compatibility against.
             - `None`: No compatibility check will be performed.
 
@@ -80,6 +98,54 @@ def resolve_device(
             If the extracted device is not compatible with the specified `array namespace`.
         CUDAUnavailableError
             If a CUDA device is specified but CUDA is not available for `PyTorch`.
+
+    Examples
+    --------
+    Basic parsing and normalization:
+
+    >>> resolve_device("cpu")
+    'cpu'
+    >>> resolve_device(" CUDA:0 ")
+    'cuda:0'
+    >>> resolve_device(None)
+    None
+
+    Namespace compatibility checks:
+
+    >>> resolve_device("cpu")
+    'cpu'
+    >>> resolve_device("cpu", xp="numpy")
+    'cpu'
+    >>> resolve_device("cpu", xp="torch")
+    'cpu'
+
+    Unsupported device for NumPy:
+
+    >>> resolve_device("cuda:0", xp="numpy")
+    Traceback (most recent call last):
+        ...
+    cobra_array.exceptions.DeviceNotSupportedError: ...
+
+    Unsupported device type for PyTorch:
+
+    >>> resolve_device("quantum", xp="torch")
+    Traceback (most recent call last):
+        ...
+    cobra_array.exceptions.DeviceNotSupportedError: ...
+
+    CUDA path for PyTorch (works with or without CUDA runtime):
+
+    >>> from cobra_array.array_api import CUDA_AVAILABLE
+    >>> result = None
+    >>> if not CUDA_AVAILABLE:
+    ...     try:
+    ...         resolve_device("cuda:0", xp="torch")
+    ...     except CUDAUnavailableError:
+    ...         result = "CUDAUnavailableError"
+    ... else:
+    ...     result = resolve_device("cuda:0", xp="torch")
+    >>> result in {"cuda:0", "CUDAUnavailableError"}
+    True
     """
     # source
     if obj is None:

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

@@ -10,6 +10,23 @@ Classes
 -------
 - :class:`CompatArray`: A backend-agnostic array abstraction compliant with the `Python Array API standard`.
 - :class:`CompatNamespace`: A wrapper around an `array namespace` providing a unified, backend-agnostic functional interface.
+
+Examples
+--------
+- Basic usage::
+
+    import numpy as np
+    from cobra_array.compat import CompatArray, CompatNamespace, wrap_arraylike, unwrap
+
+    cxp = CompatNamespace(np)
+    a = CompatArray(np.asarray([1, 2, 3]))
+    b = cxp.asarray([10, 20, 30])
+
+    r = (a + b).to_list()        # [11, 22, 33]
+    r = cxp.add(a, b).to_list()  # [11, 22, 33]
+
+    wrapped = wrap_arraylike(np.asarray([4, 5]))
+    unwrap(wrapped).tolist()  # [4, 5]
 """
 
 from ._array import (CompatArray, wrap_arraylike, unwrap)

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

@@ -26,6 +26,61 @@ class CompatArray(Compat):
     - All operations follow the semantics defined by the `Python Array API standard`.
     - Methods correspond directly to standard functions, but are exposed in an object-oriented form.
     - All methods guarantee that any array-like objects in the returned value are automatically wrapped as :class:`CompatArray`. This applies recursively to arrays contained in Python containers (e.g., `tuple`, `list`, `dict`). Non-array objects remain unchanged.
+
+    Examples
+    --------
+    Create a :class:`CompatArray` from a backend array object:
+
+    >>> xp = to_xp("numpy")
+    >>> a = CompatArray(xp.asarray([1, 2, 3]))
+    >>> a
+    NumPy_Array([1 2 3])
+    >>> a.to_list()
+    [1, 2, 3]
+    >>> a.shape
+    (3,)
+    >>> a.xp_name
+    'NumPy'
+
+    Convert Python data with an explicit backend:
+
+    >>> b = CompatArray.from_other([10, 20], xp="numpy")
+    >>> isinstance(b, CompatArray)
+    True
+    >>> b.to_tensor()
+    tensor([10, 20])
+
+    Re-wrapping behavior for existing :class:`CompatArray`:
+
+    >>> CompatArray(b) is b
+    True
+    >>> CompatArray(b, copy=True) is b
+    False
+
+    Call elementwise functions directly:
+
+    >>> x = CompatArray.from_other([1, 2, 3], xp="numpy")
+    >>> y = CompatArray.from_other([10, 20, 30], xp="numpy")
+    >>> x.add(y)
+    NumPy_Array([11 22 33])
+    >>> x.multiply(2)
+    NumPy_Array([2 4 6])
+
+    Use Python operators:
+
+    >>> x + y
+    NumPy_Array([11 22 33])
+    >>> y - x
+    NumPy_Array([ 9 18 27])
+    >>> x * 2
+    NumPy_Array([2 4 6])
+
+    Invalid input raises an exception:
+
+    >>> CompatArray("not-array")
+    Traceback (most recent call last):
+        ...
+    cobra_array.exceptions.NotArrayAPIObjectError: ...
     """
     _arr = None
     _cxp = None
@@ -103,7 +158,7 @@ class CompatArray(Compat):
 
         Parameters
         ----------
-            device : Device
+            device : AnyDevice
                 A device object or name.
 
             stream : Optional[Union[int, Any]], default to `None`

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

@@ -9,14 +9,14 @@ from typing import (Union, List, Tuple, Optional, Any, Sequence, Generic, TypeVa
 
 from ._base import Compat
 from ..types import (
-    T, DTypeT, DeviceT, dtypeT, deviceT, DType, Device,
+    T, DTypeT, DeviceT, dtypeT, deviceT, DType, AnyDevice,
     ArrayLike, ArrayLibraryName,
     ArrayOrAny, ArrayOrScalar, ArrayOrReal, ArrayOrIntLike, ArrayOrInt, ArrayOrbool,
     UniqueAllResult, UniqueCountsResult, UniqueInverseResult
 )
 
 TT = TypeVar("TT", bound=DType)
-DT = TypeVar("DT", bound=Device)
+DT = TypeVar("DT", bound=AnyDevice)
 
 
 class CompatArray(Compat, Generic[TT, DT]):
@@ -31,47 +31,54 @@ class CompatArray(Compat, Generic[TT, DT]):
     def from_other(cls, obj: object, /, xp: Literal["numpy"]) -> CompatArray[Any, Literal["cpu"]]: ...
     @overload
     @classmethod
-    def from_other(cls, obj: NDArray[dtypeT], /, xp: Union[object, ArrayLibraryName]) -> CompatArray[dtypeT, Any]: ...
+    def from_other(cls, obj: NDArray[dtypeT], /, xp: Union[object, ArrayLibraryName]) -> CompatArray[dtypeT, AnyDevice]: ...
     @overload
     @classmethod
-    def from_other(cls, obj: ArrayLike[dtypeT], /, xp: Union[object, ArrayLibraryName]) -> CompatArray[dtypeT, Any]: ...
+    def from_other(cls, obj: ArrayLike[dtypeT], /, xp: Union[object, ArrayLibraryName]) -> CompatArray[dtypeT, AnyDevice]: ...
     @overload
     @classmethod
-    def from_other(cls, obj: object, /, xp: Union[object, ArrayLibraryName]) -> CompatArray[Any, Any]: ...
+    def from_other(cls, obj: object, /, xp: Union[object, ArrayLibraryName]) -> CompatArray[Any, AnyDevice]: ...
     @classmethod
-    def from_other(cls, obj: object, /, xp: Union[object, ArrayLibraryName]) -> CompatArray[Any, Any]: ...
+    def from_other(cls, obj: object, /, xp: Union[object, ArrayLibraryName]) -> CompatArray[Any, AnyDevice]: ...
 
     @overload
     def __new__(cls, arr: NDArray[dtypeT], /, **kwargs) -> CompatArray[dtypeT, Literal["cpu"]]: ...
     @overload
-    def __new__(cls, arr: Tensor, /, **kwargs) -> CompatArray[Any, Any]: ...
+    def __new__(cls, arr: Tensor, /, **kwargs) -> CompatArray[Any, AnyDevice]: ...
     @overload
     def __new__(cls, arr: CompatArray[dtypeT, deviceT], /, **kwargs) -> CompatArray[dtypeT, deviceT]: ...
     @overload
-    def __new__(cls, arr: ArrayLike[dtypeT], /, **kwargs) -> CompatArray[dtypeT, Any]: ...
-    def __new__(cls, arr: ArrayLike[Any], /, **kwargs) -> CompatArray[Any, Any]: ...
+    def __new__(cls, arr: ArrayLike[dtypeT], /, **kwargs) -> CompatArray[dtypeT, AnyDevice]: ...
+    def __new__(cls, arr: ArrayLike[Any], /, **kwargs) -> CompatArray[Any, AnyDevice]: ...
 
     # === Conversion functions ===
     def to_numpy(self, *, copy: bool = False) -> NDArray[TT]: ...
-    def to_tensor(self, *, device: Optional[DeviceT] = None, copy: bool = False) -> Tensor: ...
+    def to_tensor(self, *, device: Optional[AnyDevice] = None, copy: bool = False) -> Tensor: ...
     def to_list(self, *, copy: bool = False) -> List[TT]: ...
 
     # === Device functions ===
+    @overload
     def to_device(self, device: DeviceT, /, *, stream: Optional[Any] = None) -> CompatArray[TT, DeviceT]: ...
+    @overload
+    def to_device(self, device: AnyDevice, /, *, stream: Optional[Any] = None) -> CompatArray[TT, AnyDevice]: ...
+
+    def to_device(self, device: AnyDevice, /, *, stream: Optional[Any] = None) -> CompatArray[Any, AnyDevice]: ...
 
     # === Data type functions ===
     @overload
-    def astype(self, dtype: DTypeT, /, *, copy: bool = ...) -> CompatArray[DTypeT, DT]: ...
+    def astype(self, dtype: DTypeT, /, *, copy: bool = ..., device: None = ...) -> CompatArray[DTypeT, DT]: ...
     @overload
     def astype(self, dtype: DTypeT, /, *, copy: bool = ..., device: DeviceT) -> CompatArray[DTypeT, DeviceT]: ...
+    @overload
+    def astype(self, dtype: DTypeT, /, *, copy: bool = ..., device: AnyDevice) -> CompatArray[DTypeT, AnyDevice]: ...
 
     def astype(
         self,
         dtype: DType,
         /, *,
         copy: bool = True,
-        device: Optional[Device] = None
-    ) -> CompatArray[Any, Any]:
+        device: Optional[AnyDevice] = None
+    ) -> CompatArray[Any, AnyDevice]:
         """
         Copies `self` to a specified data type irrespective of Type Promotion Rules rules.
 
@@ -88,8 +95,8 @@ class CompatArray(Compat, Generic[TT, DT]):
                     - `True`: `self` must be returned;
                     - `False`: A newly allocated array must be returned.
 
-            device : Optional[DeviceT], default to `None`
-                DeviceT on which to place the returned array.
+            device : Optional[AnyDevice], default to `None`
+                Device on which to place the returned array.
                 - `None`: The output array device must be inferred from `self`.
 
         Returns
@@ -1793,7 +1800,7 @@ class CompatArray(Compat, Generic[TT, DT]):
 
 
 @overload
-def unwrap(obj: CompatArray[dtypeT, Any]) -> ArrayLike[dtypeT]: ...
+def unwrap(obj: CompatArray[dtypeT, AnyDevice]) -> ArrayLike[dtypeT]: ...
 @overload
 def unwrap(obj: ArrayLike[dtypeT]) -> ArrayLike[dtypeT]: ...
 @overload
@@ -1808,7 +1815,7 @@ def wrap_arraylike(arr: NDArray[dtypeT], xp: Optional[object] = ...) -> CompatAr
 @overload
 def wrap_arraylike(arr: CompatArray[dtypeT, deviceT], xp: Optional[object] = ...) -> CompatArray[dtypeT, deviceT]: ...
 @overload
-def wrap_arraylike(arr: ArrayLike[dtypeT], xp: Optional[object] = ...) -> CompatArray[dtypeT, Any]: ...
+def wrap_arraylike(arr: ArrayLike[dtypeT], xp: Optional[object] = ...) -> CompatArray[dtypeT, AnyDevice]: ...
 @overload
 def wrap_arraylike(arr: T, xp: Optional[object] = ...) -> T: ...
 

{cobra_array-0.1.0 → cobra_array-0.1.2}/src/cobra_array/compat/_namespace.py

@@ -23,6 +23,31 @@ class CompatNamespace(Compat):
     - Functions correspond directly to those defined in the underlying `array namespace`, following the `Python Array API standard`.
     - This namespace complements :class:`CompatArray` by providing a functional interface for operations that are not naturally expressed as methods.
     - All functions guarantee that any array-like objects in the returned value are automatically wrapped as :class:`CompatArray`. This conversion is applied recursively to arrays contained in Python containers (e.g., `tuple`, `list`, `dict`). Non-array objects remain unchanged.
+
+    Examples
+    --------
+    Create a compatibility namespace from a backend namespace:
+
+    >>> import numpy as np
+    >>> cxp = CompatNamespace(np)
+    >>> cxp.xp_name
+    'NumPy'
+
+    Create arrays and call namespace functions:
+
+    >>> a = cxp.asarray([1, 2, 3])
+    >>> b = cxp.asarray([10, 20, 30])
+    >>> a
+    NumPy_Array([1 2 3])
+    >>> cxp.add(a, b).to_list()
+    [11, 22, 33]
+
+    Missing attributes raise an exception:
+
+    >>> cxp.this_attr_does_not_exist
+    Traceback (most recent call last):
+        ...
+    AttributeError: ...
     """
     def __new__(cls, xp, /):
         if isinstance(xp, CompatNamespace):