✨: add tomli dependency for Python version compatibility and load docstrings from TOML file

Signed-off-by: Nathaniel Starkman <[email protected]>

Author: nstarman

pyproject.toml

@@ -29,6 +29,7 @@
     "typing-extensions>=4.14.1",
     "optype>=0.9.3; python_version < '3.11'",
     "optype>=0.10.0; python_version >= '3.11'",
+    "tomli>=1.2.0 ; python_full_version < '3.11'",
   ]
 
   [project.urls]

src/array_api_typing/_array.py

@@ -5,6 +5,7 @@
     "NumericArray",
 )
 
+from pathlib import Path
 from types import ModuleType
 from typing import Literal, Protocol, TypeAlias
 from typing_extensions import TypeVar
@@ -13,6 +14,16 @@
 
 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)
 InputT = TypeVar("InputT")
 
@@ -40,302 +51,7 @@ def __array_namespace__(
     ) -> NS_co: ...
 
 
-@docstring_setter(
-    __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
-
-    """,  # noqa: E501
-    __iadd__="""Calculates the in-place 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: `self`, after performing the in-place addition. The returned array must have a data type determined by Type Promotion Rules.
-
-    See Also:
-        array_api_typing.Add
-
-    """,  # noqa: E501
-    __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
-
-    """,  # noqa: E501
-    __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
-
-    """,  # noqa: E501
-    __isub__="""Calculates the in-place difference for each element of an array instance with the respective element of the array `other`.
-
-    Args:
-        other: subtrahend array. Must be compatible with `self` (see
-            Broadcasting). Should have a numeric data type.
-
-    Returns:
-        Self: `self`, after performing the in-place subtraction. The returned array must have a data type determined by Type Promotion Rules.
-
-    See Also:
-        array_api_typing.Subtract
-
-    """,  # noqa: E501
-    __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
-
-    """,  # noqa: E501
-    __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
-
-    """,
-    __imul__="""Calculates the in-place 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: `self`, after performing the in-place multiplication. 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
-
-    """,
-    __itruediv__="""Calculates the in-place quotient for each element of an array instance with the respective element of the array `other`.
-
-    Args:
-        other: divisor array. Must be compatible with `self` (see Broadcasting). Should have a numeric data type.
-
-    Returns:
-        Self: `self`, after performing the in-place true division. The returned array must have a 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
-
-    """,  # noqa: E501
-    __ifloordiv__="""Calculates the in-place floor division for each element of an array instance with the respective element of the array `other`.
-
-    Args:
-        other: divisor array. Must be compatible with `self` (see Broadcasting). Should have a numeric data type.
-
-    Returns:
-        Self: `self`, after performing the in-place floor division. The returned array must have a data type determined by Type Promotion Rules.
-
-    See Also:
-        array_api_typing.FloorDiv
-
-    """,  # noqa: E501
-    __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
-
-    """,  # noqa: E501
-    __imod__="""Calculates the in-place remainder for each element of an array instance with the respective element of the array `other`.
-
-    Args:
-        other: divisor array. Must be compatible with `self` (see Broadcasting). Should have a numeric data type.
-
-    Returns:
-        Self: `self`, after performing the in-place modulo operation. The returned array must have a data type determined by Type Promotion Rules.
-
-    See Also:
-        array_api_typing.Remainder
-
-    """,  # noqa: E501
-    __mod__=r"""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
-
-    """,  # noqa: E501
-    __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
-
-    """,  # noqa: E501
-    __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.
-
-    """,  # noqa: E501
-    __ipow__="""Calculates the in-place power for each element of an array instance with the respective element of the array `other`.
-
-    Args:
-        other: exponent array. Must be compatible with `self` (see Broadcasting). Should have a numeric data type.
-
-    Returns:
-        Self: `self`, after performing the in-place power operation. The returned array must have a data type determined by Type Promotion Rules.
-
-    See Also:
-        array_api_typing.Power
-
-    """,  # noqa: E501
-    __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
-
-    """,  # noqa: E501
-)
+@docstring_setter(**_array_docstrings)
 class Array(
     HasArrayNamespace[NS_co],
     op.CanPosSelf,