oprattr 0.5.0__py3-none-any.whl

oprattr/__init__.py

@@ -0,0 +1,214 @@
+import collections.abc
+import functools
+import numbers
+
+from numerical import operators
+import numpy
+
+from . import abstract
+from . import mixins
+from . import typeface
+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):
+        """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 NotImplemented
+
+    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/_operations.py

@@ -0,0 +1,191 @@
+from numerical import operators
+
+from .abstract import (
+    Quantity,
+    Object,
+)
+
+
+class MetadataError(TypeError):
+    """A metadata-related TypeError occurred."""
+
+    def __init__(
+        self,
+        f: operators.Operator,
+        *args,
+        error: str | None = None,
+        key: str | None = 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: str | None = None,
+    key: str | None = 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, Quantity):
+        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)."""
+    x = a._data if isinstance(a, Quantity) else a
+    y = b._data if isinstance(b, Quantity) else b
+    fxy = f(x, y)
+    try:
+        iter(fxy)
+    except TypeError:
+        r = bool(fxy)
+    else:
+        r = all(fxy)
+    isne = f(1, 2)
+    if isinstance(a, Quantity) and isinstance(b, Quantity):
+        if a._meta != b._meta:
+            return isne
+        return r
+    if isinstance(a, Quantity):
+        if not a._meta:
+            return r
+        return isne
+    if isinstance(b, Quantity):
+        if not b._meta:
+            return r
+        return isne
+    return r
+
+
+def ordering(f: operators.Operator, a, b):
+    """Compute the ordering operation f(a, b)."""
+    if isinstance(a, Quantity) and isinstance(b, Quantity):
+        if a._meta == b._meta:
+            return f(a._data, b._data)
+        raise MetadataError(f, a, b, error='unequal') from None
+    if isinstance(a, Quantity):
+        if not a._meta:
+            return f(a._data, b)
+        raise MetadataError(f, a, b, error='non-empty') from None
+    if isinstance(b, Quantity):
+        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, Quantity) and isinstance(b, Quantity):
+        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, Quantity):
+        if not a._meta:
+            return type(a)(f(a._data, b))
+        raise MetadataError(f, a, b, error='non-empty') from None
+    if isinstance(b, Quantity):
+        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, Quantity) and isinstance(b, Quantity):
+        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, Quantity):
+        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, Quantity):
+        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/abstract.py

@@ -0,0 +1,60 @@
+import collections.abc
+import numbers
+
+import numerical
+import numpy.typing
+
+from . import typeface
+
+
+DataType = typeface.TypeVar(
+    'DataType',
+    int,
+    float,
+    numbers.Number,
+    numpy.number,
+    numpy.typing.ArrayLike,
+    numpy.typing.NDArray,
+)
+
+
+@typeface.runtime_checkable
+class Quantity(numerical.Quantity[DataType], typeface.Protocol):
+    """Protocol for numerical objects with metadata."""
+
+    _meta: collections.abc.Mapping[str, typeface.Any]
+
+
+class Object(numerical.Real, typeface.Generic[DataType]):
+    """A real-valued object with metadata attributes."""
+
+    def __init__(
+        self,
+        __data: DataType,
+        **metadata,
+    ) -> None:
+        if not isinstance(__data, numerical.Real):
+            raise TypeError("Data input to Object must be real-valued")
+        self._data = __data
+        self._meta = metadata
+
+    def __str__(self):
+        """Called for str(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 = ", ".join(f"{k}={str(v)!r}" for k, v in self._meta.items())
+        return f"{datastr}, {metastr}"
+
+    def __repr__(self):
+        """Called for repr(self)."""
+        return f"{self.__class__.__qualname__}({self})"
+

oprattr/mixins.py

@@ -0,0 +1,489 @@
+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
+

oprattr/typeface.py

@@ -0,0 +1,42 @@
+"""
+Support for type annotations.
+
+This module provides a single interface to type annotations, including those
+that are not defined by the operative Python version and those that this package
+prefers to use from future versions.
+
+Examples
+--------
+* Suppose `BestType` is available in the `typing` module starting with Python
+  version 3.X and is available in the `typing_extensions` module for earlier
+  versions. If the user is running with Python version <3.X, this module will
+  import `BestType` from `typing_extensions`. Otherwise, it will import
+  `BestType` from `typing`.
+* Support `UpdatedType` is available in the `typing` module for the user's
+  version of Python, but this package wishes to take advantage of updates since
+  that version. This module will automatically import the version from
+  `typing_extensions`.
+"""
+
+import typing
+import typing_extensions
+
+
+__all__ = ()
+
+EXTENDED = [
+    'Protocol',
+]
+
+def __getattr__(name: str) -> type:
+    """Get a built-in type annotation."""
+    if name in EXTENDED:
+        return getattr(typing_extensions, name)
+    try:
+        attr = getattr(typing, name)
+    except AttributeError:
+        attr = getattr(typing_extensions, name)
+    return attr
+
+
+

oprattr/typeface.pyi

@@ -0,0 +1,5 @@
+"""
+Type help for our custom type-annotation interface.
+"""
+from typing_extensions import *
+from typing import *

oprattr-0.5.0.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: oprattr
+Version: 0.5.0
+Summary: Add your description here
+Author-email: Matthew Young <myoung.space.science@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: numerical
+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.5.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+oprattr/__init__.py,sha256=NPLnNea_NmyxQUX7DLqaC7YB67XATQ2gEhkPmBGpRpo,6044
+oprattr/_operations.py,sha256=woQtV5R7ToZ5KY3OMJK7MQYHWPGFxQ3f8jTcqkmFdQI,6002
+oprattr/abstract.py,sha256=RPGJ-jOz5bJoLvdbmP5eCP_NyGRj6yj5Iia5oJ0-gnE,1491
+oprattr/mixins.py,sha256=_qqhReZu9Ta83irVihUrhggcObEj4lyp-3_S9K2hEog,16875
+oprattr/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oprattr/typeface.py,sha256=FPGAdTZUmS_jd56PcZ5tCcUE_rXNubINBpVMQLRenvg,1214
+oprattr/typeface.pyi,sha256=6gVdlDXtwl6Qyv07JWuRhM78VTGzds0pJ2KZUAAGcXs,113
+oprattr-0.5.0.dist-info/METADATA,sha256=UjAmWY4kYQduP37H4KKENdWBMMLWBsz2KXxnIDsiOi0,375
+oprattr-0.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+oprattr-0.5.0.dist-info/licenses/LICENSE,sha256=m2oXG0JDq5RzaKTS57TvGyNq5cWcV4_nfmLZjzLdYTg,1513
+oprattr-0.5.0.dist-info/RECORD,,

oprattr-0.5.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

oprattr-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,32 @@
+
+
+BSD 3-Clause License
+
+Copyright (c) 2025, Matt Young
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+