oprattr 0.6.0__tar.gz → 0.8.0__tar.gz

{oprattr-0.6.0 → oprattr-0.8.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## NEXT
 
+## v0.8.0
+
+- Redefine `mixins.NumpyMixin` to extend `numerical.NumpyMixin`
+- Redefine `Object` to extend `numerical.Object`
+- Improve flexibility of `numpy` functions in `Operand`
+- Update types in `__init__.pyi`
+
+## v0.7.0
+
+- Add `oprattr.Object` and `oprattr.Quantity` to the public namespace
+- Rename modules that should not be part of the public namespace
+- Define the `OperationError` exception class
+- Change default behavior when a metadata attribute does not implement an operation
+
 ## v0.6.0
 
 - Add `methods` module

{oprattr-0.6.0 → oprattr-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oprattr
-Version: 0.6.0
+Version: 0.8.0
 Summary: Add your description here
 Author-email: Matthew Young <myoung.space.science@gmail.com>
 License-File: LICENSE

{oprattr-0.6.0 → oprattr-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oprattr"
-version = "0.6.0"
+version = "0.8.0"
 description = "Add your description here"
 readme = "README.md"
 authors = [
@@ -24,4 +24,4 @@ dev = [
 ]
 
 [tool.uv.sources]
-numerical = { git = "https://github.com/myoung-space-science/numerical", rev = "v0.2.0" }
+numerical = { git = "https://github.com/myoung-space-science/numerical", rev = "v0.3.0" }

oprattr-0.8.0/src/oprattr/__init__.py

@@ -0,0 +1,128 @@
+import collections.abc
+import functools
+
+import numpy
+
+from ._abstract import (
+    Quantity,
+    Object,
+)
+from ._exceptions import (
+    MetadataTypeError,
+    MetadataValueError,
+    OperationError,
+)
+from . import methods
+from . import mixins
+from . import _typeface
+from ._operations import (
+    unary,
+    equality,
+    ordering,
+    additive,
+    multiplicative,
+)
+
+
+T = _typeface.TypeVar('T')
+
+class Operand(Object[T], mixins.NumpyMixin):
+    """A concrete implementation of a real-valued object."""
+
+    __abs__ = methods.__abs__
+    __pos__ = methods.__pos__
+    __neg__ = methods.__neg__
+
+    __eq__ = methods.__eq__
+    __ne__ = methods.__ne__
+    __lt__ = methods.__lt__
+    __le__ = methods.__le__
+    __gt__ = methods.__gt__
+    __ge__ = methods.__ge__
+
+    __add__ = methods.__add__
+    __radd__ = methods.__radd__
+    __sub__ = methods.__sub__
+    __rsub__ = methods.__rsub__
+    __mul__ = methods.__mul__
+    __rmul__ = methods.__rmul__
+    __truediv__ = methods.__truediv__
+    __rtruediv__ = methods.__rtruediv__
+    __floordiv__ = methods.__floordiv__
+    __rfloordiv__ = methods.__rfloordiv__
+    __mod__ = methods.__mod__
+    __rmod__ = methods.__rmod__
+    __pow__ = methods.__pow__
+    __rpow__ = methods.__rpow__
+
+    def __array__(self, *args, **kwargs):
+        """Called for numpy.array(self)."""
+        return numpy.array(self._data, *args, **kwargs)
+
+    def _apply_ufunc(self, ufunc, method, *args, **kwargs):
+        if ufunc in (numpy.equal, numpy.not_equal):
+            # NOTE: We are probably here because the left operand is a
+            # `numpy.ndarray`, which would otherwise take control and return the
+            # pure `numpy` result.
+            f = getattr(ufunc, method)
+            return equality(f, *args)
+        data, meta = super()._apply_ufunc(ufunc, method, *args, **kwargs)
+        return self._from_numpy(data, **meta)
+
+    def _apply_function(self, func, types, args, kwargs):
+        data, meta = super()._apply_function(func, types, args, kwargs)
+        if data is NotImplemented:
+            return data
+        return self._from_numpy(data, **meta)
+
+    def _get_numpy_array(self):
+        return numpy.array(self._data)
+
+    def _from_numpy(self, data, **meta):
+        """Create a new instance after applying a numpy function."""
+        if isinstance(data, (list, tuple)):
+            r = [self._factory(array, **meta) for array in data]
+            if isinstance(data, tuple):
+                return tuple(r)
+            return r
+        return self._factory(data, **meta)
+
+    def _factory(self, data, **meta):
+        """Create a new instance from data and metadata.
+
+        The default implementation uses the standard `__new__` constructor.
+        Subclasses may overload this method to use a different constructor
+        (e.g., a module-defined factory function).
+        """
+        return type(self)(data, **meta)
+
+
+@Operand.implementation(numpy.array_equal)
+def array_equal(
+    x: numpy.typing.ArrayLike,
+    y: numpy.typing.ArrayLike,
+    **kwargs
+) -> bool:
+    """Called for numpy.array_equal(x, y)"""
+    return numpy.array_equal(numpy.array(x), numpy.array(y), **kwargs)
+
+
+__all__ = [
+    # Modules
+    methods,
+    mixins,
+    # Object classes
+    Quantity,
+    Object,
+    # Error classes
+    MetadataTypeError,
+    MetadataValueError,
+    OperationError,
+    # Functions
+    additive,
+    equality,
+    multiplicative,
+    ordering,
+    unary,
+]
+

oprattr-0.8.0/src/oprattr/__init__.pyi

@@ -0,0 +1,123 @@
+import collections.abc
+
+import numpy.typing
+
+from . import _abstract
+from . import methods
+from . import mixins
+from . import _typeface
+from ._abstract import (
+    Quantity,
+    Object,
+)
+from ._exceptions import (
+    MetadataTypeError,
+    MetadataValueError,
+    OperationError,
+)
+from ._operations import (
+    unary,
+    equality,
+    ordering,
+    additive,
+    multiplicative,
+)
+
+
+T = _typeface.TypeVar('T')
+
+class Operand(_abstract.Object[T], mixins.Numpy):
+    """A concrete implementation of a real-valued object."""
+
+    def __abs__(self) -> _typeface.Self:
+        """Called for abs(self)."""
+
+    def __pos__(self) -> _typeface.Self:
+        """Called for +self."""
+
+    def __neg__(self) -> _typeface.Self:
+        """Called for -self."""
+
+    def __eq__(self, other) -> bool:
+        """Called for self == other."""
+
+    def __ne__(self, other) -> bool:
+        """Called for self != other."""
+
+    def __lt__(self, other) -> bool | numpy.typing.NDArray[numpy.bool]:
+        """Called for self < other."""
+
+    def __le__(self, other) -> bool | numpy.typing.NDArray[numpy.bool]:
+        """Called for self <= other."""
+
+    def __gt__(self, other) -> bool | numpy.typing.NDArray[numpy.bool]:
+        """Called for self > other."""
+
+    def __ge__(self, other) -> bool | numpy.typing.NDArray[numpy.bool]:
+        """Called for self >= other."""
+
+    def __add__(self, other) -> _typeface.Self:
+        """Called for self + other."""
+
+    def __radd__(self, other) -> _typeface.Self:
+        """Called for other + self."""
+
+    def __sub__(self, other) -> _typeface.Self:
+        """Called for self - other."""
+
+    def __rsub__(self, other) -> _typeface.Self:
+        """Called for other - self."""
+
+    def __mul__(self, other) -> _typeface.Self:
+        """Called for self * other."""
+
+    def __rmul__(self, other) -> _typeface.Self:
+        """Called for other * self."""
+
+    def __truediv__(self, other) -> _typeface.Self:
+        """Called for self / other."""
+
+    def __rtruediv__(self, other) -> _typeface.Self:
+        """Called for other / self."""
+
+    def __floordiv__(self, other) -> _typeface.Self:
+        """Called for self // other."""
+
+    def __rfloordiv__(self, other) -> _typeface.Self:
+        """Called for other // self."""
+
+    def __mod__(self, other) -> _typeface.Self:
+        """Called for self % other."""
+
+    def __rmod__(self, other) -> _typeface.Self:
+        """Called for other % self."""
+
+    def __pow__(self, other) -> _typeface.Self:
+        """Called for self ** other."""
+
+    def __rpow__(self, other):
+        """Called for other ** self."""
+
+    def __array__(self, *args, **kwargs) -> numpy.typing.NDArray:
+        """Called for numpy.array(self)."""
+
+
+__all__ = [
+    # Modules
+    methods,
+    mixins,
+    # Object classes
+    Quantity,
+    Object,
+    # Functions
+    unary,
+    equality,
+    ordering,
+    additive,
+    multiplicative,
+    # Error classes
+    MetadataTypeError,
+    MetadataValueError,
+    OperationError,
+]
+

oprattr-0.6.0/src/oprattr/abstract.py → oprattr-0.8.0/src/oprattr/_abstract.py

@@ -4,10 +4,10 @@ import numbers
 import numerical
 import numpy.typing
 
-from . import typeface
+from . import _typeface
 
 
-DataType = typeface.TypeVar(
+DataType = _typeface.TypeVar(
     'DataType',
     int,
     float,
@@ -18,14 +18,14 @@ DataType = typeface.TypeVar(
 )
 
 
-@typeface.runtime_checkable
-class Quantity(numerical.Quantity[DataType], typeface.Protocol):
+@_typeface.runtime_checkable
+class Quantity(numerical.Quantity[DataType], _typeface.Protocol):
     """Protocol for numerical objects with metadata."""
 
-    _meta: collections.abc.Mapping[str, typeface.Any]
+    _meta: collections.abc.Mapping[str, _typeface.Any]
 
 
-class Object(numerical.Real, typeface.Generic[DataType]):
+class Object(numerical.Object[DataType], numerical.Real):
     """A real-valued object with metadata attributes."""
 
     def __init__(
@@ -35,7 +35,7 @@ class Object(numerical.Real, typeface.Generic[DataType]):
     ) -> None:
         if not isinstance(__data, numerical.Real):
             raise TypeError("Data input to Object must be real-valued")
-        self._data = __data
+        super().__init__(__data)
         self._meta = metadata
 
     def __str__(self):

oprattr-0.8.0/src/oprattr/_exceptions.py

@@ -0,0 +1,17 @@
+class MetadataTypeError(TypeError):
+    """A metadata-related TypeError occurred."""
+
+
+class MetadataValueError(ValueError):
+    """A metadata-related ValueError occurred."""
+
+
+class OperationError(NotImplementedError):
+    """A metadata attribute does not support this operation.
+    
+    The default behavior when applying an operator to a metadata attribute of
+    `~Operand` is to copy the current value if the attribute does not define the
+    operation. Custom metadata attributes may raise this exception to indicate
+    that attempting to apply the operator is truly an error.
+    """
+

{oprattr-0.6.0 → oprattr-0.8.0}/src/oprattr/_operations.py

@@ -1,17 +1,13 @@
 from numerical import operators
 
-from .abstract import (
+from ._abstract import (
     Quantity,
     Object,
 )
-
-
-class MetadataTypeError(TypeError):
-    """A metadata-related TypeError occurred."""
-
-
-class MetadataValueError(ValueError):
-    """A metadata-related ValueError occurred."""
+from ._exceptions import (
+    MetadataTypeError,
+    MetadataValueError,
+)
 
 
 def _build_error_message(

oprattr-0.8.0/src/oprattr/mixins.py

@@ -0,0 +1,148 @@
+import collections.abc
+
+import numerical
+
+from ._abstract import Quantity
+from ._exceptions import OperationError
+from . import _typeface
+
+
+T = _typeface.TypeVar('T')
+
+class Real:
+    """Mixin for adding basic real-valued operator support."""
+
+    def __abs__(self):
+        return self
+
+    def __pos__(self):
+        return self
+
+    def __neg__(self):
+        return self
+
+    def __eq__(self, other):
+        return False
+
+    def __ne__(self, other):
+        return not (self == other)
+
+    def __lt__(self, other):
+        return False
+
+    def __le__(self, other):
+        return (self < other) and (self == other)
+
+    def __gt__(self, other):
+        return not (self <= other)
+
+    def __ge__(self, other):
+        return not (self < other)
+
+    def __add__(self, other):
+        return self
+
+    def __radd__(self, other):
+        return self
+
+    def __sub__(self, other):
+        return self
+
+    def __rsub__(self, other):
+        return self
+
+    def __mul__(self, other):
+        return self
+
+    def __rmul__(self, other):
+        return self
+
+    def __truediv__(self, other):
+        return self
+
+    def __rtruediv__(self, other):
+        return self
+
+    def __floordiv__(self, other):
+        return self
+
+    def __rfloordiv__(self, other):
+        return self
+
+    def __mod__(self, other):
+        return self
+
+    def __rmod__(self, other):
+        return self
+
+    def __pow__(self, other):
+        return self
+
+    def __rpow__(self, other):
+        return self
+
+
+UserFunction = collections.abc.Callable[..., T]
+
+class NumpyMixin(numerical.mixins.NumpyMixin):
+    """Mixin for adding `numpy` support to objects with metadata.
+
+    Notes
+    -----
+    - This class extends `numerical.mixins.NumpyMixin`. See that class for
+      further documentation.
+    """
+
+    def _apply_ufunc(self, ufunc, method, *args, **kwargs):
+        data = super()._apply_ufunc(ufunc, method, *args, **kwargs)
+        f = getattr(ufunc, method)
+        types = [type(arg) for arg in args]
+        try:
+            meta = self._apply_operator_to_metadata(f, *args, **kwargs)
+        except OperationError as err:
+            raise TypeError(
+                f"Cannot apply numpy.{ufunc} to arguments with type(s) {types}"
+            ) from err
+        if method != 'at':
+            return data, meta
+
+    def _apply_function(self, func, types, args, kwargs):
+        data = super()._apply_function(func, types, args, kwargs)
+        try:
+            meta = self._apply_operator_to_metadata(func, *args, **kwargs)
+        except OperationError as err:
+            raise TypeError(
+                f"Cannot apply numpy.{func} to arguments with type(s) {types}"
+            ) from err
+        return data, meta
+
+    def _apply_operator_to_metadata(self, f, *args, **kwargs):
+        """Apply a numpy universal or public function to arguments."""
+        keys = {
+            k
+            for x in args
+            if isinstance(x, Quantity)
+            for k in x._meta.keys()
+        }
+        meta = {}
+        for key in keys:
+            values = [
+                x._meta[key]
+                if isinstance(x, Quantity) else x
+                for x in args
+            ]
+            try:
+                result = f(*values, **kwargs)
+            except TypeError as err:
+                if len(values) > 1 and any(v != values[0] for v in values):
+                    raise err # TODO: More descriptive error message
+                else:
+                    meta[key] = values[0]
+            except OperationError as err:
+                raise TypeError(
+                    f"Attribute {key!r} does not support this operation"
+                ) from err
+            else:
+                meta[key] = result
+        return meta.copy()
+

{oprattr-0.6.0 → oprattr-0.8.0}/tests/test_object.py

@@ -1,13 +1,14 @@
 import itertools
 import numbers
 
+import numerical
 import numpy
 import pytest
 
 import oprattr
 
 
-class Symbol(oprattr.mixins.Numpy):
+class Symbol(numerical.mixins.NumpyMixin):
     """A symbolic test attribute."""
 
     def __init__(self, __x: str):
@@ -157,11 +158,6 @@ def symbol_gradient(x: Symbol, **kwargs):
     return f"numpy.gradient({x})"
 
 
-@Symbol.implementation(numpy.trapezoid)
-def symbol_trapezoid(x: Symbol, **kwargs):
-    return f"numpy.trapezoid({x})"
-
-
 def symbolic_binary(a, op, b):
     if isinstance(a, (Symbol, str)) and isinstance(b, (Symbol, str)):
         return f"{a} {op} {b}"
@@ -502,26 +498,29 @@ def test_gradient():
     grad = numpy.gradient(v)
     for t, g in zip(that, grad):
         assert isinstance(t, oprattr.Operand)
-        assert numpy.array_equal(t, x(g, name=nR))
+        assert numpy.array_equal(t, g)
+        assert t._meta['name'] == nR
     for axis in range(v.ndim):
         that = numpy.gradient(this, axis=axis)
         assert isinstance(that, oprattr.Operand)
         grad = numpy.gradient(v, axis=axis)
-        assert numpy.array_equal(that, x(grad, name=nR))
+        assert numpy.array_equal(that, grad)
+        assert t._meta['name'] == nR
 
 
 def test_trapezoid():
-    """Test `numpy.trapezoid`."""
+    """Test `numpy.trapezoid`, which `Symbol` does not implement."""
     nA = Symbol('A')
-    nR = Symbol('numpy.trapezoid(A)')
     v = numpy.arange(3*4*5).reshape(3, 4, 5)
     this = x(v, name=nA)
     that = numpy.trapezoid(this)
     assert isinstance(that, oprattr.Operand)
-    assert numpy.array_equal(that, x(numpy.trapezoid(v), name=nR))
+    assert numpy.array_equal(that, numpy.trapezoid(v))
+    assert that._meta['name'] == nA
     for axis in range(v.ndim):
         that = numpy.trapezoid(this, axis=axis)
         assert isinstance(that, oprattr.Operand)
         trap = numpy.trapezoid(v, axis=axis)
-        assert numpy.array_equal(that, x(trap, name=nR))
+        assert numpy.array_equal(that, trap)
+        assert that._meta['name'] == nA
 

{oprattr-0.6.0 → oprattr-0.8.0}/uv.lock

@@ -108,8 +108,8 @@ wheels = [
 
 [[package]]
 name = "numerical"
-version = "0.2.0"
-source = { git = "https://github.com/myoung-space-science/numerical?rev=v0.2.0#a6e3af04c8815fc82cd06b66696392daf50b4f2c" }
+version = "0.3.0"
+source = { git = "https://github.com/myoung-space-science/numerical?rev=v0.3.0#b4a46e5e93e8d256c1198aec22d5556ea041673b" }
 dependencies = [
     { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "numpy", version = "2.3.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
@@ -267,7 +267,7 @@ wheels = [
 
 [[package]]
 name = "oprattr"
-version = "0.2.0"
+version = "0.7.0"
 source = { editable = "." }
 dependencies = [
     { name = "numerical" },
@@ -284,7 +284,7 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "numerical", git = "https://github.com/myoung-space-science/numerical?rev=v0.2.0" },
+    { name = "numerical", git = "https://github.com/myoung-space-science/numerical?rev=v0.3.0" },
     { name = "numpy", specifier = ">=2.2.1" },
     { name = "scipy", specifier = ">=1.15.0" },
 ]

oprattr-0.6.0/src/oprattr/__init__.py

@@ -1,139 +0,0 @@
-import collections.abc
-import functools
-
-import numpy
-
-from . import abstract
-from . import methods
-from . import mixins
-from . import typeface
-from ._operations import equality
-
-
-T = typeface.TypeVar('T')
-
-
-class Operand(abstract.Object[T], mixins.Numpy):
-    """A concrete implementation of a real-valued object."""
-
-    __abs__ = methods.__abs__
-    __pos__ = methods.__pos__
-    __neg__ = methods.__neg__
-
-    __eq__ = methods.__eq__
-    __ne__ = methods.__ne__
-    __lt__ = methods.__lt__
-    __le__ = methods.__le__
-    __gt__ = methods.__gt__
-    __ge__ = methods.__ge__
-
-    __add__ = methods.__add__
-    __radd__ = methods.__radd__
-    __sub__ = methods.__sub__
-    __rsub__ = methods.__rsub__
-    __mul__ = methods.__mul__
-    __rmul__ = methods.__rmul__
-    __truediv__ = methods.__truediv__
-    __rtruediv__ = methods.__rtruediv__
-    __floordiv__ = methods.__floordiv__
-    __rfloordiv__ = methods.__rfloordiv__
-    __mod__ = methods.__mod__
-    __rmod__ = methods.__rmod__
-    __pow__ = methods.__pow__
-    __rpow__ = methods.__rpow__
-
-    def __array__(self, *args, **kwargs):
-        """Called for numpy.array(self)."""
-        return numpy.array(self._data, *args, **kwargs)
-
-    def _apply_ufunc(self, ufunc, method, *args, **kwargs):
-        if ufunc in (numpy.equal, numpy.not_equal):
-            # NOTE: We are probably here because the left operand is a
-            # `numpy.ndarray`, which would otherwise take control and return the
-            # pure `numpy` result.
-            f = getattr(ufunc, method)
-            return equality(f, *args)
-        return super()._apply_ufunc(ufunc, method, *args, **kwargs)
-
-
-@Operand.implementation(numpy.array_equal)
-def array_equal(
-    x: numpy.typing.ArrayLike,
-    y: numpy.typing.ArrayLike,
-    **kwargs
-) -> bool:
-    """Called for numpy.array_equal(x, y)"""
-    return numpy.array_equal(numpy.array(x), numpy.array(y), **kwargs)
-
-
-@Operand.implementation(numpy.gradient)
-def gradient(x: Operand[T], *args, **kwargs):
-    """Called for numpy.gradient(x)."""
-    data = numpy.gradient(x._data, *args, **kwargs)
-    meta = {}
-    for key, value in x._meta.items():
-        try:
-            v = numpy.gradient(value, **kwargs)
-        except TypeError as exc:
-            raise TypeError(
-                "Cannot compute numpy.gradient(x)"
-                f" because metadata attribute {key!r}"
-                " does not support this operation"
-            ) from exc
-        else:
-            meta[key] = v
-    if isinstance(data, (list, tuple)):
-        r = [type(x)(array, **meta) for array in data]
-        if isinstance(data, tuple):
-            return tuple(r)
-        return r
-    return type(x)(data, **meta)
-
-
-def wrapnumpy(f: collections.abc.Callable):
-    """Implement a numpy function for objects with metadata."""
-    @functools.wraps(f)
-    def method(x: Operand[T], **kwargs):
-        """Apply a numpy function to x."""
-        data = f(x._data, **kwargs)
-        meta = {}
-        for key, value in x._meta.items():
-            try:
-                v = f(value, **kwargs)
-            except TypeError as exc:
-                raise TypeError(
-                    f"Cannot compute numpy.{f.__qualname__}(x)"
-                    f" because metadata attribute {key!r}"
-                    " does not support this operation"
-                ) from exc
-            else:
-                meta[key] = v
-        return type(x)(data, **meta)
-    return method
-
-
-_OPERAND_UFUNCS = (
-    numpy.sqrt,
-    numpy.sin,
-    numpy.cos,
-    numpy.tan,
-    numpy.log,
-    numpy.log2,
-    numpy.log10,
-)
-
-
-_OPERAND_FUNCTIONS = (
-    numpy.squeeze,
-    numpy.mean,
-    numpy.sum,
-    numpy.cumsum,
-    numpy.transpose,
-    numpy.trapezoid,
-)
-
-
-for f in _OPERAND_UFUNCS + _OPERAND_FUNCTIONS:
-    Operand.implement(f, wrapnumpy(f))
-
-

oprattr-0.6.0/src/oprattr/__init__.pyi

@@ -1,81 +0,0 @@
-import numpy.typing
-
-from . import abstract
-from . import mixins
-from . import typeface
-
-
-T = typeface.TypeVar('T')
-
-class Operand(abstract.Object[T], mixins.Numpy):
-    """A concrete implementation of a real-valued object."""
-
-    def __abs__(self) -> typeface.Self:
-        """Called for abs(self)."""
-
-    def __pos__(self) -> typeface.Self:
-        """Called for +self."""
-
-    def __neg__(self) -> typeface.Self:
-        """Called for -self."""
-
-    def __eq__(self, other) -> bool:
-        """Called for self == other."""
-
-    def __ne__(self, other) -> bool:
-        """Called for self != other."""
-
-    def __lt__(self, other) -> bool | numpy.typing.NDArray[numpy.bool]:
-        """Called for self < other."""
-
-    def __le__(self, other) -> bool | numpy.typing.NDArray[numpy.bool]:
-        """Called for self <= other."""
-
-    def __gt__(self, other) -> bool | numpy.typing.NDArray[numpy.bool]:
-        """Called for self > other."""
-
-    def __ge__(self, other) -> bool | numpy.typing.NDArray[numpy.bool]:
-        """Called for self >= other."""
-
-    def __add__(self, other) -> typeface.Self:
-        """Called for self + other."""
-
-    def __radd__(self, other) -> typeface.Self:
-        """Called for other + self."""
-
-    def __sub__(self, other) -> typeface.Self:
-        """Called for self - other."""
-
-    def __rsub__(self, other) -> typeface.Self:
-        """Called for other - self."""
-
-    def __mul__(self, other) -> typeface.Self:
-        """Called for self * other."""
-
-    def __rmul__(self, other) -> typeface.Self:
-        """Called for other * self."""
-
-    def __truediv__(self, other) -> typeface.Self:
-        """Called for self / other."""
-
-    def __rtruediv__(self, other) -> typeface.Self:
-        """Called for other / self."""
-
-    def __floordiv__(self, other) -> typeface.Self:
-        """Called for self // other."""
-
-    def __rfloordiv__(self, other) -> typeface.Self:
-        """Called for other // self."""
-
-    def __mod__(self, other) -> typeface.Self:
-        """Called for self % other."""
-
-    def __rmod__(self, other) -> typeface.Self:
-        """Called for other % self."""
-
-    def __pow__(self, other) -> typeface.Self:
-        """Called for self ** other."""
-
-    def __rpow__(self, other):
-        """Called for other ** self."""
-

oprattr-0.6.0/src/oprattr/mixins.py

@@ -1,489 +0,0 @@
-import collections.abc
-import numbers
-
-import numpy
-
-from . import abstract
-from . import typeface
-
-
-T = typeface.TypeVar('T')
-
-
-class Real:
-    """Mixin for adding basic real-valued operator support."""
-
-    def __abs__(self):
-        return self
-
-    def __pos__(self):
-        return self
-
-    def __neg__(self):
-        return self
-
-    def __eq__(self, other):
-        return False
-
-    def __ne__(self, other):
-        return not (self == other)
-
-    def __lt__(self, other):
-        return False
-
-    def __le__(self, other):
-        return (self < other) and (self == other)
-
-    def __gt__(self, other):
-        return not (self <= other)
-
-    def __ge__(self, other):
-        return not (self < other)
-
-    def __add__(self, other):
-        return self
-
-    def __radd__(self, other):
-        return self
-
-    def __sub__(self, other):
-        return self
-
-    def __rsub__(self, other):
-        return self
-
-    def __mul__(self, other):
-        return self
-
-    def __rmul__(self, other):
-        return self
-
-    def __truediv__(self, other):
-        return self
-
-    def __rtruediv__(self, other):
-        return self
-
-    def __floordiv__(self, other):
-        return self
-
-    def __rfloordiv__(self, other):
-        return self
-
-    def __mod__(self, other):
-        return self
-
-    def __rmod__(self, other):
-        return self
-
-    def __pow__(self, other):
-        return self
-
-    def __rpow__(self, other):
-        return self
-
-
-UserFunction = collections.abc.Callable[..., T]
-
-
-class Numpy:
-    """Mixin for adding support for `numpy` functions to numeric objects.
-    
-    Classes that inherit from this class may implement support for `numpy`
-    universal functions ("ufuncs"; e.g., `numpy.sqrt`) by overloading
-    `_apply_ufunc`, and may implement support for `numpy` public functions
-    (e.g., `numpy.squeeze`) by overloading `_apply_function` and registering
-    individual function implementations via `implementation`.
-
-    It is important to note that the use cases of this class extend beyond
-    array-like objects. Both single- and multi-valued objects can benefit from
-    implementing support for `numpy` universal and public functions. For
-    example, it is possible to apply `numpy.sqrt` to both a real number and an
-    array
-
-    >>> numpy.sqrt(4)
-    2.0
-    >>> numpy.sqrt([4, 9])
-    array([2., 3.])
-
-    Even the trivial application of `numpy.mean` to a real number is defined:
-
-    >>> numpy.mean(2.5)
-    2.5
-
-    Notes
-    -----
-    - This class does not inherit from `numpy.lib.mixins.NDArrayOperatorsMixin`,
-      which implements most of the built-in Python numeric operators via
-      `__array_ufunc__`, because it assumes that subclasses independently
-      implement those methods.
-    """
-
-    def __init_subclass__(cls):
-        cls._UFUNC_TYPES |= {cls}
-        cls._FUNCTION_TYPES |= {cls}
-        cls._FUNCTIONS = {}
-
-    _UFUNC_TYPES = {
-        numpy.ndarray,
-        numbers.Number,
-        list,
-        abstract.Quantity,
-    }
-
-    def __array_ufunc__(self, ufunc, method, *args, **kwargs):
-        """Provide support for `numpy` universal functions.
-
-        See https://numpy.org/doc/stable/reference/arrays.classes.html for more
-        information on use of this special method.
-
-        Notes
-        -----
-        - This method first ensures that the input types (as well as the type of
-          `out`, if passed via keyword) are supported types. It then checks for
-          a custom implementation of `ufunc`. If there is a custom
-          implementation, this method applies it and returns the result. If
-          there is no custom implementation, this method passes control to
-          `_apply_ufunc`, to allow subclass customization.
-        - See `implementation` for additional guidance on custom
-          implementations.
-
-        See Also
-        --------
-        `implementation`
-            Class method for registering custom ufunc implementations.
-
-        `_apply_ufunc`
-            Instance method that allows custom handling of ufuncs corresponding
-            to standard Python numerical operators.
-        """
-        out = kwargs.get('out', ())
-        accepted = tuple(self._UFUNC_TYPES)
-        if not all(isinstance(x, accepted) for x in args + out):
-            return NotImplemented
-        if out:
-            kwargs['out'] = tuple(
-                x._data if isinstance(x, abstract.Quantity)
-                else x for x in out
-            )
-        if self._implements(ufunc):
-            operator = self._FUNCTIONS[ufunc]
-            return operator(*args, **kwargs)
-        return self._apply_ufunc(ufunc, method, *args, **kwargs)
-
-    def _apply_ufunc(self, ufunc, method, *args, **kwargs):
-        """Apply a `numpy` universal function (a.k.a "ufunc") to data.
-
-        Notes
-        -----
-        - Subclasses that wish to customize support for ufuncs should overload
-          this method instead of `__array_ufunc__`.
-        - Subclasses should prefer to define custom implementations of specific
-          universal functions and register each via `implementation`, rather
-          than implementing function-specific logic in this method, since
-          `__array_ufunc__` will check for a custom implementation of a given
-          function before calling this method.
-        - The default implementation of this method applies the given ufunc to
-          real-valued data and directly returns the `numpy` result, without
-          attempting to create a new instance of the custom subclass.
-
-        See Also
-        --------
-        `implementation`
-            Class method for registering custom ufunc implementations.
-
-        `__array_ufunc__`
-            The entry point for `numpy` universal functions.
-        """
-        operator = getattr(ufunc, method)
-        values = self._get_numpy_args(args)
-        try:
-            data = operator(*values, **kwargs)
-        except TypeError as err:
-            raise TypeError(
-                f"Unable to apply {ufunc} to {args}"
-            ) from err
-        if method != 'at':
-            return data
-
-    _FUNCTION_TYPES = {
-        numpy.ndarray,
-        abstract.Object,
-     } | set(numpy.ScalarType)
-
-    def __array_function__(self, func, types, args, kwargs):
-        """Provide support for functions in the `numpy` public API.
-
-        See https://numpy.org/doc/stable/reference/arrays.classes.html for more
-        information of use of this special method. The implementation shown here
-        is a combination of the example on that page and code from the
-        definition of `EncapsulateNDArray.__array_function__` in
-        https://github.com/dask/dask/blob/main/dask/array/tests/test_dispatch.py
-
-        Notes
-        -----
-        - This method first checks that all `types` are in
-          `self._FUNCTION_TYPES`, thereby allowing subclasses that don't
-          override `__array_function__` to handle objects of this type. It then
-          checks for a custom implementation of `func`. If there is a custom
-          implementation, this method applies it and returns the result. If
-          there is no custom implementation, this method passes control to
-          `_apply_function`, to allow subclass customization.
-        - See `implementation` for additional guidance on custom
-          implementations.
-
-        See Also
-        --------
-        `implementation`
-            Class method for registering custom function implementations.
-
-        `_apply_function`
-            Instance method that allows custom handling of `numpy` public
-            functions when there is no registered custom implementation.
-        """
-        accepted = tuple(self._FUNCTION_TYPES)
-        if not all(issubclass(ti, accepted) for ti in types):
-            return NotImplemented
-        if self._implements(func):
-            return self._FUNCTIONS[func](*args, **kwargs)
-        return self._apply_function(func, types, args, kwargs)
-
-    def _apply_function(self, func, types, args, kwargs):
-        """Apply a function in the `numpy` public API.
-
-        Notes
-        -----
-        - Subclasses that wish to customize support for public functions should
-          overload this method instead of `__array_function__`.
-        - Subclasses should prefer to define custom implementations of specific
-          public functions and register each via `implementation`, rather than
-          implementing function-specific logic in this method, since
-          `__array_function__` will check for a custom implementation of a given
-          function before calling this method.
-        - The default implementation calls `_get_numpy_array` for access to
-          real-valued data via an instance of `numpy.ndarray`, `_get_numpy_args`
-          to convert `args` to appropriate operands, and `_get_numpy_types` to
-          extract appropriate operand types. Subclasses may choose to overload
-          any of those individual methods instead of overloading this method.
-
-        See Also
-        --------
-        `implementation`
-            Class method for registering custom ufunc implementations.
-
-        `__array_function__`
-            The entry point for `numpy` public functions.
-        """
-        array = self._get_numpy_array()
-        if array is None:
-            return NotImplemented
-        if not isinstance(array, numpy.ndarray):
-            raise TypeError(
-                f"{self.__class__.__qualname__}._get_numpy_array"
-                " did not return a numpy.ndarray"
-            ) from None
-        args = self._get_numpy_args(args)
-        types = self._get_numpy_types(types)
-        return array.__array_function__(func, types, args, kwargs)
-
-    def _get_numpy_array(self) -> numpy.typing.NDArray | None:
-        """Convert the data interface to an array for `numpy` mixin methods.
-        
-        Notes
-        -----
-        - This method allows subclass implementations to control how they
-          convert their data interface to a `numpy.ndarray` for use with `numpy`
-          public functions.
-        - Returning `None` from this method will cause `_apply_function` to
-          return `NotImplemented`.
-        - The default implementation unconditionally returns `None`.
-        """
-        return
-
-    def _get_numpy_args(self, args):
-        """Convert `args` to operands of a `numpy` function.
-
-        This method will call `~_get_arg_data` on each member of `args` in order
-        to build a `tuple` of suitable operands. Subclasses may overload
-        `~_get_arg_data` to customize access to their data attribute.
-        """
-        return tuple(self._get_arg_data(arg) for arg in args)
-
-    def _get_arg_data(self, arg):
-        """Convert `arg` to an operand of a `numpy` function.
-
-        See Also
-        --------
-        `~_get_numpy_args`
-            The method that calls this method in a loop.
-
-        Notes
-        -----
-        - This method allows a subclass to customize how `numpy` functions
-          access its data attribute.
-        - The default implementation will return the `data` attribute of a of
-          `arg` if `arg` is an instance of the base object class; otherwise, it
-          will return the unmodified argument.
-        """
-        if isinstance(arg, abstract.Quantity):
-            return arg._data
-        return arg
-
-    def _get_numpy_types(self, types):
-        """Extract appropriate types for a `numpy` function.
-        
-        Notes
-        -----
-        - This method allows subclasses to restrict the object types that they
-          pass to `numpy` public functions via `_apply_function`.
-        - The default implementation returns a tuple that contains all types
-          except for subtypes of `~_types.Quantity`.
-        """
-        return tuple(
-            ti for ti in types
-            if not issubclass(ti, abstract.Object)
-        )
-
-    @classmethod
-    def _implements(cls, operation: collections.abc.Callable):
-        """True if this class defines a custom implementation for `operation`.
-        
-        This is a helper methods that gracefully handles the case in which a
-        subclass does not support custom operator implementations.
-        """
-        try:
-            result = operation in cls._FUNCTIONS
-        except TypeError:
-            return False
-        return result
-
-    _FUNCTIONS: dict[str, collections.abc.Callable]=None
-    """Internal collection of custom `numpy` function implementations."""
-
-    @classmethod
-    def implementation(cls, numpy_function: collections.abc.Callable, /):
-        """Register a custom implementation of this `numpy` function.
-
-        Parameters
-        ----------
-        numpy_function : callable
-            The `numpy` universal or public function to implement.
-
-        Notes
-        -----
-        - Users may register `numpy` universal functions (a.k.a. ufuncs;
-          https://numpy.org/doc/stable/reference/ufuncs.html) as well as
-          functions in the public `numpy` API (e.g., `numpy.mean`). This may be
-          important if, for example, a class needs to implement a custom version
-          of `numpy.sqrt`, which is a ufunc.
-        - See https://numpy.org/doc/stable/reference/arrays.classes.html for the
-          suggestion on which this method is based.
-
-        Examples
-        --------
-        Overload `numpy.mean` for an existing class called `Array` with a
-        version that accepts no keyword arguments:
-
-        ```
-            @Array.implementation(numpy.mean)
-            def mean(a: Array, **kwargs) -> Array:
-                if kwargs:
-                    msg = "Cannot pass keywords to numpy.mean with Array" raise
-                    TypeError(msg)
-                return numpy.sum(a) / len(a)
-        ```
-
-        This will compute the mean of the underlying data when called with no
-        arguments, but will raise an exception when called with arguments:
-
-            >>> v = Array([[1, 2], [3, 4]])
-            >>> numpy.mean(v)
-            5.0
-            >>> numpy.mean(v, axis=0)
-            ...
-            TypeError: Cannot pass keywords to numpy.mean with Array
-
-        See Also
-        --------
-        `~implements`
-        """
-        if not callable(numpy_function):
-            raise TypeError(
-                "The target operation of a custom numpy implementation"
-                " must be callable"
-            ) from None
-        def decorator(user_function: UserFunction):
-            if cls._FUNCTIONS is None:
-                raise NotImplementedError(
-                    f"Type {cls} does not support custom implementations"
-                    " of numpy functions"
-                ) from None
-            cls._FUNCTIONS[numpy_function] = user_function
-            return user_function
-        return decorator
-
-    @classmethod
-    def implement(
-        cls,
-        numpy_function: collections.abc.Callable,
-        user_function: UserFunction,
-        /,
-    ) -> None:
-        """Implement a `numpy` function via a given user function.
-
-        This method serves as an alternative to the class method
-        `implementation`, which is primarily meant to be used as a decorator.
-        This method allows the user to directly associate a custom
-        implementation with the target `numpy` function.
-
-        Parameters
-        ----------
-        numpy_function : callable
-            The `numpy` universal or public function to implement.
-
-        user_function: callable
-            The custom implementation to associate with `numpy_function`.
-
-        Examples
-        --------
-        Here is an alternative to the `~implementation` example usage:
-
-        ```
-            def mean(a: Array, **kwargs) -> Array:
-                if kwargs:
-                    msg = "Cannot pass keywords to numpy.mean with Array" raise
-                    TypeError(msg)
-                return numpy.sum(a) / len(a)
-
-            Array.implement(numpy.mean, mean)
-        ```
-
-        However, a more useful application may be to associate multiple `numpy`
-        functions with a single custom implementation:
-
-        ```
-            def trig(f: numpy.ufunc):
-                def method(a: Array):
-                    ... # custom implementation
-                return method
-
-            for f in {numpy.sin, numpy.cos, numpy.tan}:
-                Array.implement(f, trig(f))
-        ```
-
-        See Also
-        --------
-        `~implementation`
-        """
-        if not callable(numpy_function):
-            raise TypeError(
-                "The target operation of a custom numpy implementation"
-                " must be callable"
-            ) from None
-        if cls._FUNCTIONS is None:
-            raise NotImplementedError(
-                f"Type {cls} does not support custom implementations"
-                " of numpy functions"
-            ) from None
-        cls._FUNCTIONS[numpy_function] = user_function
-