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

algopy_testing/models/account.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Self, TypedDict, TypeVar
+
+import algosdk
+
+from algopy_testing.primitives.bytes import Bytes
+from algopy_testing.utils import as_bytes
+
+if TYPE_CHECKING:
+    import algopy
+
+
+T = TypeVar("T")
+
+
+class AccountFields(TypedDict, total=False):
+    balance: algopy.UInt64
+    min_balance: algopy.UInt64
+    auth_address: algopy.Account
+    total_num_uint: algopy.UInt64
+    total_num_byte_slice: algopy.Bytes
+    total_extra_app_pages: algopy.UInt64
+    total_apps_created: algopy.UInt64
+    total_apps_opted_in: algopy.UInt64
+    total_assets_created: algopy.UInt64
+    total_assets: algopy.UInt64
+    total_boxes: algopy.UInt64
+    total_box_bytes: algopy.UInt64
+
+
+@dataclass()
+class Account:
+    _public_key: bytes
+
+    def __init__(self, value: str | Bytes = algosdk.constants.ZERO_ADDRESS, /):
+        if not isinstance(value, (str | Bytes)):
+            raise TypeError("Invalid value for Account")
+
+        public_key = (
+            algosdk.encoding.decode_address(value) if isinstance(value, str) else value.value
+        )
+
+        self._public_key = public_key
+
+    def is_opted_in(self, asset_or_app: algopy.Asset | algopy.Application, /) -> bool:
+        from algopy import Application, Asset
+
+        from algopy_testing import get_test_context
+
+        context = get_test_context()
+        opted_apps = context._account_data[str(self)].opted_apps
+        opted_asset_balances = context._account_data[str(self)].opted_asset_balances
+
+        if not context:
+            raise ValueError(
+                "Test context is not initialized! Use `with algopy_testing_context()` to access "
+                "the context manager."
+            )
+
+        if isinstance(asset_or_app, Asset):
+            return asset_or_app.id in opted_asset_balances
+        elif isinstance(asset_or_app, Application):
+            return asset_or_app.id in opted_apps
+
+        raise TypeError(
+            "Invalid `asset_or_app` argument type. Must be an `algopy.Asset` or "
+            "`algopy.Application` instance."
+        )
+
+    @classmethod
+    def from_bytes(cls, value: algopy.Bytes | bytes) -> Self:
+        # NOTE: AVM does not perform any validation beyond type.
+        validated_value = as_bytes(value)
+        return cls(Bytes(validated_value))
+
+    @property
+    def bytes(self) -> Bytes:
+        return Bytes(self._public_key)
+
+    def __getattr__(self, name: str) -> object:
+        from algopy_testing.context import get_test_context
+
+        context = get_test_context()
+        if not context:
+            raise ValueError(
+                "Test context is not initialized! Use `with algopy_testing_context()` to access "
+                "the context manager."
+            )
+
+        if str(self) not in context._account_data:
+            raise ValueError(
+                "`algopy.Account` is not present in the test context! "
+                "Use `context.add_account()` or `context.any_account()` to add the account "
+                "to your test setup."
+            )
+
+        return_value = context._account_data[str(self)].fields.get(name)
+        if return_value is None:
+            raise AttributeError(
+                f"The value for '{name}' in the test context is None. "
+                f"Make sure to patch the global field '{name}' using your `AlgopyTestContext` "
+                "instance."
+            )
+
+        return return_value
+
+    def __repr__(self) -> str:
+        return str(algosdk.encoding.encode_address(self._public_key))
+
+    def __str__(self) -> str:
+        return str(algosdk.encoding.encode_address(self._public_key))
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Account | str):
+            raise TypeError("Invalid value for Account")
+        if isinstance(other, Account):
+            return self._public_key == other._public_key
+        return self._public_key == as_bytes(other)
+
+    def __bool__(self) -> bool:
+        return bool(self._public_key) and self._public_key != algosdk.encoding.decode_address(
+            algosdk.constants.ZERO_ADDRESS
+        )
+
+    def __hash__(self) -> int:
+        return hash(self._public_key)

