algorand-python-testing 0.2.1__py3-none-any.whl → 0.2.2b2__py3-none-any.whl

algopy/__init__.py

@@ -10,11 +10,14 @@ from algopy_testing.models import (
     GTxn,
     ITxn,
     LogicSig,
+    StateTotals,
     TemplateVar,
     Txn,
     logicsig,
+    uenumerate,
     urange,
 )
+from algopy_testing.models.box import Box, BoxMap, BoxRef
 from algopy_testing.primitives import BigUInt, Bytes, String, UInt64
 from algopy_testing.protocols import BytesBacked
 from algopy_testing.state import GlobalState, LocalState
@@ -55,4 +58,7 @@ __all__ = [
     "subroutine",
     "uenumerate",
     "urange",
+    "Box",
+    "BoxRef",
+    "BoxMap",
 ]

algopy_testing/context.py

@@ -285,7 +285,7 @@ class AlgopyTestContext:
         self._scratch_spaces: dict[str, list[algopy.Bytes | algopy.UInt64 | bytes | int]] = {}
         self._template_vars: dict[str, Any] = template_vars or {}
         self._blocks: dict[int, dict[str, int]] = {}
-        self._boxes: dict[bytes, algopy.Bytes] = {}
+        self._boxes: dict[bytes, bytes] = {}
         self._lsigs: dict[algopy.LogicSig, Callable[[], algopy.UInt64 | bool]] = {}
         self._active_lsig_args: Sequence[algopy.Bytes] = []
 
@@ -1047,20 +1047,23 @@ class AlgopyTestContext:
 
         return new_txn
 
-    def get_box(self, name: algopy.Bytes | bytes) -> algopy.Bytes:
+    def does_box_exist(self, name: algopy.Bytes | bytes) -> bool:
+        """return true if the box with the given name exists."""
+        name_bytes = name if isinstance(name, bytes) else name.value
+        return name_bytes in self._boxes
+
+    def get_box(self, name: algopy.Bytes | bytes) -> bytes:
         """Get the content of a box."""
-        import algopy
 
         name_bytes = name if isinstance(name, bytes) else name.value
-        return self._boxes.get(name_bytes, algopy.Bytes(b""))
+        return self._boxes.get(name_bytes, b"")
 
     def set_box(self, name: algopy.Bytes | bytes, content: algopy.Bytes | bytes) -> None:
         """Set the content of a box."""
-        import algopy
 
         name_bytes = name if isinstance(name, bytes) else name.value
         content_bytes = content if isinstance(content, bytes) else content.value
