oprattr 0.1.0__tar.gz

oprattr-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Project-specific files
+ignored
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

oprattr-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

oprattr-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1 @@
+# oprattr: Self-Consistent Operations on Object Attributes

oprattr-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "oprattr"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Matthew Young", email = "myoung.space.science@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=2.2.1",
+    "scipy>=1.15.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "ipython>=8.31.0",
+    "pytest>=8.3.4",
+]

oprattr-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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})"
+