algopy_testing/models/application.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import typing
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypedDict, TypeVar
+
+from algopy_testing.utils import as_int64
+
+if TYPE_CHECKING:
+    import algopy
+
+
+T = TypeVar("T")
+
+
+class ApplicationFields(TypedDict, total=False):
+    approval_program: algopy.Bytes
+    clear_state_program: algopy.Bytes
+    global_num_uint: algopy.UInt64
+    global_num_bytes: algopy.UInt64
+    local_num_uint: algopy.UInt64
+    local_num_bytes: algopy.UInt64
+    extra_program_pages: algopy.UInt64
+    creator: algopy.Account
+    address: algopy.Account
+
+
+@dataclass()
+class Application:
+    id: algopy.UInt64
+
+    def __init__(self, application_id: algopy.UInt64 | int = 0, /):
+        from algopy import UInt64
+
+        self.id = application_id if isinstance(application_id, UInt64) else UInt64(application_id)
+
+    def __getattr__(self, name: str) -> typing.Any:
+        from algopy_testing.context import get_test_context
+
+        context = get_test_context()
+        if not context:
+            raise ValueError(
+                "Test context is not initialized! Use `with algopy_testing_context()` to access "
+                "the context manager."
+            )
+        if int(self.id) not in context._application_data:
+            raise ValueError(
+                "`algopy.Application` is not present in the test context! "
+                "Use `context.add_application()` or `context.any_application()` to add the "
+                "application to your test setup."
+            )
+
+        return_value = context._application_data[int(self.id)].get(name)
+        if return_value is None:
+            raise AttributeError(
+                f"The value for '{name}' in the test context is None. "
+                f"Make sure to patch the global field '{name}' using your `AlgopyTestContext` "
+                "instance."
+            )
+
+        return return_value
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Application):
+            return self.id == other.id
+        return self.id == as_int64(other)
+
+    def __bool__(self) -> bool:
+        return self.id != 0
+
+    def __hash__(self) -> int:
+        return hash(self.id)

algopy_testing/models/asset.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypedDict, TypeVar
+
+if TYPE_CHECKING:
+    import algopy
+
+
+T = TypeVar("T")
+
+
+class AssetFields(TypedDict, total=False):
+    total: algopy.UInt64
+    decimals: algopy.UInt64
+    default_frozen: bool
+    unit_name: algopy.Bytes
+    name: algopy.Bytes
+    url: algopy.Bytes
+    metadata_hash: algopy.Bytes
+    manager: algopy.Account
+    reserve: algopy.Account
+    freeze: algopy.Account
+    clawback: algopy.Account
+    creator: algopy.Account
+
+
+@dataclass
+class Asset:
+    id: algopy.UInt64
+
+    def __init__(self, asset_id: algopy.UInt64 | int = 0):
+        from algopy import UInt64
+
+        self.id = asset_id if isinstance(asset_id, UInt64) else UInt64(asset_id)
+
+    def balance(self, account: algopy.Account) -> algopy.UInt64:
+        from algopy_testing.context import get_test_context
+
+        context = get_test_context()
+        if not context:
+            raise ValueError(
+                "Test context is not initialized! Use `with algopy_testing_context()` to access "
+                "the context manager."
+            )
+
+        if account not in context._account_data:
+            raise ValueError(
+                "The account is not present in the test context! "
+                "Use `context.add_account()` or `context.any_account()` to add the account to "
+                "your test setup."
+            )
+
+        account_data = context._account_data.get(str(account), None)
+
+        if not account_data:
+            raise ValueError("Account not found in testing context!")
+
+        if int(self.id) not in account_data.opted_asset_balances:
+            raise ValueError(
+                "The asset is not opted into the account! "
+                "Use `account.opt_in()` to opt the asset into the account."
+            )
+
+        return account_data.opted_asset_balances[self.id]
+
+    def frozen(self, _account: algopy.Account) -> bool:
+        raise NotImplementedError(
+            "The 'frozen' method is being executed in a python testing context. "
+            "Please mock this method using your python testing framework of choice."
+        )
+
+    def __getattr__(self, name: str) -> object:
+        from algopy_testing.context import get_test_context
+
+        context = get_test_context()
+        if not context:
+            raise ValueError(
+                "Test context is not initialized! Use `with algopy_testing_context()` to access "
+                "the context manager."
+            )
+
+        if int(self.id) not in context._asset_data:
+            raise ValueError(
+                "`algopy.Asset` is not present in the test context! "
+                "Use `context.add_asset()` or `context.any_asset()` to add the asset to "
+                "your test setup."
+            )
+
+        return_value = context._asset_data[int(self.id)].get(name)
+        if return_value is None:
+            raise AttributeError(
+                f"The value for '{name}' in the test context is None. "
+                f"Make sure to patch the global field '{name}' using your `AlgopyTestContext` "
+                "instance."
+            )
+
+        return return_value
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Asset):
+            return self.id == other.id
+        return self.id == other
+
+    def __bool__(self) -> bool:
+        return self.id != 0
+
+    def __hash__(self) -> int:
+        return hash(self.id)

