oprattr 0.6.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,5 +1,12 @@
 ## NEXT
 
+## v0.7.0
+
+- Add `oprattr.Object` and `oprattr.Quantity` to the public namespace
+- Rename modules that should not be part of the public namespace
+- Define the `OperationError` exception class
+- Change default behavior when a metadata attribute does not implement an operation
+
 ## v0.6.0
 
 - Add `methods` module

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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "oprattr"
-version = "0.6.0"
+version = "0.7.0"
 description = "Add your description here"
 readme = "README.md"
 authors = [

{oprattr-0.6.0 → oprattr-0.7.0}/src/oprattr/__init__.py

@@ -3,17 +3,27 @@ import functools
 
 import numpy
 
-from . import abstract
+from ._abstract import (
+    Quantity,
+    Object,
+)
 from . import methods
 from . import mixins
-from . import typeface
-from ._operations import equality
-
+from . import _typeface
+from ._operations import (
+    unary,
+    equality,
+    ordering,
+    additive,
+    multiplicative,
+    MetadataTypeError,
+    MetadataValueError,
+)
 
-T = typeface.TypeVar('T')
 
+T = _typeface.TypeVar('T')
 
-class Operand(abstract.Object[T], mixins.Numpy):
+class Operand(Object[T], mixins.Numpy):
     """A concrete implementation of a real-valued object."""
 
     __abs__ = methods.__abs__
@@ -66,22 +76,22 @@ def array_equal(
     return numpy.array_equal(numpy.array(x), numpy.array(y), **kwargs)
 
 
+class OperationError(NotImplementedError):
+    """A metadata attribute does not support this operation.
+    
+    The default behavior when applying an operator to a metadata attribute of
+    `~Operand` is to copy the current value if the attribute does not define the
+    operation. Custom metadata attributes may raise this exception to indicate
+    that attempting to apply the operator is truly an error.
+    """
+
+
 @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
+    f = numpy.gradient
+    data = f(x._data, *args, **kwargs)
+    meta = _apply_to_metadata(f, x, **kwargs)
     if isinstance(data, (list, tuple)):
         r = [type(x)(array, **meta) for array in data]
         if isinstance(data, tuple):
@@ -96,22 +106,34 @@ def wrapnumpy(f: collections.abc.Callable):
     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
+        meta = _apply_to_metadata(f, x, **kwargs)
         return type(x)(data, **meta)
     return method
 
 
+def _apply_to_metadata(
+    f: collections.abc.Callable,
+    x: Operand,
+    **kwargs,
+) -> dict[str, _typeface.Any]:
+    """Apply `f` to metadata attributes."""
+    processed = {}
+    for key, value in x._meta.items():
+        try:
+            v = f(value, **kwargs)
+        except TypeError:
+            processed[key] = value
+        except OperationError as exc:
+            raise TypeError(
+                f"Cannot compute numpy.{f.__qualname__}(x)"
+                f" because metadata attribute {key!r} of {type(x)}"
+                " does not support this operation"
+            ) from exc
+        else:
+            processed[key] = v
+    return processed.copy()
+
+
 _OPERAND_UFUNCS = (
     numpy.sqrt,
     numpy.sin,
@@ -133,7 +155,25 @@ _OPERAND_FUNCTIONS = (
 )
 
 
-for f in _OPERAND_UFUNCS + _OPERAND_FUNCTIONS:
-    Operand.implement(f, wrapnumpy(f))
-
-
+for _func in _OPERAND_UFUNCS + _OPERAND_FUNCTIONS:
+    Operand.implement(_func, wrapnumpy(_func))
+
+
+__all__ = [
+    # Modules
+    methods,
+    mixins,
+    # Object classes
+    Quantity,
+    Object,
+    # Functions
+    unary,
+    equality,
+    ordering,
+    additive,
+    multiplicative,
+    # Error classes
+    MetadataTypeError,
+    MetadataValueError,
+    OperationError,
+]

{oprattr-0.6.0 → oprattr-0.7.0}/src/oprattr/__init__.pyi

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

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

@@ -4,10 +4,10 @@ import numbers
 import numerical
 import numpy.typing
 
-from . import typeface
+from . import _typeface
 
 
-DataType = typeface.TypeVar(
+DataType = _typeface.TypeVar(
     'DataType',
     int,
     float,
@@ -18,14 +18,14 @@ DataType = typeface.TypeVar(
 )
 
 
-@typeface.runtime_checkable
-class Quantity(numerical.Quantity[DataType], typeface.Protocol):
+@_typeface.runtime_checkable
+class Quantity(numerical.Quantity[DataType], _typeface.Protocol):
     """Protocol for numerical objects with metadata."""
 
-    _meta: collections.abc.Mapping[str, typeface.Any]
+    _meta: collections.abc.Mapping[str, _typeface.Any]
 
 
-class Object(numerical.Real, typeface.Generic[DataType]):
+class Object(numerical.Real, _typeface.Generic[DataType]):
     """A real-valued object with metadata attributes."""
 
     def __init__(

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

@@ -1,6 +1,6 @@
 from numerical import operators
 
-from .abstract import (
+from ._abstract import (
     Quantity,
     Object,
 )

{oprattr-0.6.0 → oprattr-0.7.0}/src/oprattr/mixins.py

@@ -3,12 +3,11 @@ import numbers
 
 import numpy
 
-from . import abstract
-from . import typeface
+from . import _abstract
+from . import _typeface
 
 
-T = typeface.TypeVar('T')
-
+T = _typeface.TypeVar('T')
 
 class Real:
     """Mixin for adding basic real-valued operator support."""
@@ -85,7 +84,6 @@ class Real:
 
 UserFunction = collections.abc.Callable[..., T]
 
-
 class Numpy:
     """Mixin for adding support for `numpy` functions to numeric objects.
     
@@ -128,7 +126,7 @@ class Numpy:
         numpy.ndarray,
         numbers.Number,
         list,
-        abstract.Quantity,
+        _abstract.Quantity,
     }
 
     def __array_ufunc__(self, ufunc, method, *args, **kwargs):
@@ -163,7 +161,7 @@ class Numpy:
             return NotImplemented
         if out:
             kwargs['out'] = tuple(
-                x._data if isinstance(x, abstract.Quantity)
+                x._data if isinstance(x, _abstract.Quantity)
                 else x for x in out
             )
         if self._implements(ufunc):
@@ -208,7 +206,7 @@ class Numpy:
 
     _FUNCTION_TYPES = {
         numpy.ndarray,
-        abstract.Object,
+        _abstract.Object,
      } | set(numpy.ScalarType)
 
     def __array_function__(self, func, types, args, kwargs):
@@ -325,7 +323,7 @@ class Numpy:
           `arg` if `arg` is an instance of the base object class; otherwise, it
           will return the unmodified argument.
         """
-        if isinstance(arg, abstract.Quantity):
+        if isinstance(arg, _abstract.Quantity):
             return arg._data
         return arg
 
@@ -341,7 +339,7 @@ class Numpy:
         """
         return tuple(
             ti for ti in types
-            if not issubclass(ti, abstract.Object)
+            if not issubclass(ti, _abstract.Object)
         )
 
     @classmethod

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

@@ -157,11 +157,6 @@ def symbol_gradient(x: Symbol, **kwargs):
     return f"numpy.gradient({x})"
 
 
-@Symbol.implementation(numpy.trapezoid)
-def symbol_trapezoid(x: Symbol, **kwargs):
-    return f"numpy.trapezoid({x})"
-
-
 def symbolic_binary(a, op, b):
     if isinstance(a, (Symbol, str)) and isinstance(b, (Symbol, str)):
         return f"{a} {op} {b}"
@@ -502,26 +497,29 @@ def test_gradient():
     grad = numpy.gradient(v)
     for t, g in zip(that, grad):
         assert isinstance(t, oprattr.Operand)
-        assert numpy.array_equal(t, x(g, name=nR))
+        assert numpy.array_equal(t, g)
+        assert t._meta['name'] == nR
     for axis in range(v.ndim):
         that = numpy.gradient(this, axis=axis)
         assert isinstance(that, oprattr.Operand)
         grad = numpy.gradient(v, axis=axis)
-        assert numpy.array_equal(that, x(grad, name=nR))
+        assert numpy.array_equal(that, grad)
+        assert t._meta['name'] == nR
 
 
 def test_trapezoid():
-    """Test `numpy.trapezoid`."""
+    """Test `numpy.trapezoid`, which `Symbol` does not implement."""
     nA = Symbol('A')
-    nR = Symbol('numpy.trapezoid(A)')
     v = numpy.arange(3*4*5).reshape(3, 4, 5)
     this = x(v, name=nA)
     that = numpy.trapezoid(this)
     assert isinstance(that, oprattr.Operand)
-    assert numpy.array_equal(that, x(numpy.trapezoid(v), name=nR))
+    assert numpy.array_equal(that, numpy.trapezoid(v))
+    assert that._meta['name'] == nA
     for axis in range(v.ndim):
         that = numpy.trapezoid(this, axis=axis)
         assert isinstance(that, oprattr.Operand)
         trap = numpy.trapezoid(v, axis=axis)
-        assert numpy.array_equal(that, x(trap, name=nR))
+        assert numpy.array_equal(that, trap)
+        assert that._meta['name'] == nA