Merge pull request #44 from algorandfoundation/feat/native-funcs

feat: add .as_uint64 and .as_biguint methods to replace native property

Author: boblat

examples/marketplace/contract.py

@@ -130,7 +130,7 @@ def deposit(self, xfer: gtxn.AssetTransferTransaction, nonce: arc4.UInt64) -> No
         assert xfer.asset_amount > 0
 
         self.listings[key].deposited = arc4.UInt64(
-            self.listings[key].deposited.native + xfer.asset_amount
+            self.listings[key].deposited.as_uint64() + xfer.asset_amount
         )
 
     @abimethod
@@ -161,14 +161,14 @@ def buy(
         listing = self.listings[key].copy()
 
         amount_to_be_paid = self.quantity_price(
-            quantity, listing.unitary_price.native, asset.decimals
+            quantity, listing.unitary_price.as_uint64(), asset.decimals
         )
 
         assert buy_pay.sender == Txn.sender
         assert buy_pay.receiver.bytes == owner.bytes
         assert buy_pay.amount == amount_to_be_paid
 
-        self.listings[key].deposited = arc4.UInt64(listing.deposited.native - quantity)
+        self.listings[key].deposited = arc4.UInt64(listing.deposited.as_uint64() - quantity)
 
         itxn.AssetTransfer(
             xfer_asset=asset,
@@ -187,8 +187,8 @@ def withdraw(self, asset: Asset, nonce: arc4.UInt64) -> None:
         listing = self.listings[key].copy()
         if listing.bidder != arc4.Address():
             current_bid_deposit = self.quantity_price(
-                listing.bid.native,
-                listing.bid_unitary_price.native,
+                listing.bid.as_uint64(),
+                listing.bid_unitary_price.as_uint64(),
                 asset.decimals,
             )
             itxn.Payment(receiver=listing.bidder.native, amount=current_bid_deposit).submit()
@@ -200,7 +200,7 @@ def withdraw(self, asset: Asset, nonce: arc4.UInt64) -> None:
         itxn.AssetTransfer(
             xfer_asset=asset,
             asset_receiver=Txn.sender,
-            asset_amount=listing.deposited.native,
+            asset_amount=listing.deposited.as_uint64(),
         ).submit()
 
     @abimethod
@@ -220,13 +220,13 @@ def bid(  # noqa: PLR0913
             assert unitary_price > listing.bid_unitary_price
 
             current_bid_amount = self.quantity_price(
-                listing.bid.native, listing.bid_unitary_price.native, asset.decimals
+                listing.bid.as_uint64(), listing.bid_unitary_price.as_uint64(), asset.decimals
             )
 
             itxn.Payment(receiver=listing.bidder.native, amount=current_bid_amount).submit()
 
         amount_to_be_bid = self.quantity_price(
-            quantity.native, unitary_price.native, asset.decimals
+            quantity.as_uint64(), unitary_price.as_uint64(), asset.decimals
         )
 
         assert bid_pay.sender == Txn.sender
@@ -245,12 +245,12 @@ def accept_bid(self, asset: Asset, nonce: arc4.UInt64) -> None:
         assert listing.bidder != arc4.Address()
 
         min_quantity = (
-            listing.deposited.native
-            if listing.deposited.native < listing.bid.native
-            else listing.bid.native
+            listing.deposited.as_uint64()
+            if listing.deposited.as_uint64() < listing.bid.as_uint64()
+            else listing.bid.as_uint64()
         )
         best_bid_amount = self.quantity_price(
-            min_quantity, listing.bid_unitary_price.native, asset.decimals
+            min_quantity, listing.bid_unitary_price.as_uint64(), asset.decimals
         )
 
         itxn.Payment(receiver=Txn.sender, amount=best_bid_amount).submit()
@@ -262,6 +262,6 @@ def accept_bid(self, asset: Asset, nonce: arc4.UInt64) -> None:
         ).submit()
 
         self.listings[key].deposited = arc4.UInt64(
-            self.listings[key].deposited.native - min_quantity
+            self.listings[key].deposited.as_uint64() - min_quantity
         )
-        self.listings[key].bid = arc4.UInt64(self.listings[key].bid.native - min_quantity)
+        self.listings[key].bid = arc4.UInt64(self.listings[key].bid.as_uint64() - min_quantity)

examples/marketplace/test_contract.py

@@ -162,19 +162,19 @@ def test_buy(
         buy_pay=context.any.txn.payment(
             receiver=context.default_sender,
             amount=contract.quantity_price(
-                quantity=test_buy_quantity.native,
-                price=test_unitary_price.native,
+                quantity=test_buy_quantity.as_uint64(),
+                price=test_unitary_price.as_uint64(),
                 asset_decimals=test_asset.decimals,
             ),
         ),
-        quantity=test_buy_quantity.native,
+        quantity=test_buy_quantity.as_uint64(),
     )
 
     # Assert
     updated_listing = ListingValue.from_bytes(
         context.ledger.get_box(contract, b"listings" + listing_key.bytes)
     )
-    assert updated_listing.deposited == initial_deposit.native - test_buy_quantity.native
+    assert updated_listing.deposited == initial_deposit.as_uint64() - test_buy_quantity.as_uint64()
     assert (
         context.txn.last_group.get_itxn_group(0).asset_transfer(0).asset_receiver
         == context.default_sender
@@ -215,7 +215,7 @@ def test_withdraw(
     asset_transfer_txn = context.txn.last_group.get_itxn_group(1).asset_transfer(0)
     assert asset_transfer_txn.xfer_asset == test_asset
     assert asset_transfer_txn.asset_receiver == test_owner.native
-    assert asset_transfer_txn.asset_amount == initial_deposit.native
+    assert asset_transfer_txn.asset_amount == initial_deposit.as_uint64()
 
 
 def test_bid(
@@ -240,12 +240,12 @@ def test_bid(
     )
 
     bidder = context.any.account()
-    bid_quantity = context.any.arc4.uint64(max_value=int(initial_deposit.native))
+    bid_quantity = context.any.arc4.uint64(max_value=int(initial_deposit.as_uint64()))
     bid_price = context.any.arc4.uint64(
-        min_value=int(initial_price.native) + 1, max_value=int(10e6)
+        min_value=int(initial_price.as_uint64()) + 1, max_value=int(10e6)
     )
     bid_amount = contract.quantity_price(
-        bid_quantity.native, bid_price.native, test_asset.decimals
+        bid_quantity.as_uint64(), bid_price.as_uint64(), test_asset.decimals
     )
 
     # Act
@@ -277,7 +277,7 @@ def test_accept_bid(
     # Arrange
     owner = context.default_sender
     initial_deposit = context.any.arc4.uint64(min_value=1, max_value=int(1e6))
-    bid_quantity = context.any.arc4.uint64(max_value=int(initial_deposit.native))
+    bid_quantity = context.any.arc4.uint64(max_value=int(initial_deposit.as_uint64()))
     bid_price = context.any.arc4.uint64(max_value=int(10e6))
     bidder = context.any.account()
 
@@ -294,10 +294,10 @@ def test_accept_bid(
         bid_unitary_price=bid_price,
     )
 
-    min_quantity = min(initial_deposit.native, bid_quantity.native)
+    min_quantity = min(initial_deposit.as_uint64(), bid_quantity.as_uint64())
     expected_payment = contract.quantity_price(
         min_quantity,
-        bid_price.native,
+        bid_price.as_uint64(),
         asset_decimals=test_asset.decimals,
     )
 
@@ -306,7 +306,7 @@ def test_accept_bid(
 
     # Assert
     updated_listing = contract.listings[listing_key]
-    assert updated_listing.deposited == initial_deposit.native - min_quantity
+    assert updated_listing.deposited == initial_deposit.as_uint64() - min_quantity
 
     assert len(context.txn.last_group.itxn_groups) == 2
 

pyproject.toml

@@ -32,7 +32,7 @@ dependencies = [
     "coincurve>=19.0.1",
     # TODO: uncomment below and remove direct git reference once puya 5.0 is released
     # "algorand-python>=3",
-    "algorand-python@git+https://github.com/algorandfoundation/[email protected].6#subdirectory=stubs",
+    "algorand-python@git+https://github.com/algorandfoundation/[email protected].7#subdirectory=stubs",
 ]
 
 [project.urls]
@@ -54,7 +54,7 @@ python = "3.12"
 dependencies = [
     # TODO: uncomment below and remove direct git reference once puya 5.0 is released
     # "puyapy>=5",
-    "puyapy@git+https://github.com/algorandfoundation/[email protected].6",
+    "puyapy@git+https://github.com/algorandfoundation/[email protected].7",
     "pytest>=7.4",
     "pytest-mock>=3.10.0",
     "pytest-xdist[psutil]>=3.3",
@@ -138,7 +138,7 @@ dependencies = [
     "algokit-utils>=3.0.0",
     # TODO: uncomment below and remove direct git reference once puya 5.0 is released
     # "puyapy>=5",
-    "puyapy@git+https://github.com/algorandfoundation/[email protected].6",
+    "puyapy@git+https://github.com/algorandfoundation/[email protected].7",
 ]
 
 [tool.hatch.envs.test.scripts]
@@ -191,7 +191,7 @@ post-install-commands = [
 dependencies = [
     # TODO: uncomment below and remove direct git reference once puya 5.0 is released
     # "algorand-python>=3",
-    "algorand-python@git+https://github.com/algorandfoundation/[email protected].6#subdirectory=stubs",
+    "algorand-python@git+https://github.com/algorandfoundation/[email protected].7#subdirectory=stubs",
     "pytest>=7.4",
     "pytest-mock>=3.10.0",
     "pytest-xdist[psutil]>=3.3",

src/_algopy_testing/arc4.py

@@ -8,6 +8,7 @@
 
 import algosdk
 from Cryptodome.Hash import SHA512
+from typing_extensions import deprecated
 
 from _algopy_testing.constants import (
     ARC4_RETURN_PREFIX,
@@ -313,31 +314,44 @@ class UIntN(_UIntN, typing.Generic[_TBitSize]):  # type: ignore[type-arg]
     """
 
     @property
+    @deprecated("Use `as_uint64` instead")
     def native(self) -> algopy.UInt64:
         """Return the UInt64 representation of the value after ARC4 decoding."""
         import algopy
 
         return algopy.UInt64(int.from_bytes(self._value))
 
+    def as_uint64(self) -> algopy.UInt64:
+        """Return the UInt64 representation of the value after ARC4 decoding."""
+        import algopy
+
+        return algopy.UInt64(int.from_bytes(self._value))
+
+    def as_biguint(self) -> algopy.BigUInt:
+        """Return the BigUInt representation of the value after ARC4 decoding."""
+        import algopy
+
+        return algopy.BigUInt.from_bytes(self._value)
+
     def __eq__(self, other: object) -> bool:
         try:
             other_int = as_int64(other)
         except (TypeError, ValueError):
             return NotImplemented
-        return as_int64(self.native) == other_int
+        return as_int64(self.as_uint64()) == other_int
 
     def __lt__(self, other: object) -> bool:
         try:
             other_int = as_int64(other)
         except (TypeError, ValueError):
             return NotImplemented
-        return as_int64(self.native) < other_int
+        return as_int64(self.as_uint64()) < other_int
 
     def __bool__(self) -> bool:
-        return bool(self.native)
+        return bool(self.as_uint64())
 
     def __str__(self) -> str:
-        return str(self.native)
+        return str(self.as_uint64())
 
     def __repr__(self) -> str:
         return _arc4_repr(self)
@@ -351,31 +365,47 @@ class BigUIntN(_UIntN, typing.Generic[_TBitSize]):  # type: ignore[type-arg]
     """
 
     @property
+    @deprecated("Use `as_biguint` instead")
     def native(self) -> algopy.BigUInt:
+        """Return the BigUInt representation of the value after ARC4 decoding."""
+        import algopy
+
+        return algopy.BigUInt.from_bytes(self._value)
+
+    def as_uint64(self) -> algopy.UInt64:
         """Return the UInt64 representation of the value after ARC4 decoding."""
         import algopy
 
+        biguint = algopy.BigUInt.from_bytes(self._value)
+        if biguint.value > MAX_UINT64:
+            raise OverflowError("value too large to fit in UInt64")
+        return algopy.UInt64(biguint.value)
+
+    def as_biguint(self) -> algopy.BigUInt:
+        """Return the BigUInt representation of the value after ARC4 decoding."""
+        import algopy
+
         return algopy.BigUInt.from_bytes(self._value)
 
     def __eq__(self, other: object) -> bool:
         try:
             other_int = as_int512(other)
         except (TypeError, ValueError):
             return NotImplemented
-        return as_int512(self.native) == other_int
+        return as_int512(self.as_biguint()) == other_int
 
     def __lt__(self, other: object) -> bool:
         try:
             other_int = as_int512(other)
         except (TypeError, ValueError):
             return NotImplemented
-        return as_int512(self.native) < other_int
+        return as_int512(self.as_biguint()) < other_int
 
     def __bool__(self) -> bool:
-        return bool(self.native)
+        return bool(self.as_biguint())
 
     def __str__(self) -> str:
-        return str(self.native)
+        return str(self.as_biguint())
 
     def __repr__(self) -> str:
         return _arc4_repr(self)
@@ -959,7 +989,7 @@ def __init__(self, *value: algopy.Bytes | bytes | Byte | UInt8 | int):
                         raise ValueError("expected single Bytes value")
                     items.extend([Byte(b) for b in as_bytes(x)])
                 case UIntN(_type_info=_UIntTypeInfo(bit_size=8)) as uint:
-                    items.append(Byte(as_int(uint.native, max=2**8)))
+                    items.append(Byte(as_int(uint.as_uint64(), max=2**8)))
                 case int(int_value):
                     items.append(Byte(int_value))
                 case _:

src/_algopy_testing/op/pure.py

@@ -109,7 +109,7 @@ def extract_uint64(a: Bytes | bytes, b: UInt64 | int, /) -> UInt64:
     return UInt64(result_int)
 
 
-def getbit(a: Bytes | UInt64 | bytes | int, b: UInt64 | int, /) -> UInt64:
+def getbit(a: Bytes | UInt64 | bytes | int, b: UInt64 | int, /) -> bool:
     if isinstance(a, Bytes | bytes):
         return _getbit_bytes(a, b)
     if isinstance(a, UInt64 | int):
@@ -162,11 +162,11 @@ def select_uint64(a: UInt64 | int, b: UInt64 | int, c: bool | UInt64 | int, /) -
     return UInt64(b if c != 0 else a)
 
 
-def setbit_bytes(a: Bytes | bytes, b: UInt64 | int, c: UInt64 | int, /) -> Bytes:
+def setbit_bytes(a: Bytes | bytes, b: UInt64 | int, c: bool, /) -> Bytes:  # noqa: FBT001
     return _setbit_bytes(a, b, c)
 
 
-def setbit_uint64(a: UInt64 | int, b: UInt64 | int, c: UInt64 | int, /) -> UInt64:
+def setbit_uint64(a: UInt64 | int, b: UInt64 | int, c: bool, /) -> UInt64:  # noqa: FBT001
     a_bytes = _uint64_to_bytes(a)
     result = _setbit_bytes(a_bytes, b, c, "little")
     return UInt64(int.from_bytes(result.value))
@@ -241,7 +241,7 @@ def _int_list_to_bytes(a: list[int]) -> bytes:
 
 def _getbit_bytes(
     a: Bytes | bytes, b: UInt64 | int, byteorder: typing.Literal["little", "big"] = "big"
-) -> UInt64:
+) -> bool:
     a = as_bytes(a)
     if byteorder != "big":  # reverse bytes if NOT big endian
         a = bytes(reversed(a))
@@ -256,13 +256,13 @@ def _getbit_bytes(
         bit_index = 7 - bit_index
     bit = _get_bit(int_list[byte_index], bit_index)
 
-    return UInt64(bit)
+    return bit != 0
 
 
 def _setbit_bytes(
     a: Bytes | bytes,
     b: UInt64 | int,
-    c: UInt64 | int,
+    c: bool,  # noqa: FBT001
     byteorder: typing.Literal["little", "big"] = "big",
 ) -> Bytes:
     a = as_bytes(a)
@@ -272,7 +272,6 @@ def _setbit_bytes(
     int_list = list(a)
     max_index = len(int_list) * BITS_IN_BYTE - 1
     b = as_int(b, max=max_index)
-    c = as_int(c, max=1)
 
     byte_index = b // BITS_IN_BYTE
     bit_index = b % BITS_IN_BYTE
@@ -291,7 +290,7 @@ def _get_bit(v: int, index: int) -> int:
     return (v >> index) & 1
 
 
-def _set_bit(v: int, index: int, x: int) -> int:
+def _set_bit(v: int, index: int, x: bool) -> int:  # noqa: FBT001
     """Set the index:th bit of v to 1 if x is truthy, else to 0, and return the new
     value."""
     mask = 1 << index  # Compute mask, an integer with just bit 'index' set.

src/_algopy_testing/serialize.py

@@ -50,7 +50,11 @@ def get_native_to_arc4_serializer(  # noqa: PLR0911
                 return _Serializer(
                     arc4_type=simple_arc4_type,
                     native_to_arc4=simple_arc4_type,
-                    arc4_to_native=lambda n: n.native,
+                    arc4_to_native=lambda n: (
+                        n.as_uint64()
+                        if isinstance(n, arc4.UIntN)
+                        else n.as_biguint() if isinstance(n, arc4.BigUIntN) else n.native
+                    ),
                 )
         if issubclass(typ, UInt64Backed):
             return _Serializer(