✨ add CanArray* unop and binop protocols

Signed-off-by: Nathaniel Starkman <nstarman@users.noreply.github.com>

WIP

Signed-off-by: Nathaniel Starkman <nstarman@users.noreply.github.com>

Author: nstarman

pyproject.toml

@@ -29,6 +29,7 @@ dependencies = [
   "typing-extensions>=4.14.1",
   "optype>=0.9.3; python_version < '3.11'",
   "optype>=0.12.2; python_version >= '3.11'",
+  "tomli>=1.2.0 ; python_full_version < '3.11'",
 ]
 
 [project.urls]
@@ -123,9 +124,12 @@ ignore = [
   "D107", # Missing docstring in __init__
   "D203", # 1 blank line required before class docstring
   "D213", # Multi-line docstring summary should start at the second line
+  "D401", # First line of docstring should be in imperative mood
   "FBT", # flake8-boolean-trap
   "FIX", # flake8-fixme
   "ISC001", # Conflicts with formatter
+  "PLW1641", # Object does not implement `__hash__` method
+  "PYI041", # Use `float` instead of `int | float`
 ]
 
 [tool.ruff.lint.pylint]

src/array_api_typing/_array.py

@@ -1,13 +1,32 @@
 __all__ = (
     "Array",
+    "BoolArray",
     "HasArrayNamespace",
+    "NumericArray",
 )
 
+from pathlib import Path
 from types import ModuleType
-from typing import Literal, Protocol
+from typing import Literal, Never, Protocol, TypeAlias
 from typing_extensions import TypeVar
 
+import optype as op
+
+from ._utils import docstring_setter
+
+# Load docstrings from TOML file
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib  # type: ignore[import-not-found, no-redef]
+
+_docstrings_path = Path(__file__).parent / "_array_docstrings.toml"
+with _docstrings_path.open("rb") as f:
+    _array_docstrings = tomllib.load(f)["docstrings"]
+
 NS_co = TypeVar("NS_co", covariant=True, default=ModuleType)
+T_contra = TypeVar("T_contra", contravariant=True)
+R_co = TypeVar("R_co", covariant=True, default=Never)
 
 
 class HasArrayNamespace(Protocol[NS_co]):
@@ -33,8 +52,37 @@ def __array_namespace__(
     ) -> NS_co: ...
 
 
+@docstring_setter(**_array_docstrings)
 class Array(
     HasArrayNamespace[NS_co],
-    Protocol[NS_co],
+    op.CanPosSelf,
+    op.CanNegSelf,
+    op.CanAddSame[T_contra, R_co],
+    op.CanSubSame[T_contra, R_co],
+    op.CanMulSame[T_contra, R_co],
+    op.CanTruedivSame[T_contra, R_co],
+    op.CanFloordivSame[T_contra, R_co],
+    op.CanModSame[T_contra, R_co],
+    op.CanPowSame[T_contra, R_co],
+    Protocol[T_contra, R_co, NS_co],
 ):
     """Array API specification for array object attributes and methods."""
+
+
+BoolArray: TypeAlias = Array[bool, Array[float, Never, NS_co], NS_co]
+"""Array API specification for boolean array object attributes and methods.
+
+Specifically, this type alias fills the `T_contra` type variable with
+`bool`, allowing for `bool` objects to be added, subtracted, multiplied, etc. to
+the array object.
+
+"""
+
+NumericArray: TypeAlias = Array[float | int, NS_co]
+"""Array API specification for numeric array object attributes and methods.
+
+Specifically, this type alias fills the `T_contra` type variable with `float
+| int`, allowing for `float | int` objects to be added, subtracted, multiplied,
+etc. to the array object.
+
+"""

src/array_api_typing/_array_docstrings.toml

