Merge pull request #55 from algorandfoundation/feat/fixed-bytes

feat: add fixed size variant of bytes as a separate `FixedBytes` type

Author: boblat

docs/coverage.md

@@ -3,7 +3,7 @@
 See which `algorand-python` stubs are implemented by the `algorand-python-testing` library. See the [Concepts](testing-guide/concepts.md#types-of-algopy-stub-implementations) section for more details on the implementation categories. Refer to the [`algorand-python` stubs API](api.md) for the full list of stubs for which the `algorand-python-testing` library provides implementations referenced in the table below.
 
 | Name                                        | Implementation type |
-|---------------------------------------------|---------------------|
+| ------------------------------------------- | ------------------- |
 | algopy.Account                              | Emulated            |
 | algopy.Application                          | Emulated            |
 | algopy.Asset                                | Emulated            |
@@ -18,6 +18,7 @@ See which `algorand-python` stubs are implemented by the `algorand-python-testin
 | algopy.CompiledLogicSig                     | Mockable            |
 | algopy.Contract                             | Emulated            |
 | algopy.FixedArray                           | Native              |
+| algopy.FixedBytes                           | Native              |
 | algopy.Global                               | Emulated            |
 | algopy.GlobalState                          | Emulated            |
 | algopy.ImmutableArray                       | Native              |

docs/testing-guide/avm-types.md

@@ -50,6 +50,22 @@ random_bytes = context.any.bytes()
 random_bytes = context.any.bytes(length=32)
 ```
 
+## FixedBytes
+
+```{testcode}
+import typing
+
+# Direct instantiation
+bytes_value = algopy.FixedBytes[typing.Literal[16]](b"Hello, Algorand!")
+
+
+# Instantiate test context
+...
+
+# Generate random byte sequences of length 32
+random_bytes = context.any.fixed_bytes(algopy.FixedBytes[typing.Literal[32]])
+```
+
 ## String
 
 ```{testcode}

src/_algopy_testing/__init__.py

@@ -19,7 +19,7 @@
     uenumerate,
     urange,
 )
-from _algopy_testing.primitives import BigUInt, Bytes, String, UInt64
+from _algopy_testing.primitives import BigUInt, Bytes, FixedBytes, String, UInt64
 from _algopy_testing.state import Box, BoxMap, BoxRef, GlobalState, LocalState
 from _algopy_testing.value_generators.arc4 import ARC4ValueGenerator
 from _algopy_testing.value_generators.avm import AVMValueGenerator
@@ -39,6 +39,7 @@
     "BoxRef",
     "Bytes",
     "Contract",
+    "FixedBytes",
     "GlobalState",
     "ITxnGroupLoader",
     "ITxnLoader",

src/_algopy_testing/decorators/arc4.py

@@ -12,7 +12,7 @@
 from _algopy_testing.constants import ALWAYS_APPROVE_TEAL_PROGRAM, ARC4_RETURN_PREFIX
 from _algopy_testing.context_helpers import lazy_context
 from _algopy_testing.enums import OnCompleteAction
-from _algopy_testing.primitives import BigUInt, Bytes, String, UInt64
+from _algopy_testing.primitives import BigUInt, Bytes, FixedBytes, String, UInt64
 
 _P = typing.ParamSpec("_P")
 _R = typing.TypeVar("_R")
@@ -418,6 +418,8 @@ def _type_to_arc4(  # noqa: PLR0912 PLR0911
         return "uint512"
     if issubclass(annotation, Bytes):
         return "byte[]"
+    if issubclass(annotation, FixedBytes):
+        return f"byte[{annotation._length}]"
     if issubclass(annotation, bool):
         return "bool"
     raise TypeError(f"type not a valid ARC4 type: {annotation}")

src/_algopy_testing/primitives/__init__.py

@@ -9,6 +9,7 @@
 )
 from _algopy_testing.primitives.biguint import BigUInt
 from _algopy_testing.primitives.bytes import Bytes
+from _algopy_testing.primitives.fixed_bytes import FixedBytes
 from _algopy_testing.primitives.string import String
 from _algopy_testing.primitives.uint64 import UInt64
 
@@ -17,6 +18,7 @@
     "BigUInt",
     "Bytes",
     "FixedArray",
+    "FixedBytes",
     "ImmutableArray",
     "ImmutableFixedArray",
     "ReferenceArray",

src/_algopy_testing/primitives/bytes.py

@@ -7,6 +7,8 @@
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
+    from _algopy_testing.primitives.fixed_bytes import FixedBytes
+
 
 from itertools import zip_longest
 
@@ -27,7 +29,7 @@ def __init__(self, value: bytes = b"") -> None:
         check_type(value, bytes)
         self.value = as_bytes(value)
 
-    def __contains__(self, item: Bytes | bytes) -> bool:
+    def __contains__(self, item: Bytes | FixedBytes | bytes) -> bool:  # type: ignore[type-arg]
         item_bytes = as_bytes(item)
         return item_bytes in self.value
 
@@ -43,11 +45,8 @@ def __bool__(self) -> bool:
     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, "+")
+        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 " +
@@ -70,7 +69,7 @@ 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."""
+        otherwise the substring of bytes described by the slice."""
         if isinstance(index, slice):
             return Bytes(self.value[index])
         else:
@@ -181,7 +180,7 @@ 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
+        OverflowError: If `result` of `op` is out of bounds
     """
     if len(result) > MAX_BYTES_SIZE:
         raise OverflowError(f"{op} overflows")