algorand-python-testing 0.0.0b1__py3-none-any.whl

algopy_testing/primitives/__init__.py

@@ -0,0 +1,6 @@
+from algopy_testing.primitives.biguint import BigUInt
+from algopy_testing.primitives.bytes import Bytes
+from algopy_testing.primitives.string import String
+from algopy_testing.primitives.uint64 import UInt64
+
+__all__ = ["BigUInt", "Bytes", "String", "UInt64"]

algopy_testing/primitives/biguint.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import functools
+
+from algopy_testing.constants import UINT64_BYTES_LENGTH
+from algopy_testing.primitives.bytes import Bytes
+from algopy_testing.primitives.uint64 import UInt64
+from algopy_testing.protocols import BytesBacked
+from algopy_testing.utils import as_bytes, as_int, as_int512, int_to_bytes
+
+# TypeError, ValueError are used for operations that are compile time errors
+# ArithmeticError and subclasses are used for operations that would fail during AVM execution
+
+
+@functools.total_ordering
+class BigUInt(BytesBacked):
+    """
+    A python implementation of an TEAL bigint type represented by AVM []byte type
+    """
+
+    __value: bytes  # underlying 'bytes' value representing the BigUInt
+
+    def __init__(self, value: UInt64 | int = 0) -> None:
+        self.__value = (
+            _int_to_bytes(value.value, UINT64_BYTES_LENGTH)
+            if isinstance(value, UInt64)
+            else _int_to_bytes(value)
+        )
+
+    def __repr__(self) -> str:
+        return f"{self.value}u"
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+    # comparison operations should not error when comparing any uint type
+    # e.g. UInt64, BigUInt, arc4.UInt*, arc4.BigUint*
+    # however will raise a TypeError if compared to something that is not a numeric value
+    # as this would be a compile error when compiled to TEAL
+    def __eq__(self, other: object) -> bool:
+        return as_int512(self) == as_int512(other)
+
+    def __lt__(self, other: BigUInt | UInt64 | int) -> bool:
+        return as_int512(self) < as_int512(other)
+
+    def __bool__(self) -> bool:
+        return bool(as_int512(self))
+
+    def __add__(self, other: BigUInt | UInt64 | int) -> BigUInt:
+        return _checked_result(as_int512(self) + as_int512(other), "+")
+
+    # the reflected dunder methods (__radd__, __rsub___, etc.) should only be called when the
+    # BigUInt is on the right hand side and UInt64 or int on the left
+    def __radd__(self, other: int | UInt64) -> BigUInt:
+        return self + other
+
+    def __sub__(self, other: BigUInt | UInt64 | int) -> BigUInt:
+        return _checked_result(as_int512(self) - as_int512(other), "-")
+
+    def __rsub__(self, other: int | UInt64) -> BigUInt:
+        return _as_biguint(other) - self
+
+    def __mul__(self, other: BigUInt | UInt64 | int) -> BigUInt:
+        return _checked_result(as_int512(self) * as_int512(other), "*")
+
+    def __rmul__(self, other: int | UInt64) -> BigUInt:
+        return self * other
+
+    def __floordiv__(self, denominator: BigUInt | UInt64 | int) -> BigUInt:
+        return _checked_result(as_int512(self) // as_int512(denominator), "//")
+
+    def __rfloordiv__(self, numerator: int | UInt64) -> BigUInt:
+        return _as_biguint(numerator) // self
+
+    def __mod__(self, denominator: BigUInt | UInt64 | int) -> BigUInt:
+        return _checked_result(as_int512(self) % as_int512(denominator), "%")
+
+    def __rmod__(self, numerator: int | UInt64) -> BigUInt:
+        return _as_biguint(numerator) % self
+
+    def __and__(self, other: BigUInt | UInt64 | int) -> BigUInt:
+        assert as_int512(self) >= 0
+        assert as_int512(other) >= 0
+        return BigUInt.from_bytes(self.bytes & _as_biguint(other).bytes)
+
+    def __rand__(self, other: BigUInt | UInt64 | int) -> BigUInt:
+        return self & other
+
+    def __or__(self, other: BigUInt | UInt64 | int) -> BigUInt:
+        assert as_int512(self) >= 0
+        assert as_int512(other) >= 0
+        return BigUInt.from_bytes(self.bytes | _as_biguint(other).bytes)
+
+    def __ror__(self, other: BigUInt | UInt64 | int) -> BigUInt:
+        return self | other
+
+    def __xor__(self, other: BigUInt | UInt64 | int) -> BigUInt:
+        assert as_int512(self) >= 0
+        assert as_int512(other) >= 0
+        return BigUInt.from_bytes(self.bytes ^ _as_biguint(other).bytes)
+
+    def __rxor__(self, other: BigUInt | UInt64 | int) -> BigUInt:
+        return self ^ other
+
+    def __pos__(self) -> BigUInt:
+        """
+        Compute the unary positive of the BigUInt.
+
+        Returns:
+            BigUInt: The result of the unary positive operation.
+        """
+        return BigUInt(+as_int512(self))
+
+    @classmethod
+    def from_bytes(cls, value: Bytes | bytes) -> BigUInt:
+        """Construct an instance from the underlying bytes (no validation)"""
+        result = cls()
+        result.__value = as_bytes(value)
+        return result
+
+    @property
+    def bytes(self) -> Bytes:
+        """Get the underlying Bytes"""
+        return Bytes(self.__value)
+
+    @property
+    def value(self) -> int:
+        """Get the underlying int"""
+        return int.from_bytes(self.__value)
+
+
+def _checked_result(result: int, op: str) -> BigUInt:
+    """Ensures `result` is a valid BigUInt value
+
+    Raises:
+        ArithmeticError: If `result` of `op` is negative"""
+    if result < 0:
+        raise ArithmeticError(f"{op} underflows")
+    return BigUInt(result)
+
+
+def _as_biguint(value: object) -> BigUInt:
+    return BigUInt(value if (isinstance(value, UInt64)) else as_int(value, max=None))
+
+
+def _int_to_bytes(x: int, pad_to: int | None = None) -> bytes:
+    x = as_int(x, max=None)
+    return int_to_bytes(x, pad_to=pad_to)

algopy_testing/primitives/bytes.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import base64
+import operator
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+from itertools import zip_longest
+
+from algopy_testing.constants import MAX_BYTES_SIZE
+from algopy_testing.primitives.uint64 import UInt64
+from algopy_testing.utils import as_bytes, as_int64
+
+# TypeError, ValueError are used for operations that are compile time errors
+# ArithmeticError and subclasses are used for operations that would fail during AVM execution
+
+
+class Bytes:
+    """
+    A python implementation of an AVM []byte
+    """
+
+    value: bytes  # underlying bytes value representing the []byte
+
+    def __init__(self, value: bytes = b"") -> None:
+        self.value = as_bytes(value)
+
+    def __repr__(self) -> str:
+        return repr(self.value)
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+    def __bool__(self) -> bool:
+        return bool(self.value)
+
+    def __add__(self, other: Bytes | bytes) -> Bytes:
+        """Concatenate Bytes with another Bytes or bytes literal
+        e.g. `Bytes(b"Hello ") + b"World"`."""
+        if isinstance(other, Bytes):
+            return _checked_result(self.value + other.value, "+")
+        else:
+            result = self.value + as_bytes(other)
+            return _checked_result(result, "+")
+
+    def __radd__(self, other: bytes) -> Bytes:
+        """Concatenate Bytes with another Bytes or bytes literal
+        e.g. `b"Hello " + Bytes(b"World")`."""
+        return _checked_result(other + self.value, "+")
+
+    def __len__(self) -> int:
+        return len(self.value)
+
+    def __iter__(self) -> Iterator[Bytes]:
+        """Bytes can be iterated, yielding each consecutive byte"""
+        return _BytesIter(self, 1)
+
+    def __reversed__(self) -> Iterator[Bytes]:
+        """Bytes can be iterated in reverse, yield each preceding byte starting at the end"""
+        return _BytesIter(self, -1)
+
+    def __getitem__(
+        self, index: UInt64 | int | slice
+    ) -> Bytes:  # maps to substring/substring3 if slice, extract/extract3 otherwise?
+        """Returns a Bytes containing a single byte if indexed with UInt64 or int
+        otherwise the substring o bytes described by the slice"""
+        if isinstance(index, slice):
+            return Bytes(self.value[index])
+        else:
+            int_index = as_int64(index)
+            # my_bytes[0:1] => b'j' whereas my_bytes[0] => 106
+            return Bytes(self.value[slice(int_index, int_index + 1)])
+
+    def __eq__(self, other: object) -> bool:
+        return self.value == as_bytes(other)
+
+    def __and__(self, other: bytes | Bytes) -> Bytes:
+        return self._operate_bitwise(other, "and_")
+
+    def __rand__(self, other: bytes) -> Bytes:
+        return self & other
+
+    def __or__(self, other: bytes | Bytes) -> Bytes:
+        return self._operate_bitwise(other, "or_")
+
+    def __ror__(self, other: bytes) -> Bytes:
+        return self | other
+
+    def __xor__(self, other: bytes | Bytes) -> Bytes:
+        return self._operate_bitwise(other, "xor")
+
+    def __rxor__(self, other: bytes) -> Bytes:
+        return self ^ other
+
+    def __invert__(self) -> Bytes:
+        """
+        Compute the bitwise inversion of the Bytes.
+
+        Returns:
+            Bytes: The result of the bitwise inversion operation.
+        """
+        return Bytes(bytes(~x + 256 for x in self.value))
+
+    def _operate_bitwise(self, other: bytes | Bytes, operator_name: str) -> Bytes:
+        op = getattr(operator, operator_name)
+        maybe_bytes = as_bytes(other)
+        # pad the shorter of self.value and other bytes with leading zero
+        # by reversing them as zip_longest fills at the end
+        return Bytes(
+            bytes(
+                reversed(
+                    bytes(
+                        op(a[0], a[1])
+                        for a in zip_longest(
+                            reversed(self.value), reversed(maybe_bytes), fillvalue=0
+                        )
+                    )
+                )
+            )
+        )
+
+    @property
+    def length(self) -> UInt64:
+        """Returns the length of the Bytes"""
+        return UInt64(len(self.value))
+
+    @staticmethod
+    def from_base32(value: str) -> Bytes:
+        """Creates Bytes from a base32 encoded string e.g. `Bytes.from_base32("74======")`"""
+        return Bytes(base64.b32decode(value))
+
+    @staticmethod
+    def from_base64(value: str) -> Bytes:
+        """Creates Bytes from a base64 encoded string e.g. `Bytes.from_base64("RkY=")`"""
+        return Bytes(base64.b64decode(value))
+
+    @staticmethod
+    def from_hex(value: str) -> Bytes:
+        """Creates Bytes from a hex/octal encoded string e.g. `Bytes.from_hex("FF")`"""
+        return Bytes(base64.b16decode(value))
+
+
+class _BytesIter:
+    value: Bytes
+
+    def __init__(self, sequence: Bytes, step: int = 1):
+        self.value = sequence
+        self.current = 0 if step > 0 else len(sequence) - 1
+        self.step = step
+        self.myend = len(sequence) - 1 if step > 0 else 0
+
+    def __iter__(self) -> _BytesIter:
+        return self
+
+    def __next__(self) -> Bytes:
+        # if current is one step over the end
+        if self.current == self.myend + self.step:
+            raise StopIteration
+
+        self.current += self.step
+        return self.value[self.current - self.step]
+
+
+def _checked_result(result: bytes, op: str) -> Bytes:
+    """Ensures `result` is a valid Bytes value
+
+    Raises:
+        ArithmeticError: If `result` of `op` is out of bounds"""
+    if len(result) > MAX_BYTES_SIZE:
+        raise OverflowError(f"{op} overflows")
+    return Bytes(result)

algopy_testing/primitives/string.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from algopy_testing.primitives.bytes import Bytes
+from algopy_testing.protocols import BytesBacked
+from algopy_testing.utils import as_bytes, as_string
+
+
+class String(BytesBacked):
+    """
+    Represents a UTF-8 encoded string backed by Bytes, accessible via .bytes.
+
+    Works with str literals instead of bytes literals. Due to lack of AVM support for unicode,
+    indexing and length operations are not supported. Use .bytes.length for byte length.
+    """
+
+    _value: bytes  # underlying 'bytes' value representing the String
+
+    def __init__(self, value: str = "") -> None:
+        if not isinstance(value, str):
+            raise TypeError(f"expected str, got {type(value).__name__!r}")
+        self._value = value.encode("utf-8")
+
+    def __repr__(self) -> str:
+        return repr(self.value)
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+    def __bool__(self) -> bool:
+        return bool(self.value)
+
+    def __eq__(self, other: object) -> bool:
+        return self.value == as_string(other)
+
+    def __contains__(self, item: object) -> bool:
+        return as_string(item) in self.value
+
+    def __add__(self, other: String | str) -> String:
+        return String(self.value + as_string(other))
+
+    def __radd__(self, other: String | str) -> String:
+        return String(as_string(other) + self.value)
+
+    def startswith(self, prefix: String | str) -> bool:
+        return self.value.startswith(as_string(prefix))
+
+    def endswith(self, suffix: String | str) -> bool:
+        return self.value.endswith(as_string(suffix))
+
+    def join(self, others: tuple[String, ...], /) -> String:
+        return String(self.value.join(map(as_string, others)))
+
+    @classmethod
+    def from_bytes(cls, value: Bytes | bytes) -> String:
+        """Construct an instance from the underlying bytes (no validation)"""
+        value = as_bytes(value)
+        result = cls()
+        result._value = bytes(value)
+        return result
+
+    @property
+    def bytes(self) -> Bytes:
+        """Get the underlying Bytes"""
+        return Bytes(self._value)
+
+    @property
+    def value(self) -> str:
+        return self._value.decode("utf-8")

algopy_testing/primitives/uint64.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import functools
+
+from algopy_testing.constants import MAX_UINT64
+from algopy_testing.utils import as_int64
+
+# TypeError, ValueError are used for operations that are compile time errors
+# ArithmeticError and subclasses are used for operations that would fail during AVM execution
+
+
+@functools.total_ordering
+class UInt64:
+    """
+    A python implementation of an AVM 64-bit unsigned integer
+    """
+
+    value: int  # underlying 'int' value representing the UInt64
+
+    def __init__(self, value: int = 0) -> None:
+        self.value = as_int64(value)
+
+    def __repr__(self) -> str:
+        return f"{self.value}u"
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+    # comparison operations should not error when comparing any uint type
+    # e.g. UInt64, BigUInt, arc4.UInt*, arc4.BigUint*
+    # however will raise a TypeError if compared to something that is not a numeric value
+    # as this would be a compile error when compiled to TEAL
+    def __eq__(self, other: object) -> bool:
+        maybe_int = _as_maybe_uint64(other)
+        # returning NotImplemented here will allow BigUInt to handle larger comparisons
+        if maybe_int is None:
+            return NotImplemented
+        return self.value == maybe_int
+
+    def __lt__(self, other: int | UInt64) -> bool:
+        maybe_int = _as_maybe_uint64(other)
+        # returning NotImplemented here will allow BigUInt to handle larger comparisons
+        if maybe_int is None:
+            return NotImplemented
+        return self.value < maybe_int
+
+    def __bool__(self) -> bool:
+        return self.value != 0
+
+    def __add__(self, other: int | UInt64) -> UInt64:
+        maybe_int = _as_maybe_uint64(other)
+        # returning NotImplemented here will allow BigUInt (and others) to upcast
+        # a BigUint + UInt64 operation
+        if maybe_int is None:
+            return NotImplemented
+        return _checked_result(self.value + maybe_int, "+")
+
+    # the reflected dunder methods (__radd__, __rsub___, etc.) should only be called when the
+    # UInt64 is on the right hand side and an int on the left
+    def __radd__(self, other: int) -> UInt64:
+        return self + other
+
+    def __sub__(self, other: int | UInt64) -> UInt64:
+        maybe_int = _as_maybe_uint64(other)
+        if maybe_int is None:
+            return NotImplemented
+        return _checked_result(self.value - maybe_int, "-")
+
+    def __rsub__(self, other: int) -> UInt64:
+        return _as_uint64(other) - self
+
+    def __mul__(self, other: int | UInt64) -> UInt64:
+        maybe_int = _as_maybe_uint64(other)
+        if maybe_int is None:
+            return NotImplemented
+        return _checked_result(self.value * maybe_int, "*")
+
+    def __rmul__(self, other: int) -> UInt64:
+        return self * other
+
+    def __floordiv__(self, denominator: int | UInt64) -> UInt64:
+        maybe_int = _as_maybe_uint64(denominator)
+        if maybe_int is None:
+            return NotImplemented
+        return _checked_result(self.value // maybe_int, "//")
+
+    def __rfloordiv__(self, numerator: int) -> UInt64:
+        return _as_uint64(numerator) // self
+
+    def __mod__(self, denominator: int | UInt64) -> UInt64:
+        maybe_int = _as_maybe_uint64(denominator)
+        if maybe_int is None:
+            return NotImplemented
+
+        return _checked_result(self.value % maybe_int, "%")
+
+    def __rmod__(self, numerator: int) -> UInt64:
+        return _as_uint64(numerator) % self
+
+    def __pow__(self, exp: int | UInt64, modulo: int | UInt64 | None = None) -> UInt64:
+        exp_int = _as_maybe_uint64(exp)
+        if exp_int is None:
+            return NotImplemented
+        if modulo is not None:
+            return NotImplemented
+        if self.value == 0 and exp_int == 0:
+            raise ArithmeticError("UInt64(0)**UInt64(0) is undefined")
+        return _checked_result(self.value**exp_int, "**")
+
+    def __rpow__(self, base: int, modulo: int | UInt64 | None = None) -> UInt64:
+        return pow(_as_uint64(base), self, modulo)
+
+    def __and__(self, other: int | UInt64) -> UInt64:
+        maybe_int = _as_maybe_uint64(other)
+        if maybe_int is None:
+            return NotImplemented
+        return UInt64(self.value & maybe_int)
+
+    def __rand__(self, other: int) -> UInt64:
+        return self & other
+
+    def __or__(self, other: int | UInt64) -> UInt64:
+        maybe_int = _as_maybe_uint64(other)
+        if maybe_int is None:
+            return NotImplemented
+        return UInt64(self.value | maybe_int)
+
+    def __ror__(self, other: int | UInt64) -> UInt64:
+        return self | other
+
+    def __xor__(self, other: int | UInt64) -> UInt64:
+        maybe_int = _as_maybe_uint64(other)
+        if maybe_int is None:
+            return NotImplemented
+        return UInt64(self.value ^ maybe_int)
+
+    def __rxor__(self, other: int | UInt64) -> UInt64:
+        return self ^ other
+
+    def __lshift__(self, other: int | UInt64) -> UInt64:
+        shift = as_int64(other)
+        if shift > 63:
+            raise ArithmeticError("expected shift <= 63")
+        return UInt64((self.value << shift) & MAX_UINT64)
+
+    def __rlshift__(self, other: int | UInt64) -> UInt64:
+        return _as_uint64(other) << self
+
+    def __rshift__(self, other: int | UInt64) -> UInt64:
+        shift = as_int64(other)
+        if shift > 63:
+            raise ArithmeticError("expected shift <= 63")
+        return UInt64((self.value >> shift) & MAX_UINT64)
+
+    def __rrshift__(self, other: int | UInt64) -> UInt64:
+        return _as_uint64(other) >> self
+
+    def __invert__(self) -> UInt64:
+        """
+        Compute the bitwise inversion of the UInt64.
+
+        Returns:
+            UInt64: The result of the bitwise inversion operation.
+        """
+        return UInt64(~self.value & MAX_UINT64)
+
+    def __index__(self) -> int:
+        """
+        Return the internal integer value of the UInt64 for use in indexing/slice expressions.
+
+        Returns:
+            int: The internal integer value of the UInt64.
+        """
+        return self.value
+
+    def __pos__(self) -> UInt64:
+        """
+        Compute the unary positive of the UInt64.
+
+        Returns:
+            UInt64: The result of the unary positive operation.
+        """
+        return UInt64(+self.value)
+
+    def __hash__(self) -> int:
+        return hash(self.value)
+
+
+def _as_maybe_uint64(value: object) -> int | None:
+    """Returns int value if `value` is an int or UInt64, otherwise None"""
+    match value:
+        case int(int_value):
+            return as_int64(int_value)
+        case UInt64(value=int_value):
+            return int_value
+        case _:
+            return None
+
+
+def _checked_result(result: int, op: str) -> UInt64:
+    """Ensures `result` is a valid UInt64 value
+
+    Raises:
+        ArithmeticError: If `result` of `op` is out of bounds"""
+    if result < 0:
+        raise ArithmeticError(f"{op} underflows")
+    if result > MAX_UINT64:
+        raise OverflowError(f"{op} overflows")
+    return UInt64(result)
+
+
+def _as_uint64(value: object) -> UInt64:
+    return UInt64(as_int64(value))

algopy_testing/protocols.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import typing
+
+if typing.TYPE_CHECKING:
+    import algopy
+
+
+class BytesBacked(typing.Protocol):
+    """Represents a type that is a single bytes value"""
+
+    @classmethod
+    def from_bytes(cls, value: algopy.Bytes | bytes, /) -> typing.Self:
+        """Construct an instance from the underlying bytes (no validation)"""
+
+    @property
+    def bytes(self) -> algopy.Bytes:
+        """Get the underlying Bytes"""

algopy_testing/state/__init__.py

@@ -0,0 +1,4 @@
+from algopy_testing.state.global_state import GlobalState
+from algopy_testing.state.local_state import LocalState
+
+__all__ = ["GlobalState", "LocalState"]