oprattr 0.6.0__tar.gz

oprattr-0.6.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.6.0/.python-version

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

oprattr-0.6.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+## NEXT
+
+## v0.6.0
+
+- Add `methods` module
+- Add `__init__.pyi` type file
+- Update metadata error types
+
+## v0.5.0
+
+- Fix `MetadataError` bug
+- Improve string representations of `Operand` instances
+
+## v0.4.0
+
+- Replace local `operators` module with equivalent module from `numerical` package
+- Redefine equality to always return a single boolean value
+
+## v0.3.0
+
+- Incorporate `numerical` package
+- Add `typeface` module
+
+## v0.2.0
+
+- Rename `_types` submodule to `abstract`
+
+## v0.1.0
+
+- Hello world!

oprattr-0.6.0/DEVELOPERS.md

@@ -0,0 +1,16 @@
+# Developer Notes
+
+This document contains notes for those who wish to contribute to `oprattr` by modifying the code base. In order to develop `oprattr`, you should fork the respository, edit your forked copy, and submit a pull request for integration with the original repository.
+
+Note that this is a living document and is subject to change without notice.
+
+## Version Numbers
+
+When incrementing the version number to X.Y.Z, please do the following
+* create a new subsection in `CHANGELOG.md`, below **NEXT**, with the title
+  formatted as vX.Y.Z (YYYY-MM-DD)
+* update the version number in `pyproject.toml`
+* commit with the message "Increment version to X.Y.Z"
+* create a tag named "vX.Y.Z" with the message "version X.Y.Z"
+* push and follow tags
+

oprattr-0.6.0/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.
+

oprattr-0.6.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: oprattr
+Version: 0.6.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.6.0/README.md

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

oprattr-0.6.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "oprattr"
+version = "0.6.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Matthew Young", email = "myoung.space.science@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numerical",
+    "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",
+]
+
+[tool.uv.sources]
+numerical = { git = "https://github.com/myoung-space-science/numerical", rev = "v0.2.0" }

oprattr-0.6.0/src/oprattr/__init__.py

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

@@ -0,0 +1,81 @@
+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/_operations.py

@@ -0,0 +1,182 @@
+from numerical import operators
+
+from .abstract import (
+    Quantity,
+    Object,
+)
+
+
+class MetadataTypeError(TypeError):
+    """A metadata-related TypeError occurred."""
+
+
+class MetadataValueError(ValueError):
+    """A metadata-related ValueError occurred."""
+
+
+def _build_error_message(
+    f: operators.Operator,
+    *args,
+    error: str | None = None,
+    key: str | None = None,
+) -> str:
+    """Helper for metadata error messages.
+
+    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"
+    types = [type(arg) for arg in args]
+    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:
+                errmsg = _build_error_message(f, a, error='type', key=key)
+                raise MetadataTypeError(errmsg) 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)
+        errmsg = _build_error_message(f, a, b, error='unequal')
+        raise MetadataValueError(errmsg) from None
+    errmsg = _build_error_message(f, a, b, error='non-empty')
+    if isinstance(a, Quantity):
+        if not a._meta:
+            return f(a._data, b)
+        raise MetadataTypeError(errmsg) from None
+    if isinstance(b, Quantity):
+        if not b._meta:
+            return f(a, b._data)
+        raise MetadataTypeError(errmsg) 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)
+        errmsg = _build_error_message(f, a, b, error='unequal')
+        raise MetadataValueError(errmsg) from None
+    errmsg = _build_error_message(f, a, b, error='non-empty')
+    if isinstance(a, Quantity):
+        if not a._meta:
+            return type(a)(f(a._data, b))
+        raise MetadataTypeError(errmsg) from None
+    if isinstance(b, Quantity):
+        if not b._meta:
+            return type(b)(f(a, b._data))
+        raise MetadataTypeError(errmsg) 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:
+                errmsg = _build_error_message(f, a, b, error='type', key=key)
+                raise MetadataTypeError(errmsg) 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:
+                errmsg = _build_error_message(f, a, b, error='type', key=key)
+                raise MetadataTypeError(errmsg) 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:
+                errmsg = _build_error_message(f, a, b, error='type', key=key)
+                raise MetadataTypeError(errmsg) from exc
+            else:
+                meta[key] = v
+        return type(b)(f(a, b._data), **meta)
+    return f(a, b)
+
+

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