algorand-python-testing 0.1.0__py3-none-any.whl

algopy_testing/itxn.py

@@ -0,0 +1,353 @@
+from __future__ import annotations
+
+import logging
+import typing
+from copy import deepcopy
+
+import algosdk
+
+from algopy_testing.constants import MAX_UINT64
+from algopy_testing.context import get_test_context
+from algopy_testing.models.transactions import (
+    PaymentFields,
+    _ApplicationCallBaseFields,
+    _AssetConfigBaseFields,
+    _AssetFreezeBaseFields,
+    _AssetTransferBaseFields,
+    _KeyRegistrationBaseFields,
+    _PaymentBaseFields,
+    _TransactionCoreFields,
+    _TransactionFields,
+)
+from algopy_testing.utils import dummy_transaction_id, txn_type_to_bytes
+
+logger = logging.getLogger(__name__)
+
+if typing.TYPE_CHECKING:
+    import algopy
+
+
+class _BaseInnerTransaction:
+    fields: dict[str, typing.Any]
+
+    def submit(self) -> object:
+        import algopy.itxn
+
+        context = get_test_context()
+
+        if not context:
+            raise RuntimeError("No test context found")
+
+        result = algopy.itxn.InnerTransactionResult(**self.fields)
+        context._append_inner_transaction_group([result])
+        return result
+
+    def copy(self) -> typing.Self:
+        return deepcopy(self)
+
+    def get_field(self, type_dict: object, name: str) -> typing.Any:
+        if name in type_dict.__annotations__:
+            return self.fields.get(name)
+
+        raise AttributeError(f"{type(self).__name__!r} object has no attribute {name!r}")
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, _BaseInnerTransaction):
+            return bool(self.fields == other.fields)
+        return False
+
+    def __hash__(self) -> int:
+        return hash(self.fields)
+
+
+class InnerTransaction(_BaseInnerTransaction):
+    def __init__(
+        self,
+        *,
+        type: algopy.TransactionType,  # noqa: A002
+        **kwargs: typing.Unpack[_TransactionCoreFields],
+    ):
+        self.fields = {
+            "type": type,
+            "type_bytes": txn_type_to_bytes(int(type)),
+            **kwargs,
+        }
+
+    def set(self, **kwargs: typing.Unpack[_TransactionFields]) -> None:
+        """Updates inner transaction parameter values"""
+        self.fields.update(kwargs)
+
+    def __getattr__(self, name: str) -> object:
+        return self.get_field(_TransactionFields, name)
+
+
+class Payment(_BaseInnerTransaction):
+    def __init__(self, **kwargs: typing.Unpack[_PaymentBaseFields]):
+        import algopy
+
+        self.fields = {**kwargs, "type": algopy.TransactionType.Payment}
+
+    def set(self, **kwargs: typing.Unpack[_PaymentBaseFields]) -> None:
+        """Updates inner transaction parameter values"""
+        import algopy
+
+        self.fields.update({**kwargs, "type": algopy.TransactionType.Payment})
+
+    def __getattr__(self, name: str) -> object:
+        return self.get_field(_PaymentBaseFields, name)
+
+
+class KeyRegistration(_BaseInnerTransaction):
+    def __init__(self, **kwargs: typing.Unpack[_KeyRegistrationBaseFields]):
+        import algopy
+
+        self.fields = {**kwargs, "type": algopy.TransactionType.KeyRegistration}
+
+    def set(self, **kwargs: typing.Unpack[_KeyRegistrationBaseFields]) -> None:
+        """Updates inner transaction parameter values"""
+        import algopy
+
+        self.fields.update({**kwargs, "type": algopy.TransactionType.KeyRegistration})
+
+    def __getattr__(self, name: str) -> object:
+        return self.get_field(_KeyRegistrationBaseFields, name)
+
+
+class AssetConfig(_BaseInnerTransaction):
+    def __init__(self, **kwargs: typing.Unpack[_AssetConfigBaseFields]):
+        import algopy
+
+        self.fields = {**kwargs, "type": algopy.TransactionType.AssetConfig}
+
+    def set(self, **kwargs: typing.Unpack[_AssetConfigBaseFields]) -> None:
+        """Updates inner transaction parameter values"""
+        import algopy
+
+        self.fields.update({**kwargs, "type": algopy.TransactionType.AssetConfig})
+
+    def __getattr__(self, name: str) -> object:
+        return self.get_field(_AssetConfigBaseFields, name)
+
+
+class AssetTransfer(_BaseInnerTransaction):
+    def __init__(self, **kwargs: typing.Unpack[_AssetTransferBaseFields]):
+        import algopy
+
+        from algopy_testing import get_test_context
+
+        context = get_test_context()
+        self.fields = {
+            "type": algopy.TransactionType.AssetTransfer,
+            "asset_sender": context.default_application.address if context else None,
+            "amount": 0,
+            **kwargs,
+        }
+
+    def set(self, **kwargs: typing.Unpack[_AssetTransferBaseFields]) -> None:
+        """Updates inner transaction parameter values"""
+        import algopy
+
+        self.fields.update({**kwargs, "type": algopy.TransactionType.AssetTransfer})
+
+    def __getattr__(self, name: str) -> object:
+        return self.get_field(_AssetTransferBaseFields, name)
+
+
+class AssetFreeze(_BaseInnerTransaction):
+    def __init__(self, **kwargs: typing.Unpack[_AssetFreezeBaseFields]):
+        import algopy
+
+        self.fields = {**kwargs, "type": algopy.TransactionType.AssetFreeze}
+
+    def set(self, **kwargs: typing.Unpack[_AssetFreezeBaseFields]) -> None:
+        """Updates inner transaction parameter values"""
+        import algopy
+
+        self.fields.update({**kwargs, "type": algopy.TransactionType.AssetFreeze})
+
+    def __getattr__(self, name: str) -> object:
+        return self.get_field(_AssetFreezeBaseFields, name)
+
+
+class ApplicationCall(_BaseInnerTransaction):
+    def __init__(self, **kwargs: typing.Unpack[_ApplicationCallBaseFields]):
+        import algopy
+
+        self.fields = {**kwargs, "type": algopy.TransactionType.ApplicationCall}
+
+    def set(self, **kwargs: typing.Unpack[_ApplicationCallBaseFields]) -> None:
+        """Updates inner transaction parameter values"""
+        import algopy
+
+        self.fields.update({**kwargs, "type": algopy.TransactionType.ApplicationCall})
+
+    def __getattr__(self, name: str) -> object:
+        return self.get_field(_ApplicationCallBaseFields, name)
+
+
+# ==== Inner Transaction Results  ====
+# These are used to represent finalized transactions submitted to the network
+# and are created by the `submit` method of each inner transaction class
+
+
+class _BaseInnerTransactionResult:
+    fields: dict[str, typing.Any]
+
+    @typing.overload
+    def __init__(
+        self,
+        txn_type: algopy.TransactionType,
+        **kwargs: typing.Unpack[_TransactionFields],
+    ): ...
+
+    @typing.overload
+    def __init__(
+        self,
+        **kwargs: typing.Unpack[_TransactionFields],
+    ): ...
+
+    def __init__(
+        self,
+        txn_type: algopy.TransactionType | None = None,
+        **kwargs: typing.Unpack[_TransactionFields],
+    ):
+        import algopy
+
+        if txn_type is None and kwargs.get("type") is None:
+            raise ValueError("No transaction type provided to `algopy.itxn.InnerTransaction`")
+
+        txn_type = txn_type if txn_type is not None else kwargs.get("type")
+        txn_type_bytes = txn_type_to_bytes(int(txn_type))  # type: ignore[arg-type]
+
+        self.fields = {
+            "type": txn_type,
+            "type_bytes": txn_type_bytes,
+            "first_valid": algopy.UInt64(0),
+            "first_valid_time": algopy.UInt64(0),
+            "last_valid": algopy.UInt64(MAX_UINT64),
+            "note": algopy.Bytes(b""),
+            "lease": algopy.Bytes(bytes(algosdk.constants.ZERO_ADDRESS, encoding="utf-8")),
+            "close_remainder_to": algopy.Bytes(
+                bytes(algosdk.constants.ZERO_ADDRESS, encoding="utf-8")
+            ),
+            "txn_id": algopy.Bytes(dummy_transaction_id()),
+            **kwargs,
+        }
+        self._parse_covariant_types()
+
+    def get_field(self, type_dict: object, name: str) -> typing.Any:
+        if name in type_dict.__annotations__:
+            return self.fields.get(name)
+
+        raise AttributeError(f"{type(self).__name__!r} object has no attribute {name!r}")
+
+    def _parse_covariant_types(
+        self,
+    ) -> None:
+        import algopy
+
+        for name, value in self.fields.items():
+            if isinstance(value, int):
+                self.fields[name] = algopy.UInt64(value)
+            if isinstance(value, bytes):
+                self.fields[name] = algopy.Bytes(value)
+            if isinstance(value, str):
+                self.fields[name] = algopy.Bytes(value.encode("utf-8"))
+
+
+class PaymentInnerTransaction(_BaseInnerTransactionResult):
+    def __init__(self, **kwargs: typing.Unpack[PaymentFields]):
+        import algopy
+
+        super().__init__(algopy.TransactionType.Payment, **kwargs)
+
+    def __getattr__(self, name: str) -> object:
+        return self.get_field(PaymentFields, name)
+
+
+class KeyRegistrationInnerTransaction(_BaseInnerTransactionResult):
+    def __init__(self, **kwargs: typing.Unpack[_KeyRegistrationBaseFields]):
+        import algopy
+
+        super().__init__(algopy.TransactionType.KeyRegistration, **kwargs)
+
+    def __getattr__(self, name: str) -> object:
+        return self.get_field(_KeyRegistrationBaseFields, name)
+
+
+class AssetConfigInnerTransaction(_BaseInnerTransactionResult):
+    def __init__(self, **kwargs: typing.Unpack[_AssetConfigBaseFields]):
+        import algopy
+
+        super().__init__(algopy.TransactionType.AssetConfig, **kwargs)
+
+    def __getattr__(self, name: str) -> object:
+        return self.get_field(_AssetConfigBaseFields, name)
+
+
+class AssetTransferInnerTransaction(_BaseInnerTransactionResult):
+    def __init__(self, **kwargs: typing.Unpack[_AssetTransferBaseFields]):
+        import algopy
+
+        super().__init__(algopy.TransactionType.AssetTransfer, **kwargs)
+
+    def __getattr__(self, name: str) -> object:
+        return self.get_field(_AssetTransferBaseFields, name)
+
+
+class AssetFreezeInnerTransaction(_BaseInnerTransactionResult):
+    def __init__(self, **kwargs: typing.Unpack[_AssetFreezeBaseFields]):
+        import algopy
+
+        super().__init__(algopy.TransactionType.AssetFreeze, **kwargs)
+
+    def __getattr__(self, name: str) -> object:
+        return self.get_field(_AssetFreezeBaseFields, name)
+
+
+class ApplicationCallInnerTransaction(_BaseInnerTransactionResult):
+    def __init__(self, **kwargs: typing.Unpack[_ApplicationCallBaseFields]):
+        import algopy
+
+        super().__init__(algopy.TransactionType.ApplicationCall, **kwargs)
+
+    def __getattr__(self, name: str) -> object:
+        return self.get_field(_ApplicationCallBaseFields, name)
+
+
+class InnerTransactionResult(_BaseInnerTransactionResult):
+    def __init__(self, **kwargs: typing.Unpack[_TransactionFields]):
+        super().__init__(**kwargs)
+
+    def __getattr__(self, name: str) -> object:
+        return self.get_field(_TransactionFields, name)
+
+
+_InnerTransactionsType = (
+    InnerTransactionResult
+    | PaymentInnerTransaction
+    | KeyRegistrationInnerTransaction
+    | AssetConfigInnerTransaction
+    | AssetTransferInnerTransaction
+    | AssetFreezeInnerTransaction
+    | ApplicationCallInnerTransaction
+)
+
+__all__ = [
+    "_BaseInnerTransaction",
+    "_InnerTransactionsType",
+    "InnerTransaction",
+    "Payment",
+    "KeyRegistration",
+    "AssetConfig",
+    "AssetTransfer",
+    "AssetFreeze",
+    "ApplicationCall",
+    "PaymentInnerTransaction",
+    "KeyRegistrationInnerTransaction",
+    "AssetConfigInnerTransaction",
+    "AssetTransferInnerTransaction",
+    "AssetFreezeInnerTransaction",
+    "ApplicationCallInnerTransaction",
+    "InnerTransactionResult",
+]

algopy_testing/models/__init__.py

@@ -0,0 +1,23 @@
+from algopy_testing.models.account import Account
+from algopy_testing.models.application import Application
+from algopy_testing.models.asset import Asset
+from algopy_testing.models.contract import ARC4Contract, Contract
+from algopy_testing.models.global_values import Global
+from algopy_testing.models.gtxn import GTxn
+from algopy_testing.models.itxn import ITxn
+from algopy_testing.models.txn import Txn
+from algopy_testing.models.unsigned_builtins import uenumerate, urange
+
+__all__ = [
+    "ARC4Contract",
+    "Account",
+    "Application",
+    "Asset",
+    "Contract",
+    "Global",
+    "GTxn",
+    "ITxn",
+    "Txn",
+    "uenumerate",
+    "urange",
+]

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_string
+
+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_string(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)