oprattr 0.1.0__tar.gz → 0.3.0__tar.gz

oprattr-0.3.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+## NEXT
+
+## v0.3.0
+
+- Incorporate `numerical` package
+- Add `typeface` module
+
+## v0.2.0
+
+- Rename `_types` submodule to `abstract`
+
+## v0.1.0
+
+- Hello world!

oprattr-0.3.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.3.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.1.0 → oprattr-0.3.0}/PKG-INFO

@@ -1,9 +1,11 @@
 Metadata-Version: 2.4
 Name: oprattr
-Version: 0.1.0
+Version: 0.3.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-0.1.0 → oprattr-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oprattr"
-version = "0.1.0"
+version = "0.3.0"
 description = "Add your description here"
 readme = "README.md"
 authors = [
@@ -8,6 +8,7 @@ authors = [
 ]
 requires-python = ">=3.10"
 dependencies = [
+    "numerical",
     "numpy>=2.2.1",
     "scipy>=1.15.0",
 ]
@@ -21,3 +22,6 @@ 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.1.0 → oprattr-0.3.0}/src/oprattr/__init__.py

@@ -1,12 +1,13 @@
+import collections.abc
 import functools
 import numbers
-import typing
 
 import numpy
 
+from . import abstract
 from . import mixins
 from . import operators
-from . import _types
+from . import typeface
 from ._operations import (
     unary,
     equality,
@@ -16,10 +17,10 @@ from ._operations import (
 )
 
 
-T = typing.TypeVar('T')
+T = typeface.TypeVar('T')
 
 
-class Operand(_types.Object[T], mixins.Numpy):
+class Operand(abstract.Object[T], mixins.Numpy):
     """A concrete implementation of a real-valued object."""
 
     def __abs__(self):
@@ -114,7 +115,7 @@ class Operand(_types.Object[T], mixins.Numpy):
 
     def __rpow__(self, other):
         """Called for other ** self."""
-        return super().__rpow__(other)
+        return NotImplemented
 
     def __array__(self, *args, **kwargs):
         """Called for numpy.array(self)."""
@@ -155,7 +156,7 @@ def gradient(x: Operand[T], *args, **kwargs):
     return type(x)(data, **meta)
 
 
-def wrapnumpy(f: typing.Callable):
+def wrapnumpy(f: collections.abc.Callable):
     """Implement a numpy function for objects with metadata."""
     @functools.wraps(f)
     def method(x: Operand[T], **kwargs):

{oprattr-0.1.0 → oprattr-0.3.0}/src/oprattr/_operations.py

@@ -1,7 +1,5 @@
-import typing
-
 from . import operators
-from ._types import Object
+from .abstract import Quantity
 
 
 class MetadataError(TypeError):
@@ -11,8 +9,8 @@ class MetadataError(TypeError):
         self,
         f: operators.Operator,
         *args,
-        error: typing.Optional[str]=None,
-        key: typing.Optional[str]=None,
+        error: str | None = None,
+        key: str | None = None,
     ) -> None:
         super().__init__(*args)
         self._f = f