algopy_testing/models/block.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import algopy
+
+
+class Block:
+    @staticmethod
+    def blk_seed(a: algopy.UInt64 | int, /) -> algopy.Bytes:
+        from algopy_testing import get_test_context, op
+
+        context = get_test_context()
+
+        try:
+            index = int(a)
+            return op.itob(context._blocks[index]["seed"])
+        except KeyError as e:
+            raise KeyError(f"Block {a} not set") from e
+
+    @staticmethod
+    def blk_timestamp(a: algopy.UInt64 | int, /) -> algopy.UInt64:
+        import algopy
+
+        from algopy_testing import get_test_context
+
+        context = get_test_context()
+
+        try:
+            index = int(a)
+            return algopy.UInt64(context._blocks[index]["timestamp"])
+        except KeyError as e:
+            raise KeyError(f"Block {a} not set") from e

algopy_testing/models/box.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from algopy_testing.context import get_test_context
+
+if TYPE_CHECKING:
+    import algopy
+
+
+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 > 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
+
+    @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 ValueError("Box does not exist")
+        return box_content[start : start + length]
+
+    @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 = context.get_box(name_bytes)
+        return box_content, bool(box_content)
+
+    @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)
+        return algopy.UInt64(len(box_content)), bool(box_content)
+
+    @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, 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 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)
+
+    @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 > 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))
+        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 ValueError("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)

algopy_testing/models/contract.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, final
+
+if TYPE_CHECKING:
+    import algopy
+
+
+@dataclass
+class StateTotals:
+    global_uints: int | None = None
+    global_bytes: int | None = None
+    local_uints: int | None = None
+    local_bytes: int | None = None
+
+
+class _ContractMeta(type):
+    def __call__(cls, *args: Any, **kwargs: dict[str, Any]) -> object:
+        from algopy import Contract
+
+        from algopy_testing.context import get_test_context
+
+        context = get_test_context()
+        instance = super().__call__(*args, **kwargs)
+
+        if context and isinstance(instance, Contract):
+            context._add_contract(instance)
+
+        return instance
+
+
+class Contract(metaclass=_ContractMeta):
+    """Base class for an Algorand Smart Contract"""
+
+    _name: str
+    _scratch_slots: Any | None
+    _state_totals: StateTotals | None
+
+    def __init_subclass__(
+        cls,
+        *,
+        name: str | None = None,
+        scratch_slots: (
+            algopy.UInt64 | tuple[int | algopy.UInt64, ...] | list[int | algopy.UInt64] | None
+        ) = None,
+        state_totals: StateTotals | None = None,
+    ):
+        cls._name = name or cls.__name__
+        cls._scratch_slots = scratch_slots
+        cls._state_totals = state_totals
+
+    def approval_program(self) -> algopy.UInt64 | bool:
+        raise NotImplementedError("`approval_program` is not implemented.")
+
+    def clear_state_program(self) -> algopy.UInt64 | bool:
+        raise NotImplementedError("`clear_state_program` is not implemented.")
+
+    def __hash__(self) -> int:
+        return hash(self._name)
+
+    def __getattribute__(self, name: str) -> Any:
+        attr = super().__getattribute__(name)
+        if callable(attr):
+
+            def wrapper(*args: Any, **kwargs: dict[str, Any]) -> Any:
+                return attr(*args, **kwargs)
+
+            return wrapper
+        return attr
+
+
+class ARC4Contract(Contract):
+    @final
+    def approval_program(self) -> algopy.UInt64 | bool:
+        raise NotImplementedError(
+            "`approval_program` is not implemented. To test ARC4 specific logic, "
+            "refer to direct calls to ARC4 methods."
+        )
+
+    def clear_state_program(self) -> algopy.UInt64 | bool:
+        return True

algopy_testing/models/gitxn.py

@@ -0,0 +1,42 @@
+import typing
+from collections.abc import Callable, Sequence
+
+
+class _GITxn:
+    def __getattr__(self, name: str) -> Callable[[int], typing.Any]:
+        from algopy_testing.context import get_test_context
+
+        context = get_test_context()
+        if not context:
+            raise ValueError(
+                "Test context is not initialized! Use `with algopy_testing_context()` to access "
+                "the context manager."
+            )
+        if not context._inner_transaction_groups:
+            raise ValueError(
+                "No inner transaction found in the context! Use `with algopy_testing_context()` "
+                "to access the context manager."
+            )
+        last_itxn_group = context._inner_transaction_groups[-1]
+
+        if not last_itxn_group:
+            raise ValueError("No inner transaction found in the testing context!")
+
+        return lambda index: self._get_value(last_itxn_group, name, index)
+
+    # TODO: refine mapping
+    def _map_fields(self, name: str) -> str:
+        field_mapping = {"type": "type_bytes", "type_enum": "type", "application_args": "app_args"}
+        return field_mapping.get(name, name)
+
+    def _get_value(self, itxn_group: Sequence[typing.Any], name: str, index: int) -> object:
+        if index >= len(itxn_group):
+            raise IndexError("Transaction index out of range")
+        itxn = itxn_group[index]
+        value = getattr(itxn, self._map_fields(name))
+        if value is None:
+            raise ValueError(f"'{name}' is not defined for {type(itxn).__name__}")
+        return value
+
+
+GITxn = _GITxn()

algopy_testing/models/global_values.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import time
+import typing
+from dataclasses import dataclass
+from typing import TypedDict, TypeVar
+
+import algosdk
+
+if typing.TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import algopy
+
+T = TypeVar("T")
+
+
+class GlobalFields(TypedDict, total=False):
+    min_txn_fee: algopy.UInt64
+    min_balance: algopy.UInt64
+    max_txn_life: algopy.UInt64
+    zero_address: algopy.Account
+    group_size: algopy.UInt64
+    logic_sig_version: algopy.UInt64
+    round: algopy.UInt64
+    latest_timestamp: algopy.UInt64
+    current_application_id: algopy.Application
+    creator_address: algopy.Account
+    current_application_address: algopy.Account
+    group_id: algopy.Bytes
+    caller_application_id: algopy.Application
+    caller_application_address: algopy.Account
+    asset_create_min_balance: algopy.UInt64
+    asset_opt_in_min_balance: algopy.UInt64
+    genesis_hash: algopy.Bytes
+    opcode_budget: Callable[[], int]
+
+
+@dataclass
+class _Global:
+    def __getattr__(self, name: str) -> typing.Any:
+        import algopy
+
+        from algopy_testing.context import get_test_context
+
+        context = get_test_context()
+        if not context:
+            raise ValueError(
+                "Test context is not initialized! Use `with algopy_testing_context()` to access "
+                "the context manager."
+            )
+
+        if name == "latest_timestamp" and context._global_fields.get(name) is None:
+            return algopy.UInt64(int(time.time()))
+
+        if name == "group_size" and context._global_fields.get(name) is None:
+            return algopy.UInt64(len(context.get_transaction_group()))
+
+        if name == "zero_address" and context._global_fields.get(name) is None:
+            return algopy.Account(algosdk.constants.ZERO_ADDRESS)
+
+        if name not in context._global_fields:
+            raise AttributeError(
+                f"'algopy.Global' object has no value set for attribute named '{name}'. "
+                f"Use `context.patch_global_fields({name}=your_value)` to set the value "
+                "in your test setup."
+            )
+
+        return context._global_fields[name]  # type: ignore[literal-required]
+
+
+Global = _Global()