-        self._boxes[name_bytes] = algopy.Bytes(content_bytes)
+        self._boxes[name_bytes] = content_bytes
 
     def execute_logicsig(
         self, lsig: algopy.LogicSig, lsig_args: Sequence[algopy.Bytes] | None = None
@@ -1071,12 +1074,14 @@ class AlgopyTestContext:
             self._lsigs[lsig] = lsig.func
         return lsig.func()
 
-    def clear_box(self, name: algopy.Bytes | bytes) -> None:
+    def clear_box(self, name: algopy.Bytes | bytes) -> bool:
         """Clear the content of a box."""
 
         name_bytes = name if isinstance(name, bytes) else name.value
         if name_bytes in self._boxes:
             del self._boxes[name_bytes]
+            return True
+        return False
 
     def clear_all_boxes(self) -> None:
         """Clear all boxes."""
@@ -1170,7 +1175,6 @@ class AlgopyTestContext:
         self._app_id = iter(range(1, 2**64))
 
 
-#
 _var: ContextVar[AlgopyTestContext] = ContextVar("_var")
 
 

algopy_testing/enums.py

@@ -1,22 +1,42 @@
-from enum import Enum, IntEnum, StrEnum
+from __future__ import annotations
 
+from enum import Enum, StrEnum
 
-class OnCompleteAction(Enum):
-    NoOp = 0
-    OptIn = 1
-    CloseOut = 2
-    ClearState = 3
-    UpdateApplication = 4
-    DeleteApplication = 5
+from algopy_testing.primitives import UInt64
 
 
-class TransactionType(IntEnum):
-    Payment = 0
-    KeyRegistration = 1
-    AssetConfig = 2
-    AssetTransfer = 3
-    AssetFreeze = 4
-    ApplicationCall = 5
+class OnCompleteAction(UInt64):
+    NoOp: OnCompleteAction
+    OptIn: OnCompleteAction
+    CloseOut: OnCompleteAction
+    ClearState: OnCompleteAction
+    UpdateApplication: OnCompleteAction
+    DeleteApplication: OnCompleteAction
+
+
+OnCompleteAction.NoOp = OnCompleteAction(0)
+OnCompleteAction.OptIn = OnCompleteAction(1)
+OnCompleteAction.CloseOut = OnCompleteAction(2)
+OnCompleteAction.ClearState = OnCompleteAction(3)
+OnCompleteAction.UpdateApplication = OnCompleteAction(4)
+OnCompleteAction.DeleteApplication = OnCompleteAction(5)
+
+
+class TransactionType(UInt64):
+    Payment: TransactionType
+    KeyRegistration: TransactionType
+    AssetConfig: TransactionType
+    AssetTransfer: TransactionType
+    AssetFreeze: TransactionType
+    ApplicationCall: TransactionType
+
+
+TransactionType.Payment = TransactionType(0)
+TransactionType.KeyRegistration = TransactionType(1)
+TransactionType.AssetConfig = TransactionType(2)
+TransactionType.AssetTransfer = TransactionType(3)
+TransactionType.AssetFreeze = TransactionType(4)
+TransactionType.ApplicationCall = TransactionType(5)
 
 
 class ECDSA(Enum):

algopy_testing/models/box.py

@@ -1,141 +1,258 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+import typing
 
+from algopy_testing.constants import MAX_BOX_SIZE
 from algopy_testing.context import get_test_context
+from algopy_testing.utils import as_bytes, as_string
 
-if TYPE_CHECKING:
+_TKey = typing.TypeVar("_TKey")
+_TValue = typing.TypeVar("_TValue")
+
+if typing.TYPE_CHECKING:
     import algopy
 
 
-class Box:
-    @staticmethod
-    def create(a: algopy.Bytes | bytes, b: algopy.UInt64 | int, /) -> bool:
+class Box(typing.Generic[_TValue]):
+    """
+    Box abstracts the reading and writing of a single value to a single box.
+    The box size will be reconfigured dynamically to fit the size of the value being assigned to
+    it.
+    """
+
+    def __init__(
+        self, type_: type[_TValue], /, *, key: bytes | str | algopy.Bytes | algopy.String = ""
+    ) -> None:
         import algopy
 
+        self._type = type_
+
+        self._key = (
+            algopy.String(as_string(key)).bytes
+            if isinstance(key, str | algopy.String)
+            else algopy.Bytes(as_bytes(key))
+        )
+
+    def __bool__(self) -> bool:
+        """
+        Returns True if the box exists, regardless of the truthiness of the contents
+        of the box
+        """
         context = get_test_context()
-        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
-        size = int(b)
-        if not name_bytes or size > 32768:
-            raise ValueError("Invalid box name or size")
-        if context.get_box(name_bytes):
-            return False
-        context.set_box(name_bytes, b"\x00" * size)
-        return True
+        return context.does_box_exist(self.key)
 
-    @staticmethod
-    def delete(a: algopy.Bytes | bytes, /) -> bool:
-        import algopy
+    @property
+    def key(self) -> algopy.Bytes:
+        """Provides access to the raw storage key"""
+        if not self._key:
+            raise RuntimeError("Box key is empty")
+        return self._key
 
+    @property
+    def value(self) -> _TValue:
+        """Retrieve the contents of the box. Fails if the box has not been created."""
         context = get_test_context()
-        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
-        if context.get_box(name_bytes):
-            context.clear_box(name_bytes)
-            return True
-        return False
+        if not context.does_box_exist(self.key):
+            raise RuntimeError("Box has not been created")
+        return _cast_to_value_type(self._type, context.get_box(self.key))
 
-    @staticmethod
-    def extract(
-        a: algopy.Bytes | bytes, b: algopy.UInt64 | int, c: algopy.UInt64 | int, /
-    ) -> algopy.Bytes:
-        import algopy
+    @value.setter
+    def value(self, value: _TValue) -> None:
+        """Write _value_ to the box. Creates the box if it does not exist."""
+        context = get_test_context()
+        bytes_value = _cast_to_bytes(value)
+        context.set_box(self.key, bytes_value)
 
+    @value.deleter
+    def value(self) -> None:
+        """Delete the box"""
         context = get_test_context()
-        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
-        start = int(b)
-        length = int(c)
-        box_content = context.get_box(name_bytes)
-        if not box_content:
-            raise ValueError("Box does not exist")
-        return box_content[start : start + length]
+        context.clear_box(self.key)
 
-    @staticmethod
-    def get(a: algopy.Bytes | bytes, /) -> tuple[algopy.Bytes, bool]:
-        import algopy
+    def get(self, *, default: _TValue) -> _TValue:
+        """
+        Retrieve the contents of the box, or return the default value if the box has not been
+        created.
+
+        :arg default: The default value to return if the box has not been created
+        """
+        box_content, box_exists = self.maybe()
+        return default if not box_exists else box_content
 
+    def maybe(self) -> tuple[_TValue, bool]:
+        """
+        Retrieve the contents of the box if it exists, and return a boolean indicating if the box
+        exists.
+
+        """
         context = get_test_context()
-        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
-        box_content = context.get_box(name_bytes)
-        return box_content, bool(box_content)
+        box_exists = context.does_box_exist(self.key)
+        box_content_bytes = context.get_box(self.key)
+        box_content = _cast_to_value_type(self._type, box_content_bytes)
+        return box_content, box_exists
 
-    @staticmethod
-    def length(a: algopy.Bytes | bytes, /) -> tuple[algopy.UInt64, bool]:
+    @property
+    def length(self) -> algopy.UInt64:
+        """
+        Get the length of this Box. Fails if the box does not exist
+        """
         import algopy
 
         context = get_test_context()
-        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
-        box_content = context.get_box(name_bytes)
-        return algopy.UInt64(len(box_content)), bool(box_content)
+        if not context.does_box_exist(self.key):
+            raise RuntimeError("Box has not been created")
+        return algopy.UInt64(len(context.get_box(self.key)))
+
 
-    @staticmethod
-    def put(a: algopy.Bytes | bytes, b: algopy.Bytes | bytes, /) -> None:
+class BoxRef:
+    """
+    BoxRef abstracts the reading and writing of boxes containing raw binary data. The size is
+    configured manually, and can be set to values larger than what the AVM can handle in a single
+    value.
+    """
+
+    def __init__(self, /, *, key: bytes | str | algopy.Bytes | algopy.String = "") -> None:
         import algopy
 
+        self._key = (
+            algopy.String(as_string(key)).bytes
+            if isinstance(key, str | algopy.String)
+            else algopy.Bytes(as_bytes(key))
+        )
+
+    def __bool__(self) -> bool:
+        """Returns True if the box has a value set, regardless of the truthiness of that value"""
         context = get_test_context()
-        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
-        content = b.value if isinstance(b, algopy.Bytes) else b
-        existing_content = context.get_box(name_bytes)
-        if existing_content and len(existing_content) != len(content):
-            raise ValueError("New content length does not match existing box length")
-        context.set_box(name_bytes, content)
+        return context.does_box_exist(self.key)
 
-    @staticmethod
-    def replace(
-        a: algopy.Bytes | bytes, b: algopy.UInt64 | int, c: algopy.Bytes | bytes, /
-    ) -> None:
-        import algopy
+    @property
+    def key(self) -> algopy.Bytes:
+        """Provides access to the raw storage key"""
+        if not self._key:
+            raise RuntimeError("Box key is empty")
+
+        return self._key
+
+    def create(self, *, size: algopy.UInt64 | int) -> bool:
+        """
+        Creates a box with the specified size, setting all bits to zero. Fails if the box already
+        exists with a different size. Fails if the specified size is greater than the max box size
+        (32,768)
+
+        Returns True if the box was created, False if the box already existed
+        """
+        size_int = int(size)
+        if size_int > MAX_BOX_SIZE:
+            raise ValueError(f"Box size cannot exceed {MAX_BOX_SIZE}")
+
+        box_content, box_exists = self._maybe()
+        if box_exists and len(box_content) != size_int:
+            raise ValueError("Box already exists with a different size")
+        if box_exists:
+            return False
+        context = get_test_context()
+        context.set_box(self.key, b"\x00" * size_int)
+        return True
 
+    def delete(self) -> bool:
+        """
+        Deletes the box if it exists and returns a value indicating if the box existed
+        """
         context = get_test_context()
-        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
-        start = int(b)
-        new_content = c.value if isinstance(c, algopy.Bytes) else c
-        box_content = context.get_box(name_bytes)
-        if not box_content:
-            raise ValueError("Box does not exist")
-        if start + len(new_content) > len(box_content):
-            raise ValueError("Replacement content exceeds box size")
-        updated_content = (
-            box_content[:start] + new_content + box_content[start + len(new_content) :]
-        )
-        context.set_box(name_bytes, updated_content)
+        return context.clear_box(self.key)
 
-    @staticmethod
-    def resize(a: algopy.Bytes | bytes, b: algopy.UInt64 | int, /) -> None:
+    def extract(
+        self, start_index: algopy.UInt64 | int, length: algopy.UInt64 | int
+    ) -> algopy.Bytes:
+        """
+        Extract a slice of bytes from the box.
+
+        Fails if the box does not exist, or if `start_index + length > len(box)`
+
+        :arg start_index: The offset to start extracting bytes from
+        :arg length: The number of bytes to extract
+        """
         import algopy
 
+        box_content, box_exists = self._maybe()
+        start_int = int(start_index)
+        length_int = int(length)
+        if not box_exists:
+            raise RuntimeError("Box has not been created")
+        if (start_int + length_int) > len(box_content):
+            raise ValueError("Index out of bounds")
+        result = box_content[start_int : start_int + length_int]
+        return algopy.Bytes(result)
+
+    def resize(self, new_size: algopy.UInt64 | int) -> None:
+        """
+        Resizes the box the specified `new_size`. Truncating existing data if the new value is
+        shorter or padding with zero bytes if it is longer.
+
+        :arg new_size: The new size of the box
+        """
         context = get_test_context()
-        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
-        new_size = int(b)
-        if not name_bytes or new_size > 32768:
-            raise ValueError("Invalid box name or size")
-        box_content = context.get_box(name_bytes)
-        if not box_content:
-            raise ValueError("Box does not exist")
-        if new_size > len(box_content):
-            updated_content = box_content + b"\x00" * (new_size - len(box_content))
+        new_size_int = int(new_size)
+
+        if new_size_int > MAX_BOX_SIZE:
+            raise ValueError(f"Box size cannot exceed {MAX_BOX_SIZE}")
+        box_content, box_exists = self._maybe()
+        if not box_exists:
+            raise RuntimeError("Box has not been created")
+        if new_size_int > len(box_content):
+            updated_content = box_content + b"\x00" * (new_size_int - len(box_content))
         else:
-            updated_content = box_content[:new_size]
-        context.set_box(name_bytes, updated_content)
+            updated_content = box_content[:new_size_int]
+        context.set_box(self.key, updated_content)
+
+    def replace(self, start_index: algopy.UInt64 | int, value: algopy.Bytes | bytes) -> None:
+        """
+        Write `value` to the box starting at `start_index`. Fails if the box does not exist,
+        or if `start_index + len(value) > len(box)`
+
+        :arg start_index: The offset to start writing bytes from
+        :arg value: The bytes to be written
+        """
+        context = get_test_context()
+        box_content, box_exists = self._maybe()
+        if not box_exists:
+            raise RuntimeError("Box has not been created")
+        start = int(start_index)
+        length = len(value)
+        if (start + length) > len(box_content):
+            raise ValueError("Replacement content exceeds box size")
+        updated_content = box_content[:start] + value + box_content[start + length :]
+        context.set_box(self.key, updated_content)
 
-    @staticmethod
     def splice(
-        a: algopy.Bytes | bytes,
-        b: algopy.UInt64 | int,
-        c: algopy.UInt64 | int,
-        d: algopy.Bytes | bytes,
-        /,
+        self,
+        start_index: algopy.UInt64 | int,
+        length: algopy.UInt64 | int,
+        value: algopy.Bytes | bytes,
     ) -> None:
+        """
+        set box to contain its previous bytes up to index `start_index`, followed by `bytes`,
+        followed by the original bytes of the box that began at index `start_index + length`
+
+        **Important: This op does not resize the box**
+        If the new value is longer than the box size, it will be truncated.
+        If the new value is shorter than the box size, it will be padded with zero bytes
+
+        :arg start_index: The index to start inserting `value`
+        :arg length: The number of bytes after `start_index` to omit from the new value
+        :arg value: The `value` to be inserted.
+        """
         import algopy
 
         context = get_test_context()
-        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
-        start = int(b)
-        delete_count = int(c)
-        insert_content = d.value if isinstance(d, algopy.Bytes) else d
-        box_content = context.get_box(name_bytes)
+        box_content, box_exists = self._maybe()
+
+        start = int(start_index)
+        delete_count = int(length)
+        insert_content = value.value if isinstance(value, algopy.Bytes) else value
 
-        if not box_content:
-            raise ValueError("Box does not exist")
+        if not box_exists:
+            raise RuntimeError("Box has not been created")
 
         if start > len(box_content):
             raise ValueError("Start index exceeds box size")
@@ -155,4 +272,249 @@ class Box:
             new_content += b"\x00" * (len(box_content) - len(new_content))
 
         # Update the box with the new content
-        context.set_box(name_bytes, new_content)
+        context.set_box(self.key, new_content)
+
+    def get(self, *, default: algopy.Bytes | bytes) -> algopy.Bytes:
+        """
+        Retrieve the contents of the box, or return the default value if the box has not been
+        created.
+
+        :arg default: The default value to return if the box has not been created
+        """
+        import algopy
+
+        box_content, box_exists = self._maybe()
+        default_bytes = default if isinstance(default, algopy.Bytes) else algopy.Bytes(default)
+        return default_bytes if not box_exists else algopy.Bytes(box_content)
+
+    def put(self, value: algopy.Bytes | bytes) -> None:
+        """
+        Replaces the contents of box with value. Fails if box exists and len(box) != len(value).
+        Creates box if it does not exist
+
+        :arg value: The value to write to the box
+        """
+        import algopy
+
+        box_content, box_exists = self._maybe()
+        if box_exists and len(box_content) != len(value):
+            raise ValueError("Box already exists with a different size")
+
+        context = get_test_context()
+        content = value if isinstance(value, algopy.Bytes) else algopy.Bytes(value)
+        context.set_box(self.key, content)
+
+    def maybe(self) -> tuple[algopy.Bytes, bool]:
+        """
+        Retrieve the contents of the box if it exists, and return a boolean indicating if the box
+        exists.
+        """
+        import algopy
+
+        box_content, box_exists = self._maybe()
+        return algopy.Bytes(box_content), box_exists
+
+    def _maybe(self) -> tuple[bytes, bool]:
+        context = get_test_context()
+        box_exists = context.does_box_exist(self.key)
+        box_content = context.get_box(self.key)
+        return box_content, box_exists
+
+    @property
+    def length(self) -> algopy.UInt64:
+        """
+        Get the length of this Box. Fails if the box does not exist
+        """
+        import algopy
+
+        box_content, box_exists = self._maybe()
+        if not box_exists:
+            raise RuntimeError("Box has not been created")
+        return algopy.UInt64(len(box_content))
+
+
+class BoxMap(typing.Generic[_TKey, _TValue]):
+    """
+    BoxMap abstracts the reading and writing of a set of boxes using a common key and content type.
+    Each composite key (prefix + key) still needs to be made available to the application via the
+    `boxes` property of the Transaction.
+    """
+
+    def __init__(
+        self,
+        key_type: type[_TKey],
+        value_type: type[_TValue],
+        /,
+        *,
+        key_prefix: bytes | str | algopy.Bytes | algopy.String = "",
+    ) -> None:
+        """Declare a box map.
+
+        :arg key_type: The type of the keys
+        :arg value_type: The type of the values
+        :arg key_prefix: The value used as a prefix to key data, can be empty.
+                         When the BoxMap is being assigned to a member variable,
+                         this argument is optional and defaults to the member variable name,
+                         and if a custom value is supplied it must be static.
+        """
+        import algopy
+
+        self._key_type = key_type
+        self._value_type = value_type
+        self._key_prefix = (
+            algopy.String(as_string(key_prefix)).bytes
+            if isinstance(key_prefix, str | algopy.String)
+            else algopy.Bytes(as_bytes(key_prefix))
+        )
+
+    @property
+    def key_prefix(self) -> algopy.Bytes:
+        """Provides access to the raw storage key-prefix"""
+        if not self._key_prefix:
+            raise RuntimeError("Box key prefix is empty")
+        return self._key_prefix
+
+    def __getitem__(self, key: _TKey) -> _TValue:
+        """
+        Retrieve the contents of a keyed box. Fails if the box for the key has not been created.
+        """
+        box_content, box_exists = self.maybe(key)
+        if not box_exists:
+            raise RuntimeError("Box has not been created")
+        return box_content
+
+    def __setitem__(self, key: _TKey, value: _TValue) -> None:
+        """Write _value_ to a keyed box. Creates the box if it does not exist"""
+        context = get_test_context()
+        key_bytes = self._full_key(key)
+        bytes_value = _cast_to_bytes(value)
+        context.set_box(key_bytes, bytes_value)
+
+    def __delitem__(self, key: _TKey) -> None:
+        """Deletes a keyed box"""
+        context = get_test_context()
+        key_bytes = self._full_key(key)
+        context.clear_box(key_bytes)
+
+    def __contains__(self, key: _TKey) -> bool:
+        """
+        Returns True if a box with the specified key exists in the map, regardless of the
+        truthiness of the contents of the box
+        """
+        context = get_test_context()
+        key_bytes = self._full_key(key)
+        return context.does_box_exist(key_bytes)
+
+    def get(self, key: _TKey, *, default: _TValue) -> _TValue:
+        """
+        Retrieve the contents of a keyed box, or return the default value if the box has not been
+        created.
+
+        :arg key: The key of the box to get
+        :arg default: The default value to return if the box has not been created.
+        """
+        box_content, box_exists = self.maybe(key)
+        return default if not box_exists else box_content
+
+    def maybe(self, key: _TKey) -> tuple[_TValue, bool]:
+        """
+        Retrieve the contents of a keyed box if it exists, and return a boolean indicating if the
+        box exists.
+
+        :arg key: The key of the box to get
+        """
+        context = get_test_context()
+        key_bytes = self._full_key(key)
+        box_exists = context.does_box_exist(key_bytes)
+        box_content_bytes = context.get_box(key_bytes)
+        box_content = _cast_to_value_type(self._value_type, box_content_bytes)
+        return box_content, box_exists
+
+    def length(self, key: _TKey) -> algopy.UInt64:
+        """
+        Get the length of an item in this BoxMap. Fails if the box does not exist
+
+        :arg key: The key of the box to get
+        """
+        import algopy
+
+        context = get_test_context()
+        key_bytes = self._full_key(key)
+        box_exists = context.does_box_exist(key_bytes)
+        if not box_exists:
+            raise RuntimeError("Box has not been created")
+        box_content_bytes = context.get_box(key_bytes)
+        return algopy.UInt64(len(box_content_bytes))
+
+    def _full_key(self, key: _TKey) -> algopy.Bytes:
+        return self.key_prefix + _cast_to_bytes(key)
+
+
+def _cast_to_value_type(t: type[_TValue], value: bytes) -> _TValue:  # noqa: PLR0911
+    """
+    assuming _TValue to be one of the followings:
+        - bool,
+        - algopy.Bytes,
+        - algopy.UInt64
+        - algopy.Asset,
+        - algopy.Application,
+        - algopy.UInt64 enums
+        - algopy.arc4.Struct
+        - algopy_testing.BytesBacked
+            - any type with `from_bytes` class method and `bytes` property
+            - .e.g algopy.String, algopy.Address, algopy.arc4.DynamicArray etc.
+    """
+    import algopy
+
+    context = get_test_context()
+
+    if t is bool:
+        return algopy.op.btoi(value) == 1  # type: ignore[return-value]
+    elif t is algopy.Bytes:
+        return algopy.Bytes(value)  # type: ignore[return-value]
+    elif t is algopy.UInt64:
+        return algopy.op.btoi(value)  # type: ignore[return-value]
+    elif t is algopy.OnCompleteAction:
+        return algopy.OnCompleteAction(algopy.op.btoi(value).value)  # type: ignore[return-value]
+    elif t is algopy.TransactionType:
+        return algopy.TransactionType(algopy.op.btoi(value).value)  # type: ignore[return-value]
+    elif t is algopy.Asset:
+        asset_id = algopy.op.btoi(value)
+        return context.get_asset(asset_id)  # type: ignore[return-value]
+    elif t is algopy.Application:
+        application_id = algopy.op.btoi(value)
+        return context.get_application(application_id)  # type: ignore[return-value]
+    elif hasattr(t, "from_bytes"):
+        return t.from_bytes(value)  # type: ignore[attr-defined, no-any-return]
+
+    raise ValueError(f"Unsupported type: {t}")
+
+
+def _cast_to_bytes(value: _TValue) -> algopy.Bytes:
+    """
+    assuming _TValue to be one of the followings:
+        - bool,
+        - algopy.Bytes,
+        - algopy.UInt64
+        - algopy.Asset,
+        - algopy.Application,
+        - algopy.UInt64 enums
+        - algopy.arc4.Struct
+        - algopy_testing.BytesBacked
+            - any type with `from_bytes` class method and `bytes` property
+            - .e.g algopy.String, algopy.Address, algopy.arc4.DynamicArray etc.
+    """
+    import algopy
+
+    if isinstance(value, bool):
+        return algopy.op.itob(1 if value else 0)
+    elif isinstance(value, algopy.Bytes):
+        return value
+    elif isinstance(value, algopy.UInt64):
+        return algopy.op.itob(value)
+    elif isinstance(value, algopy.Asset | algopy.Application):
+        return algopy.op.itob(value.id)
+    elif hasattr(value, "bytes"):
+        return typing.cast(algopy.Bytes, value.bytes)
+
+    raise ValueError(f"Unsupported type: {type(value)}")

algopy_testing/models/contract.py

@@ -69,6 +69,18 @@ class Contract(metaclass=_ContractMeta):
             return wrapper
         return attr
 
+    def __setattr__(self, name: str, value: Any) -> None:
+        import algopy
+
+        name_bytes = algopy.String(name).bytes
+        match value:
+            case algopy.Box() | algopy.BoxRef() | algopy.GlobalState() | algopy.LocalState():
+                value._key = name_bytes
+            case algopy.BoxMap():
+                value._key_prefix = name_bytes
+
+        super().__setattr__(name, value)
+
 
 class ARC4Contract(Contract):
     @final

algopy_testing/op.py

@@ -22,12 +22,13 @@ from ecdsa import (  # type: ignore  # noqa: PGH003
 from algopy_testing.constants import (
     BITS_IN_BYTE,
     DEFAULT_ACCOUNT_MIN_BALANCE,
+    MAX_BOX_SIZE,
     MAX_BYTES_SIZE,
     MAX_UINT64,
 )
+from algopy_testing.context import get_test_context
 from algopy_testing.enums import EC, ECDSA, Base64, VrfVerify
 from algopy_testing.models.block import Block
-from algopy_testing.models.box import Box
 from algopy_testing.models.gitxn import GITxn
 from algopy_testing.models.global_values import Global
 from algopy_testing.models.gtxn import GTxn
@@ -1023,6 +1024,160 @@ class _EllipticCurve:
 
 EllipticCurve = _EllipticCurve()
 
+
+class Box:
+    @staticmethod
+    def create(a: algopy.Bytes | bytes, b: algopy.UInt64 | int, /) -> bool:
+        import algopy
+
+        context = get_test_context()
+        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
+        size = int(b)
+        if not name_bytes or size > MAX_BOX_SIZE:
+            raise ValueError("Invalid box name or size")
+        if context.get_box(name_bytes):
+            return False
+        context.set_box(name_bytes, b"\x00" * size)
+        return True
+
+    @staticmethod
+    def delete(a: algopy.Bytes | bytes, /) -> bool:
+        import algopy
+
+        context = get_test_context()
+        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
+        if context.get_box(name_bytes):
+            context.clear_box(name_bytes)
+            return True
+        return False
+
+    @staticmethod
+    def extract(
+        a: algopy.Bytes | bytes, b: algopy.UInt64 | int, c: algopy.UInt64 | int, /
+    ) -> algopy.Bytes:
+        import algopy
+
+        context = get_test_context()
+        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
+        start = int(b)
+        length = int(c)
+        box_content = context.get_box(name_bytes)
+        if not box_content:
+            raise RuntimeError("Box does not exist")
+        result = box_content[start : start + length]
+        return algopy.Bytes(result)
+
+    @staticmethod
+    def get(a: algopy.Bytes | bytes, /) -> tuple[algopy.Bytes, bool]:
+        import algopy
+
+        context = get_test_context()
+        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
+        box_content = algopy.Bytes(context.get_box(name_bytes))
+        box_exists = context.does_box_exist(name_bytes)
+        return box_content, box_exists
+
+    @staticmethod
+    def length(a: algopy.Bytes | bytes, /) -> tuple[algopy.UInt64, bool]:
+        import algopy
+
+        context = get_test_context()
+        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
+        box_content = context.get_box(name_bytes)
+        box_exists = context.does_box_exist(name_bytes)
+        return algopy.UInt64(len(box_content)), box_exists
+
+    @staticmethod
+    def put(a: algopy.Bytes | bytes, b: algopy.Bytes | bytes, /) -> None:
+        import algopy
+
+        context = get_test_context()
+        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
+        content = b.value if isinstance(b, algopy.Bytes) else b
+        existing_content = context.get_box(name_bytes)
+        if existing_content and len(existing_content) != len(content):
+            raise ValueError("New content length does not match existing box length")
+        context.set_box(name_bytes, algopy.Bytes(content))
+
+    @staticmethod
+    def replace(
+        a: algopy.Bytes | bytes, b: algopy.UInt64 | int, c: algopy.Bytes | bytes, /
+    ) -> None:
+        import algopy
+
+        context = get_test_context()
+        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
+        start = int(b)
+        new_content = c.value if isinstance(c, algopy.Bytes) else c
+        box_content = context.get_box(name_bytes)
+        if not box_content:
+            raise RuntimeError("Box does not exist")
+        if start + len(new_content) > len(box_content):
+            raise ValueError("Replacement content exceeds box size")
+        updated_content = (
+            box_content[:start] + new_content + box_content[start + len(new_content) :]
+        )
+        context.set_box(name_bytes, updated_content)
+
+    @staticmethod
+    def resize(a: algopy.Bytes | bytes, b: algopy.UInt64 | int, /) -> None:
+        import algopy
+
+        context = get_test_context()
+        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
+        new_size = int(b)
+        if not name_bytes or new_size > MAX_BOX_SIZE:
+            raise ValueError("Invalid box name or size")
+        box_content = context.get_box(name_bytes)
+        if not box_content:
+            raise RuntimeError("Box does not exist")
+        if new_size > len(box_content):
+            updated_content = box_content + b"\x00" * (new_size - len(box_content))
+        else:
+            updated_content = box_content[:new_size]
+        context.set_box(name_bytes, updated_content)
+
+    @staticmethod
+    def splice(
+        a: algopy.Bytes | bytes,
+        b: algopy.UInt64 | int,
+        c: algopy.UInt64 | int,
+        d: algopy.Bytes | bytes,
+        /,
+    ) -> None:
+        import algopy
+
+        context = get_test_context()
+        name_bytes = a.value if isinstance(a, algopy.Bytes) else a
+        start = int(b)
+        delete_count = int(c)
+        insert_content = d.value if isinstance(d, algopy.Bytes) else d
+        box_content = context.get_box(name_bytes)
+
+        if not box_content:
+            raise RuntimeError("Box does not exist")
+
+        if start > len(box_content):
+            raise ValueError("Start index exceeds box size")
+
+        # Calculate the end index for deletion
+        end = min(start + delete_count, len(box_content))
+
+        # Construct the new content
+        new_content = box_content[:start] + insert_content + box_content[end:]
+
+        # Adjust the size if necessary
+        if len(new_content) > len(box_content):
+            # Truncate if the new content is too long
+            new_content = new_content[: len(box_content)]
+        elif len(new_content) < len(box_content):
+            # Pad with zeros if the new content is too short
+            new_content += b"\x00" * (len(box_content) - len(new_content))
+
+        # Update the box with the new content
+        context.set_box(name_bytes, new_content)
+
+
 __all__ = [
     "AcctParamsGet",
     "AppGlobal",

algopy_testing/state/global_state.py

@@ -3,6 +3,9 @@ from __future__ import annotations
 import typing
 from typing import cast, overload
 
+if typing.TYPE_CHECKING:
+    import algopy
+
 _T = typing.TypeVar("_T")
 
 
@@ -35,6 +38,8 @@ class GlobalState(typing.Generic[_T]):
         key: bytes | str = "",
         description: str = "",
     ) -> None:
+        import algopy
+
         if isinstance(type_or_value, type):
             self.type_ = type_or_value
             self._value: _T | None = None
@@ -42,9 +47,21 @@ class GlobalState(typing.Generic[_T]):
             self.type_ = type(type_or_value)
             self._value = type_or_value
 
-        self.key = key
+        match key:
+            case bytes(key):
+                self._key = algopy.Bytes(key)
+            case str(key):
+                self._key = algopy.String(key).bytes
+            case _:
+                raise ValueError("Key must be bytes or str")
+
         self.description = description
 
+    @property
+    def key(self) -> algopy.Bytes:
+        """Provides access to the raw storage key"""
+        return self._key
+
     @property
     def value(self) -> _T:
         if self._value is None:

algopy_testing/state/local_state.py

@@ -18,11 +18,24 @@ class LocalState(typing.Generic[_T]):
         key: bytes | str = "",
         description: str = "",
     ) -> None:
+        import algopy
+
         self.type_ = type_
-        self.key = key
+        match key:
+            case bytes(key):
+                self._key = algopy.Bytes(key)
+            case str(key):
+                self._key = algopy.String(key).bytes
+            case _:
+                raise ValueError("Key must be bytes or str")
         self.description = description
         self._state: dict[object, _T] = {}
 
+    @property
+    def key(self) -> algopy.Bytes:
+        """Provides access to the raw storage key"""
+        return self._key
+
     def _validate_local_state_key(self, key: algopy.Account | algopy.UInt64 | int) -> None:
         from algopy import Account, UInt64
 

algopy_testing/utilities/__init__.py

@@ -1,3 +1,4 @@
 from algopy_testing.utilities.budget import OpUpFeeSource, ensure_budget
+from algopy_testing.utilities.log import log
 
 __all__ = ["OpUpFeeSource", "ensure_budget", "log"]

{algorand_python_testing-0.2.1.dist-info → algorand_python_testing-0.2.2b2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: algorand-python-testing
-Version: 0.2.1
+Version: 0.2.2b2
 Summary: Algorand Python testing library
 Project-URL: Documentation, https://github.com/algorandfoundation/puya/tree/main/algopy_testing#README.md
 Project-URL: Issues, https://github.com/algorandfoundation/puya/issues
@@ -14,14 +14,25 @@ Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Testing
 Requires-Python: >=3.12
+Requires-Dist: algorand-python>=1.2
 Requires-Dist: coincurve>=19.0.1
 Requires-Dist: ecdsa>=0.17.0
 Requires-Dist: pycryptodomex<4,>=3.6.0
 Requires-Dist: pynacl<2,>=1.4.0
-Requires-Dist: algorand-python>=1,<1.3.0
 Description-Content-Type: text/markdown
 
-# Algorand Python Testing
+<div align="center">
+<a href="https://github.com/algorandfoundation/algorand-python-testing"><img src="https://bafybeiaibjaf6zy6hvef2rrysaacsfsyb3hw4qqtgn657gw7k5tdzqdxzi.ipfs.nftstorage.link/" width=60%></a>
+</div>
+
+<p align="center">
+    <a target="_blank" href="https://algorandfoundation.github.io/algorand-python-testing/"><img src="https://img.shields.io/badge/docs-repository-74dfdc?logo=github&style=flat.svg" /></a>
+    <a target="_blank" href="https://developer.algorand.org/algokit/"><img src="https://img.shields.io/badge/learn-AlgoKit-74dfdc?logo=algorand&mac=flat.svg" /></a>
+    <a target="_blank" href="https://github.com/algorandfoundation/algorand-python-testing"><img src="https://img.shields.io/github/stars/algorandfoundation/algorand-python-testing?color=74dfdc&logo=star&style=flat" /></a>
+    <a target="_blank" href="https://developer.algorand.org/algokit/"><img  src="https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fgithub.com%2Falgorandfoundation%2Falgorand-python-testing&countColor=%2374dfdc&style=flat" /></a>
+</p>
+
+---
 
 Algorand Python Testing is a companion package to [Algorand Python](https://github.com/algorandfoundation/puya) that enables efficient unit testing of Algorand Python smart contracts in an offline environment. It emulates key AVM behaviors without requiring a network connection, offering fast and reliable testing capabilities with a familiar Pythonic interface.
 

{algorand_python_testing-0.2.1.dist-info → algorand_python_testing-0.2.2b2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-algopy/__init__.py,sha256=nd5hpdHpkfb5srMM6vHKfbOmEIxTutr4Dh0b7wwFq8Y,1143
+algopy/__init__.py,sha256=aAz8sf_DjKyyEAhpMQNGs-l4NCVROrZgKblsqWIqs7A,1273
 algopy/arc4.py,sha256=zE-cwwmeEBA0m22QiHIujeY0S5rdyf3gDqTyGgROAqI,48
 algopy/gtxn.py,sha256=tS2waKIr3g79T1xcmE2iVcvu524xANsR8awXduUVoT0,48
 algopy/itxn.py,sha256=gXida1ee8xMfRufZ24G4xPGGSe26Iwm9nqfHpQCxbpE,48
@@ -7,11 +7,11 @@ algopy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 algopy_testing/__init__.py,sha256=x7WpDet7utqy6M9MdE5OJeKLqNd1uAIPg_U2ZpDOenI,1150
 algopy_testing/arc4.py,sha256=3rCZGKs4-mH3SymHOrp190edGS9MV_v3L5oP_5_GBsA,52015
 algopy_testing/constants.py,sha256=L1-Vod3_k6NAmeHJ9d8qIIovSMlakudvd4VeR6BjPeo,733
-algopy_testing/context.py,sha256=TswTYyLMw1_novoEnoLoIIGrkN-c2xBCWoWFW7AOvs8,39371
-algopy_testing/enums.py,sha256=MJE7g_5wiI94a5oAaEdPGGaO7QS1wm5GgZlYtADwB1U,690
+algopy_testing/context.py,sha256=BFcMfIZvpO4n2LXr1n3chc5vN30qoPfPuBaYNQDFjUw,39570
+algopy_testing/enums.py,sha256=6ed2GvC-yRw6cYS06uwkgbFbfQ1C1H2qDqkWXgwul5g,1531
 algopy_testing/gtxn.py,sha256=ul1iBYt8Kwc9Xob_pWVwa6dj9ueQ0iIz2DHkC72Aga4,7954
 algopy_testing/itxn.py,sha256=lLz6dPBwTSvU5zmuKPQd0LkCLG1VJN2Q8Dmb6HRNb3s,23363
-algopy_testing/op.py,sha256=e_VY3pvgUuW_y64yolzzuxeN2Gpg4XkDcJM5fNK-iOg,33046
+algopy_testing/op.py,sha256=2Z9GETVphRAe4kRWRbS1L77yEhKTmN55dqfXVoqMEfU,38650
 algopy_testing/protocols.py,sha256=fPvuYAWKVVYM8oZE9hJtmRKW24Ba8VSzrBGz-7mDnIw,448
 algopy_testing/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 algopy_testing/utils.py,sha256=PkDkHPAKJxyq6Jc0kWSVhF9MtIyNZmNv-hY2bPtwQ40,8393
@@ -24,8 +24,8 @@ algopy_testing/models/account.py,sha256=vR_furAVjNGkT1x8vJ8BQeOuCyjg3Cwc1pIGUkwX
 algopy_testing/models/application.py,sha256=leMvgKkYt7Kct4ayUwkL7rQy65mpqp52oGnuoNO-1xA,2203
 algopy_testing/models/asset.py,sha256=qsvC7vGDKTH_PHqybc0SAgzPLAjPgzgwK0aDliUxoLk,3471
 algopy_testing/models/block.py,sha256=JwzoQ3Z7EIvOaSjbMlzQTQ7DztYejw43rQeRptolADs,876
-algopy_testing/models/box.py,sha256=CJrj9v0SwoJztyMVbe0Xu9ZHsAhWUdurAXjWo9lped8,5548
-algopy_testing/models/contract.py,sha256=9TwDC-5Ncxor2wn4_EVQ8ku6RpRkTNDTeuU64RKAmP0,2307
+algopy_testing/models/box.py,sha256=cJrKHtwBs0EVvnfAHEZylmbywrg-Vx_-uVaQAsfIxP0,18820
+algopy_testing/models/contract.py,sha256=jNFWwa_wxhpTJwP4LKQDLEA7wQWxlK8xfVu-uxFccQE,2714
 algopy_testing/models/gitxn.py,sha256=MEWkVoK81Hoqz6Bb7uFAuGCZTb_G5lH9Vl1Dx_2nO7w,1594
 algopy_testing/models/global_values.py,sha256=cT5JKbcSY2_VenF6Pn3BkSj_iaV2D5o4uJZYyKXs2xQ,2215
 algopy_testing/models/gtxn.py,sha256=RJCwFyJvIbxwbF27RpWJaS04x7ZACKr1IPP3iXRS6Rk,1993
@@ -41,12 +41,12 @@ algopy_testing/primitives/bytes.py,sha256=TI-M5hA4NNTdiNwZg_70EH08VFHOW0f9Wm7RwV
 algopy_testing/primitives/string.py,sha256=7eWrbFxu74nQ7ZdDg6GVsZ73VF_p24os7SnIoXKZuFk,2189
 algopy_testing/primitives/uint64.py,sha256=-vQHLYza-K7Y_Pms-49pQQ44B78CNLEYBb6X6Ny-G6c,7110
 algopy_testing/state/__init__.py,sha256=uRFuGSn7RMnhjVKWWdHnVtPNhNfTlQIoQaDPbcmkr3U,155
-algopy_testing/state/global_state.py,sha256=1eJRY9SYzOdj_dnNUqF_vghh0t9Q6N1B1MzLX0hKPxU,1662
-algopy_testing/state/local_state.py,sha256=7m98XD5Afbn72yvgw9Q_VLAEhObLBv_5trp11ZkGwuE,1788
-algopy_testing/utilities/__init__.py,sha256=y43zYxwO37xO9CodAENU9y5p6DBVrkDOHnoZZO77nxc,126
+algopy_testing/state/global_state.py,sha256=Kp_Utr2YLQmMYL_Y-94gp5EIhxephbqKUWDaZEGnGBA,2090
+algopy_testing/state/local_state.py,sha256=8dtmyIQXKyonLRHxNykAFqmcodTn30QEGt1PR-eJjVM,2171
+algopy_testing/utilities/__init__.py,sha256=juZqPBATNsIUYDvZJf2KSVwt21anHloc4bgI5KWfLFg,171
 algopy_testing/utilities/budget.py,sha256=P1pOKWCyya4wsqAwKgvp7y0p97hn2Kr2qFVRKm-sJZo,540
 algopy_testing/utilities/log.py,sha256=5MDJY8Oh_COt5OLZXWqkvAJk2qdfBpfSGIpidV-HJ4k,1870
-algorand_python_testing-0.2.1.dist-info/METADATA,sha256=Pw-Gf-qZuEf-8xHrleA8MGA8eKcJWa4l4yIEmiGf79M,3139
-algorand_python_testing-0.2.1.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
-algorand_python_testing-0.2.1.dist-info/licenses/LICENSE,sha256=jRyAzzkz3HPr-knS8XWyDY8CyuU-L4RtydPP8uGWsUw,657
-algorand_python_testing-0.2.1.dist-info/RECORD,,
+algorand_python_testing-0.2.2b2.dist-info/METADATA,sha256=YUTScpM6LeXfKQfMhFCiExhIp0WNJATWO653RTQMQMY,4172
+algorand_python_testing-0.2.2b2.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+algorand_python_testing-0.2.2b2.dist-info/licenses/LICENSE,sha256=jRyAzzkz3HPr-knS8XWyDY8CyuU-L4RtydPP8uGWsUw,657
+algorand_python_testing-0.2.2b2.dist-info/RECORD,,