oprattr 0.1.0__py3-none-any.whl

oprattr/__init__.py

@@ -0,0 +1,204 @@
+import functools
+import numbers
+import typing
+
+import numpy
+
+from . import mixins
+from . import operators
+from . import _types
+from ._operations import (
+    unary,
+    equality,
+    ordering,
+    additive,
+    multiplicative,
+)
+
+
+T = typing.TypeVar('T')
+
+
+class Operand(_types.Object[T], mixins.Numpy):
+    """A concrete implementation of a real-valued object."""
+
+    def __abs__(self):
+        """Called for abs(self)."""
+        return unary(operators.abs, self)
+
+    def __pos__(self):
+        """Called for +self."""
+        return unary(operators.pos, self)
+
+    def __neg__(self):
+        """Called for -self."""
+        return unary(operators.neg, self)
+
+    def __eq__(self, other):
+        """Called for self == other."""
+        return equality(operators.eq, self, other)
+
+    def __ne__(self, other):
+        """Called for self != other."""
+        return equality(operators.ne, self, other)
+
+    def __lt__(self, other):
+        """Called for self < other."""
+        return ordering(operators.lt, self, other)
+
+    def __le__(self, other):
+        """Called for self <= other."""
+        return ordering(operators.le, self, other)
+
+    def __gt__(self, other):
+        """Called for self > other."""
+        return ordering(operators.gt, self, other)
+
+    def __ge__(self, other):
+        """Called for self >= other."""
+        return ordering(operators.ge, self, other)
+
+    def __add__(self, other):
+        """Called for self + other."""
+        return additive(operators.add, self, other)
+
+    def __radd__(self, other):
+        """Called for other + self."""
+        return additive(operators.add, other, self)
+
+    def __sub__(self, other):
+        """Called for self - other."""
+        return additive(operators.sub, self, other)
+
+    def __rsub__(self, other):
+        """Called for other - self."""
+        return additive(operators.sub, other, self)
+
+    def __mul__(self, other):
+        """Called for self * other."""
+        return multiplicative(operators.mul, self, other)
+
+    def __rmul__(self, other):
+        """Called for other * self."""
+        return multiplicative(operators.mul, other, self)
+
+    def __truediv__(self, other):
+        """Called for self / other."""
+        return multiplicative(operators.truediv, self, other)
+
+    def __rtruediv__(self, other):
+        """Called for other / self."""
+        return multiplicative(operators.truediv, other, self)
+
+    def __floordiv__(self, other):
+        """Called for self // other."""
+        return multiplicative(operators.floordiv, self, other)
+
+    def __rfloordiv__(self, other):
+        """Called for other // self."""
+        return multiplicative(operators.floordiv, other, self)
+
+    def __mod__(self, other):
+        """Called for self % other."""
+        return multiplicative(operators.mod, self, other)
+
+    def __rmod__(self, other):
+        """Called for other % self."""
+        return multiplicative(operators.mod, other, self)
+
+    def __pow__(self, other):
+        """Called for self ** other."""
+        if isinstance(other, numbers.Real):
+            return multiplicative(operators.pow, self, other)
+        return NotImplemented
+
+    def __rpow__(self, other):
+        """Called for other ** self."""
+        return super().__rpow__(other)
+
+    def __array__(self, *args, **kwargs):
+        """Called for numpy.array(self)."""
+        return numpy.array(self._data, *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: typing.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/_operations.py

@@ -0,0 +1,179 @@
+import typing
+
+from . import operators
+from ._types import Object
+
+
+class MetadataError(TypeError):
+    """A metadata-related TypeError occurred."""
+
+    def __init__(
+        self,
+        f: operators.Operator,
+        *args,
+        error: typing.Optional[str]=None,
+        key: typing.Optional[str]=None,
+    ) -> None:
+        super().__init__(*args)
+        self._f = f
+        self._error = error
+        self._key = key
+
+    def __str__(self):
+        """Called when handling the exception."""
+        types = [type(arg) for arg in self.args]
+        return _build_error_message(
+            self._f,
+            *types,
+            error=self._error,
+            key=self._key,
+        )
+
+
+def _build_error_message(
+    f: operators.Operator,
+    *types: type,
+    error: typing.Optional[str]=None,
+    key: typing.Optional[str]=None,
+) -> str:
+    """Helper for `_raise_metadata_exception`.
+    
+    This function should avoid raising an exception if at all possible, and
+    instead return the default error message, since it is already being called
+    as the result of an error elsewhere.
+    """
+    errmsg = f"Cannot compute {f}"
+    errstr = error.lower() if isinstance(error, str) else ''
+    if errstr == 'unequal':
+        return f"{errmsg} between objects with unequal metadata"
+    if errstr in {'non-empty', 'nonempty'}:
+        if len(types) == 2:
+            a, b = types
+            endstr = "because {} has metadata"
+            if issubclass(a, Object):
+                return f"{errmsg} between {a} and {b} {endstr.format(str(a))}"
+            if issubclass(b, Object):
+                return f"{errmsg} between {a} and {b} {endstr.format(str(b))}"
+    if errstr == 'type':
+        if key is None:
+            keystr = "a metadata attribute"
+        else:
+            keystr = f"metadata attribute {key!r}"
+        midstr = f"because {keystr}"
+        endstr = "does not support this operation"
+        if len(types) == 1:
+            return f"{errmsg} of {types[0]} {midstr} {endstr}"
+        if len(types) == 2:
+            a, b = types
+            return f"{errmsg} between {a} and {b} {midstr} {endstr}"
+    return errmsg
+
+
+def unary(f: operators.Operator, a):
+    """Compute the unary operation f(a)."""
+    if isinstance(a, Object):
+        meta = {}
+        for key, value in a._meta.items():
+            try:
+                v = f(value)
+            except TypeError as exc:
+                raise MetadataError(f, a, error='type', key=key) from exc
+            else:
+                meta[key] = v
+        return type(a)(f(a._data), **meta)
+    return f(a)
+
+
+def equality(f: operators.Operator, a, b):
+    """Compute the equality operation f(a, b)."""
+    if isinstance(a, Object) and isinstance(b, Object):
+        if a._meta != b._meta:
+            return f is operators.ne
+        return f(a._data, b._data)
+    if isinstance(a, Object):
+        if not a._meta:
+            return f(a._data, b)
+        return f is operators.ne
+    if isinstance(b, Object):
+        if not b._meta:
+            return f(a, b._data)
+        return f is operators.ne
+    return f(a, b)
+
+
+def ordering(f: operators.Operator, a, b):
+    """Compute the ordering operation f(a, b)."""
+    if isinstance(a, Object) and isinstance(b, Object):
+        if a._meta == b._meta:
+            return f(a._data, b._data)
+        raise MetadataError(f, a, b, error='unequal') from None
+    if isinstance(a, Object):
+        if not a._meta:
+            return f(a._data, b)
+        raise MetadataError(f, a, b, error='non-empty') from None
+    if isinstance(b, Object):
+        if not b._meta:
+            return f(a, b._data)
+        raise MetadataError(f, a, b, error='non-empty') from None
+    return f(a, b)
+
+
+def additive(f: operators.Operator, a, b):
+    """Compute the additive operation f(a, b)."""
+    if isinstance(a, Object) and isinstance(b, Object):
+        if a._meta == b._meta:
+            return type(a)(f(a._data, b._data), **a._meta)
+        raise MetadataError(f, a, b, error='unequal') from None
+    if isinstance(a, Object):
+        if not a._meta:
+            return type(a)(f(a._data, b))
+        raise MetadataError(f, a, b, error='non-empty') from None
+    if isinstance(b, Object):
+        if not b._meta:
+            return type(b)(f(a, b._data))
+        raise MetadataError(f, a, b, error='non-empty') from None
+    return f(a, b)
+
+
+def multiplicative(f: operators.Operator, a, b):
+    """Compute the multiplicative operation f(a, b)."""
+    if isinstance(a, Object) and isinstance(b, Object):
+        keys = set(a._meta) & set(b._meta)
+        meta = {}
+        for key in keys:
+            try:
+                v = f(a._meta[key], b._meta[key])
+            except TypeError as exc:
+                raise MetadataError(f, a, b, error='type', key=key) from exc
+            else:
+                meta[key] = v
+        for key, value in a._meta.items():
+            if key not in keys:
+                meta[key] = value
+        for key, value in b._meta.items():
+            if key not in keys:
+                meta[key] = value
+        return type(a)(f(a._data, b._data), **meta)
+    if isinstance(a, Object):
+        meta = {}
+        for key, value in a._meta.items():
+            try:
+                v = f(value, b)
+            except TypeError as exc:
+                raise MetadataError(f, a, b, error='type', key=key) from exc
+            else:
+                meta[key] = v
+        return type(a)(f(a._data, b), **meta)
+    if isinstance(b, Object):
+        meta = {}
+        for key, value in b._meta.items():
+            try:
+                v = f(a, value)
+            except TypeError as exc:
+                raise MetadataError(f, a, b, error='type', key=key) from exc
+            else:
+                meta[key] = v
+        return type(b)(f(a, b._data), **meta)
+    return f(a, b)
+
+

oprattr/_types.py

@@ -0,0 +1,144 @@
+import abc
+import numbers
+import typing
+
+import numpy.typing
+
+
+@typing.runtime_checkable
+class Real(typing.Protocol):
+    """Abstract protocol for real-valued objects."""
+
+    @abc.abstractmethod
+    def __abs__(self):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __pos__(self):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __neg__(self):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __eq__(self, other):
+        return False
+
+    @abc.abstractmethod
+    def __ne__(self, other):
+        return True
+
+    @abc.abstractmethod
+    def __le__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __lt__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __ge__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __gt__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __add__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __radd__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __sub__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __rsub__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __mul__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __rmul__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __truediv__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __rtruediv__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __floordiv__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __rfloordiv__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __mod__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __rmod__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __pow__(self, other):
+        return NotImplemented
+
+    @abc.abstractmethod
+    def __rpow__(self, other):
+        return NotImplemented
+
+
+DataType = typing.TypeVar(
+    'DataType',
+    int,
+    float,
+    numbers.Number,
+    numpy.number,
+    numpy.typing.ArrayLike,
+    numpy.typing.NDArray,
+)
+
+
+class Object(Real, typing.Generic[DataType]):
+    """A real-valued object with metadata attributes."""
+
+    def __init__(
+        self,
+        __data: DataType,
+        **metadata,
+    ) -> None:
+        if not isinstance(__data, Real):
+            raise TypeError("Data input to Object must be real-valued")
+        self._data = __data
+        self._meta = metadata
+
+    def __repr__(self):
+        """Called for repr(self)."""
+        try:
+            datastr = numpy.array2string(
+                self._data,
+                separator=", ",
+                threshold=6,
+                edgeitems=2,
+                prefix=f"{self.__class__.__qualname__}(",
+                suffix=")"
+            )
+        except Exception:
+            datastr = str(self._data)
+        metastr = "metadata={" + ", ".join(f"{k!r}" for k in self._meta) + "}"
+        return f"{self.__class__.__qualname__}({datastr}, {metastr})"
+

oprattr/mixins.py

@@ -0,0 +1,415 @@
+import numbers
+import typing
+
+import numpy
+
+from . import _types
+
+
+T = typing.TypeVar('T')
+
+
+UserFunction = typing.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,
+        _types.Object,
+    }
+
+    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, _types.Object)
+                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,
+        _types.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) -> typing.Optional[numpy.typing.NDArray]:
+        """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, _types.Object):
+            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, _types.Object)
+        )
+
+    @classmethod
+    def _implements(cls, operation: typing.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: typing.Dict[str, typing.Callable]=None
+    """Internal collection of custom `numpy` function implementations."""
+
+    @classmethod
+    def implementation(cls, numpy_function: typing.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: typing.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
+

oprattr/operators.py

@@ -0,0 +1,41 @@
+"""
+A namespace for operators used by this package's `Object` class.
+"""
+
+import builtins
+import operator
+import typing
+
+
+class Operator:
+    """Base class for enhanced operators."""
+    def __init__(self, __f: typing.Callable, operation: str):
+        self._f = __f
+        self._operation = operation
+
+    def __repr__(self):
+        """Called for repr(self)."""
+        return self._operation
+
+    def __call__(self, *args, **kwds):
+        """Called for self(*args, **kwds)."""
+        return self._f(*args, **kwds)
+
+
+eq = Operator(operator.eq, r'a == b')
+ne = Operator(operator.ne, r'a != b')
+lt = Operator(operator.lt, r'a < b')
+le = Operator(operator.le, r'a <= b')
+gt = Operator(operator.gt, r'a > b')
+ge = Operator(operator.ge, r'a >= b')
+abs = Operator(builtins.abs, r'abs(a)')
+pos = Operator(operator.pos, r'+a')
+neg = Operator(operator.neg, r'-a')
+add = Operator(operator.add, r'a + b')
+sub = Operator(operator.sub, r'a - b')
+mul = Operator(operator.mul, r'a * b')
+truediv = Operator(operator.truediv, r'a / b')
+floordiv = Operator(operator.floordiv, r'a // b')
+mod = Operator(operator.mod, r'a % b')
+pow = Operator(builtins.pow, r'a ** b')
+

oprattr-0.1.0.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: oprattr
+Version: 0.1.0
+Summary: Add your description here
+Author-email: Matthew Young <myoung.space.science@gmail.com>
+Requires-Python: >=3.10
+Requires-Dist: numpy>=2.2.1
+Requires-Dist: scipy>=1.15.0
+Description-Content-Type: text/markdown
+
+# oprattr: Self-Consistent Operations on Object Attributes

oprattr-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+oprattr/__init__.py,sha256=_mEw0H7v3bpKXFPvM_koOVnvsUQLO3HK6zBmnKCOFQU,5553
+oprattr/_operations.py,sha256=e8kTjc183mKR51EX2Ds22kPx0dQc5uqct2btgHzCgoY,5829
+oprattr/_types.py,sha256=TzTt9GkQ5KZc5kqajdLnn8EcvxzMj3SALSI5iJrB6Vk,3182
+oprattr/mixins.py,sha256=G-4aVbQ1wLDz15KSFL9yWqlU5HXQFwp4g7VoFjl7_24,15471
+oprattr/operators.py,sha256=skqQpIezGSDbsmB2h-UNnxG_7aDGT6PsnvUkondpwOg,1154
+oprattr/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oprattr-0.1.0.dist-info/METADATA,sha256=nwgndllGe5R1KX3UGxZjzvVcpdPG7jg9NQJDO8LtQhI,328
+oprattr-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+oprattr-0.1.0.dist-info/RECORD,,

oprattr-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any