@@ -0,0 +1,275 @@
+[docstrings]
+__pos__ = '''
+Evaluates `+self_i` for each element of an array instance.
+
+Returns:
+    Self: An array containing the evaluated result for each element.
+        The returned array must have the same data type as `self`.
+
+See Also:
+    array_api_typing.Positive
+
+'''
+
+__neg__ = '''
+Evaluates `-self_i` for each element of an array instance.
+
+Returns:
+    Self: an array containing the evaluated result for each element in
+        `self`. The returned array must have a data type determined by Type
+        Promotion Rules.
+
+See Also:
+    array_api_typing.Negative
+
+'''
+
+__add__ = '''
+Calculates the sum for each element of an array instance with the respective
+element of the array `other`.
+
+Args:
+    other: addend array. Must be compatible with `self` (see
+        Broadcasting). Should have a numeric data type.
+
+Returns:
+    Self: an array containing the element-wise sums. The returned array
+        must have a data type determined by Type Promotion Rules.
+
+See Also:
+    array_api_typing.Add
+
+'''
+
+__radd__ = '''
+Calculates the sum for each element of the array `other` with the respective
+element of an array instance.
+
+Args:
+    other: addend array. Must be compatible with `self` (see Broadcasting).
+        Should have a numeric data type.
+
+Returns:
+    Self: an array containing the element-wise sums. The returned array
+        must have a data type determined by Type Promotion Rules.
+
+See Also:
+    array_api_typing.Add
+
+'''
+
+__sub__ = '''
+Calculates the difference for each element of an array instance with the
+respective element of the array other.
+
+The result of `self_i - other_i` must be the same as `self_i +
+(-other_i)` and must be governed by the same floating-point rules as
+addition (see `CanArrayAdd`).
+
+Args:
+    other: subtrahend array. Must be compatible with `self` (see
+        Broadcasting). Should have a numeric data type.
+
+Returns:
+    Self: an array containing the element-wise differences. The returned
+        array must have a data type determined by Type Promotion Rules.
+
+See Also:
+    array_api_typing.Subtract
+
+'''
+
+__rsub__ = '''
+Calculates the difference for each element of the array `other` with the
+respective element of an array instance.
+
+The result of `other_i - self_i` must be the same as `other_i + (-self_i)`
+and must be governed by the same floating-point rules as addition (see
+`CanArrayAdd`).
+
+Args:
+    other: minuend array. Must be compatible with `self` (see Broadcasting).
+        Should have a numeric data type.
+
+Returns:
+    Self: an array containing the element-wise differences. The returned
+        array must have a data type determined by Type Promotion Rules.
+
+See Also:
+    array_api_typing.Subtract
+
+'''
+
+__mul__ = '''
+Calculates the product for each element of an array instance with the
+respective element of the array `other`.
+
+Args:
+    other: multiplicand array. Must be compatible with `self` (see
+        Broadcasting). Should have a numeric data type.
+
+Returns:
+    Self: an array containing the element-wise products. The returned
+        array must have a data type determined by Type Promotion Rules.
+
+See Also:
+    array_api_typing.Multiply
+
+'''
+
+__rmul__ = '''
+Calculates the product for each element of the array `other` with the
+respective element of an array instance.
+
+Args:
+    other: multiplicand array. Must be compatible with `self` (see
+        Broadcasting). Should have a numeric data type.
+
+Returns:
+    Self: an array containing the element-wise products. The returned array
+        must have a data type determined by Type Promotion Rules.
+
+See Also:
+    array_api_typing.Multiply
+
+'''
+
+__truediv__ = '''
+Evaluates `self_i / other_i` for each element of an array instance with the
+respective element of the array `other`.
+
+Args:
+    other: Must be compatible with `self` (see Broadcasting). Should have a
+        numeric data type.
+
+Returns:
+    Self: an array containing the element-wise results. The returned array
+        should have a floating-point data type determined by Type Promotion
+        Rules.
+
+See Also:
+    array_api_typing.TrueDiv
+
+'''
+
+__rtruediv__ = '''
+Calculates the quotient for each element of the array `other` with the
+respective element of an array instance.
+
+Args:
+    other: dividend array. Must be compatible with `self` (see Broadcasting).
+        Should have a numeric data type.
+
+Returns:
+    Self: an array containing the element-wise quotients. The returned
+        array must have a data type determined by Type Promotion Rules.
+
+See Also:
+    array_api_typing.TrueDiv
+
+'''
+
+__floordiv__ = '''
+Evaluates `self_i // other_i` for each element of an array instance with the
+respective element of the array `other`.
+
+Args:
+    other: Must be compatible with `self` (see Broadcasting). Should have a
+        numeric data type.
+
+Returns:
+    Self: an array containing the element-wise results. The returned array
+        must have a data type determined by Type Promotion Rules.
+
+See Also:
+    array_api_typing.FloorDiv
+
+'''
+
+__rfloordiv__ = '''
+Calculates the floor division for each element of the array `other` with the
+respective element of an array instance.
+
+Args:
+    other: dividend array. Must be compatible with `self` (see Broadcasting).
+        Should have a numeric data type.
+
+Returns:
+    Self: an array containing the element-wise floor division results. The
+        returned array must have a data type determined by Type Promotion
+        Rules.
+
+See Also:
+    array_api_typing.FloorDiv
+
+'''
+
+__mod__ = '''
+Evaluates `self_i % other_i` for each element of an array instance with the
+respective element of the array `other`.
+
+Args:
+    other: Must be compatible with `self` (see Broadcasting). Should have a
+        numeric data type.
+
+Returns:
+    Self: an array containing the element-wise results. Each element-wise
+        result must have the same sign as the respective element `other_i`.
+        The returned array must have a floating-point data type determined
+        by Type Promotion Rules.
+
+See Also:
+    array_api_typing.Remainder
+
+'''
+
+__rmod__ = '''
+Calculates the remainder for each element of the array `other` with the
+respective element of an array instance.
+
+Args:
+    other: dividend array. Must be compatible with `self` (see Broadcasting).
+        Should have a numeric data type.
+
+Returns:
+    Self: an array containing the element-wise remainders. The returned
+        array must have a data type determined by Type Promotion Rules.
+
+See Also:
+    array_api_typing.Remainder
+
+'''
+
+__pow__ = '''
+Calculates an implementation-dependent approximation of exponentiation by
+raising each element (the base) of an array instance to the power of
+`other_i` (the exponent), where `other_i` is the corresponding element of
+the array `other`.
+
+Args:
+    other: array whose elements correspond to the exponentiation exponent.
+        Must be compatible with `self` (see Broadcasting). Should have a
+        numeric data type.
+
+Returns:
+    Self: an array containing the element-wise results. The returned array
+        must have a data type determined by Type Promotion Rules.
+
+'''
+
+__rpow__ = '''
+Calculates the power for each element of the array `other` raised to the
+respective element of an array instance.
+
+Args:
+    other: base array. Must be compatible with `self` (see Broadcasting).
+        Should have a numeric data type.
+
+Returns:
+    Self: an array containing the element-wise powers. The returned array
+        must have a data type determined by Type Promotion Rules.
+
+See Also:
+    array_api_typing.Power
+
+'''