@@ -33,8 +31,8 @@ class MetadataError(TypeError):
 def _build_error_message(
     f: operators.Operator,
     *types: type,
-    error: typing.Optional[str]=None,
-    key: typing.Optional[str]=None,
+    error: str | None = None,
+    key: str | None = None,
 ) -> str:
     """Helper for `_raise_metadata_exception`.
     
@@ -50,9 +48,9 @@ def _build_error_message(
         if len(types) == 2:
             a, b = types
             endstr = "because {} has metadata"
-            if issubclass(a, Object):
+            if issubclass(a, Quantity):
                 return f"{errmsg} between {a} and {b} {endstr.format(str(a))}"
-            if issubclass(b, Object):
+            if issubclass(b, Quantity):
                 return f"{errmsg} between {a} and {b} {endstr.format(str(b))}"
     if errstr == 'type':
         if key is None:
@@ -71,7 +69,7 @@ def _build_error_message(
 
 def unary(f: operators.Operator, a):
     """Compute the unary operation f(a)."""
-    if isinstance(a, Object):
+    if isinstance(a, Quantity):
         meta = {}
         for key, value in a._meta.items():
             try:
@@ -86,15 +84,15 @@ def unary(f: operators.Operator, a):
 
 def equality(f: operators.Operator, a, b):
     """Compute the equality operation f(a, b)."""
-    if isinstance(a, Object) and isinstance(b, Object):
+    if isinstance(a, Quantity) and isinstance(b, Quantity):
         if a._meta != b._meta:
             return f is operators.ne
         return f(a._data, b._data)
-    if isinstance(a, Object):
+    if isinstance(a, Quantity):
         if not a._meta:
             return f(a._data, b)
         return f is operators.ne
-    if isinstance(b, Object):
+    if isinstance(b, Quantity):
         if not b._meta:
             return f(a, b._data)
         return f is operators.ne
@@ -103,15 +101,15 @@ def equality(f: operators.Operator, 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 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, Object):
+    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, Object):
+    if isinstance(b, Quantity):
         if not b._meta:
             return f(a, b._data)
         raise MetadataError(f, a, b, error='non-empty') from None
@@ -120,15 +118,15 @@ def ordering(f: operators.Operator, 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 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, Object):
+    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, Object):
+    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
@@ -137,7 +135,7 @@ def additive(f: operators.Operator, a, b):
 
 def multiplicative(f: operators.Operator, a, b):
     """Compute the multiplicative operation f(a, b)."""
-    if isinstance(a, Object) and isinstance(b, Object):
+    if isinstance(a, Quantity) and isinstance(b, Quantity):
         keys = set(a._meta) & set(b._meta)
         meta = {}
         for key in keys:
@@ -154,7 +152,7 @@ def multiplicative(f: operators.Operator, a, b):
             if key not in keys:
                 meta[key] = value
         return type(a)(f(a._data, b._data), **meta)
-    if isinstance(a, Object):
+    if isinstance(a, Quantity):
         meta = {}
         for key, value in a._meta.items():
             try:
@@ -164,7 +162,7 @@ def multiplicative(f: operators.Operator, a, b):
             else:
                 meta[key] = v
         return type(a)(f(a._data, b), **meta)
-    if isinstance(b, Object):
+    if isinstance(b, Quantity):
         meta = {}
         for key, value in b._meta.items():
             try:

oprattr-0.3.0/src/oprattr/abstract.py

@@ -0,0 +1,56 @@
+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 __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-0.1.0 → oprattr-0.3.0}/src/oprattr/mixins.py

@@ -1,15 +1,89 @@
+import collections.abc
 import numbers
-import typing
 
 import numpy
 
-from . import _types
+from . import abstract
+from . import typeface
 
 
-T = typing.TypeVar('T')
+T = typeface.TypeVar('T')
 
 
-UserFunction = typing.Callable[..., 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:
@@ -54,7 +128,7 @@ class Numpy:
         numpy.ndarray,
         numbers.Number,
         list,
-        _types.Object,
+        abstract.Quantity,
     }
 
     def __array_ufunc__(self, ufunc, method, *args, **kwargs):
@@ -89,7 +163,7 @@ class Numpy:
             return NotImplemented
         if out:
             kwargs['out'] = tuple(
-                x._data if isinstance(x, _types.Object)
+                x._data if isinstance(x, abstract.Quantity)
                 else x for x in out
             )
         if self._implements(ufunc):
@@ -134,7 +208,7 @@ class Numpy:
 
     _FUNCTION_TYPES = {
         numpy.ndarray,
-        _types.Object,
+        abstract.Object,
      } | set(numpy.ScalarType)
 
     def __array_function__(self, func, types, args, kwargs):
@@ -212,7 +286,7 @@ class Numpy:
         types = self._get_numpy_types(types)
         return array.__array_function__(func, types, args, kwargs)
 
-    def _get_numpy_array(self) -> typing.Optional[numpy.typing.NDArray]:
+    def _get_numpy_array(self) -> numpy.typing.NDArray | None:
         """Convert the data interface to an array for `numpy` mixin methods.
         
         Notes
@@ -251,7 +325,7 @@ class Numpy:
           `arg` if `arg` is an instance of the base object class; otherwise, it
           will return the unmodified argument.
         """
-        if isinstance(arg, _types.Object):
+        if isinstance(arg, abstract.Quantity):
             return arg._data
         return arg
 
@@ -267,11 +341,11 @@ class Numpy:
         """
         return tuple(
             ti for ti in types
-            if not issubclass(ti, _types.Object)
+            if not issubclass(ti, abstract.Object)
         )
 
     @classmethod
-    def _implements(cls, operation: typing.Callable):
+    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
@@ -283,11 +357,11 @@ class Numpy:
             return False
         return result
 
-    _FUNCTIONS: typing.Dict[str, typing.Callable]=None
+    _FUNCTIONS: dict[str, collections.abc.Callable]=None
     """Internal collection of custom `numpy` function implementations."""
 
     @classmethod
-    def implementation(cls, numpy_function: typing.Callable, /):
+    def implementation(cls, numpy_function: collections.abc.Callable, /):
         """Register a custom implementation of this `numpy` function.
 
         Parameters
@@ -351,7 +425,7 @@ class Numpy:
     @classmethod
     def implement(
         cls,
-        numpy_function: typing.Callable,
+        numpy_function: collections.abc.Callable,
         user_function: UserFunction,
         /,
     ) -> None:

{oprattr-0.1.0 → oprattr-0.3.0}/src/oprattr/operators.py

@@ -2,14 +2,14 @@
 A namespace for operators used by this package's `Object` class.
 """
 
+import collections.abc
 import builtins
 import operator
-import typing
 
 
 class Operator:
     """Base class for enhanced operators."""
-    def __init__(self, __f: typing.Callable, operation: str):
+    def __init__(self, __f: collections.abc.Callable, operation: str):
         self._f = __f
         self._operation = operation
 

oprattr-0.3.0/src/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-0.3.0/src/oprattr/typeface.pyi

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

{oprattr-0.1.0 → oprattr-0.3.0}/tests/print-exceptions.py

@@ -1,6 +1,6 @@
 """
 This script generates and echos exceptions related to operations on instances of
-the `Object` class. It is meant as a supplement to rigorous tests.
+the `Operand` class. It is meant as a supplement to rigorous tests.
 """
 
 import oprattr