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

algopy_testing/models/contract.py

@@ -0,0 +1,69 @@
+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.")
+
+
+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/global_values.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import time
+import typing
+from dataclasses import dataclass
+from typing import TypedDict, TypeVar
+
+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.UInt64
+    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:
+        from algopy import 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 name == "latest_timestamp" and context._global_fields.get(name) is None:
+            return UInt64(int(time.time()))
+
+        if name == "group_size" and context._global_fields.get(name) is None:
+            return UInt64(len(context.get_transaction_group()))
+
+        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()

algopy_testing/models/gtxn.py

@@ -0,0 +1,40 @@
+import typing
+from collections.abc import Callable
+
+
+class _GTxn:
+    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."
+            )
+
+        txn_group = context.get_transaction_group()
+        if not txn_group:
+            raise ValueError(
+                "No group transactions found in the context! Use `with algopy_testing_context()` "
+                "to access the context manager."
+            )
+
+        return lambda index: self._get_value(txn_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, txn_group: list[typing.Any], name: str, index: int) -> object:
+        if index >= len(txn_group):
+            raise IndexError("Transaction index out of range")
+        gtxn = txn_group[index]
+        value = getattr(gtxn, self._map_fields(name))
+        if value is None:
+            raise ValueError(f"'{name}' is not defined for {type(gtxn).__name__}")
+        return value
+
+
+GTxn = _GTxn()

algopy_testing/models/itxn.py

@@ -0,0 +1,34 @@
+import typing
+from collections.abc import Callable
+
+
+class _ITxn:
+    def __getattr__(self, name: str) -> Callable[[], 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!")
+
+        last_itxn = last_itxn_group[-1]
+
+        value = getattr(last_itxn, name)
+        if value is None:
+            raise ValueError(f"'{name}' is not defined for {type(last_itxn).__name__} ")
+        # mimic the static functions on ITxn with a lambda
+        return lambda: value
+
+
+ITxn = _ITxn()

algopy_testing/models/transactions.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import typing
+from typing import TYPE_CHECKING, TypedDict
+
+if TYPE_CHECKING:
+    import algopy
+
+
+class _TransactionCoreFields(TypedDict, total=False):
+    sender: algopy.Account
+    fee: algopy.UInt64
+    first_valid: algopy.UInt64
+    first_valid_time: algopy.UInt64
+    last_valid: algopy.UInt64
+    note: algopy.Bytes
+    lease: algopy.Bytes
+    txn_id: algopy.Bytes
+    rekey_to: algopy.Account
+
+
+class _TransactionBaseFields(_TransactionCoreFields, total=False):
+    type: algopy.TransactionType
+    type_bytes: algopy.Bytes
+
+
+class _AssetTransferBaseFields(TypedDict, total=False):
+    xfer_asset: algopy.Asset
+    asset_amount: algopy.UInt64
+    asset_sender: algopy.Account
+    asset_receiver: algopy.Account
+    asset_close_to: algopy.Account
+
+
+class _PaymentBaseFields(TypedDict, total=False):
+    receiver: algopy.Account
+    amount: algopy.UInt64
+    close_remainder_to: algopy.Account
+
+
+class _AssetFreezeBaseFields(TypedDict, total=False):
+    freeze_asset: algopy.Asset
+    freeze_account: algopy.Account
+    frozen: bool
+
+
+class _AssetConfigBaseFields(TypedDict, total=False):
+    config_asset: algopy.Asset
+    total: algopy.UInt64
+    decimals: algopy.UInt64
+    default_frozen: bool
+    unit_name: algopy.Bytes
+    asset_name: algopy.Bytes
+    url: algopy.Bytes
+    metadata_hash: algopy.Bytes
+    manager: algopy.Account
+    reserve: algopy.Account
+    freeze: algopy.Account
+    clawback: algopy.Account
+
+
+class _ApplicationCallCoreFields(TypedDict, total=False):
+    app_id: algopy.Application
+    on_completion: algopy.OnCompleteAction
+    num_app_args: algopy.UInt64
+    num_accounts: algopy.UInt64
+    approval_program: algopy.Bytes
+    clear_state_program: algopy.Bytes
+    num_assets: algopy.UInt64
+    num_apps: algopy.UInt64
+    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
+    last_log: algopy.Bytes
+    num_approval_program_pages: algopy.UInt64
+    num_clear_state_program_pages: algopy.UInt64
+
+
+class _ApplicationCallBaseFields(_ApplicationCallCoreFields, total=False):
+    app_args: typing.Callable[[algopy.UInt64 | int], algopy.Bytes]
+    accounts: typing.Callable[[algopy.UInt64 | int], algopy.Account]
+    assets: typing.Callable[[algopy.UInt64 | int], algopy.Asset]
+    apps: typing.Callable[[algopy.UInt64 | int], algopy.Application]
+    approval_program_pages: typing.Callable[[algopy.UInt64 | int], algopy.Bytes]
+    clear_state_program_pages: typing.Callable[[algopy.UInt64 | int], algopy.Bytes]
+
+
+class _ApplicationCallFields(_TransactionBaseFields, _ApplicationCallCoreFields, total=False):
+    pass
+
+
+class _KeyRegistrationBaseFields(TypedDict, total=False):
+    vote_key: algopy.Bytes
+    selection_key: algopy.Bytes
+    vote_first: algopy.UInt64
+    vote_last: algopy.UInt64
+    vote_key_dilution: algopy.UInt64
+    non_participation: bool
+    state_proof_key: algopy.Bytes
+
+
+class _TransactionFields(
+    _TransactionBaseFields,
+    _PaymentBaseFields,
+    _KeyRegistrationBaseFields,
+    _AssetConfigBaseFields,
+    _AssetTransferBaseFields,
+    _AssetFreezeBaseFields,
+    _ApplicationCallBaseFields,
+    total=False,
+):
+    pass
+
+
+class AssetTransferFields(_TransactionBaseFields, _AssetTransferBaseFields, total=False):
+    pass
+
+
+class PaymentFields(_TransactionBaseFields, _PaymentBaseFields, total=False):
+    pass
+
+
+class AssetFreezeFields(_TransactionBaseFields, _AssetFreezeBaseFields, total=False):
+    pass
+
+
+class AssetConfigFields(_TransactionBaseFields, _AssetConfigBaseFields, total=False):
+    pass
+
+
+class ApplicationCallFields(_TransactionBaseFields, _ApplicationCallBaseFields, total=False):
+    pass
+
+
+class KeyRegistrationFields(_TransactionBaseFields, _KeyRegistrationBaseFields, total=False):
+    pass
+
+
+__all__ = [
+    "_ApplicationCallBaseFields",
+    "_ApplicationCallFields",
+    "_AssetConfigBaseFields",
+    "_AssetFreezeBaseFields",
+    "_AssetTransferBaseFields",
+    "_KeyRegistrationBaseFields",
+    "_PaymentBaseFields",
+    "_TransactionBaseFields",
+    "_TransactionCoreFields",
+    "_TransactionFields",
+    "ApplicationCallFields",
+    "AssetConfigFields",
+    "AssetFreezeFields",
+    "AssetTransferFields",
+    "KeyRegistrationFields",
+    "PaymentFields",
+]

algopy_testing/models/txn.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import typing
+from typing import TYPE_CHECKING, TypedDict, TypeVar
+
+if TYPE_CHECKING:
+    import algopy
+
+
+T = TypeVar("T")
+
+
+class TxnFields(TypedDict, total=False):
+    sender: algopy.Account
+    fee: algopy.UInt64
+    first_valid: algopy.UInt64
+    first_valid_time: algopy.UInt64
+    last_valid: algopy.UInt64
+    note: algopy.Bytes
+    lease: algopy.Bytes
+    receiver: algopy.Account
+    amount: algopy.UInt64
+    close_remainder_to: algopy.Account
+    vote_pk: algopy.Bytes
+    selection_pk: algopy.Bytes
+    vote_first: algopy.UInt64
+    vote_last: algopy.UInt64
+    vote_key_dilution: algopy.UInt64
+    type: algopy.Bytes
+    type_enum: algopy.UInt64
+    xfer_asset: algopy.Asset
+    asset_amount: algopy.UInt64
+    asset_sender: algopy.Account
+    asset_receiver: algopy.Account
+    asset_close_to: algopy.Account
+    group_index: algopy.UInt64
+    tx_id: algopy.Bytes
+    application_id: algopy.Application
+    on_completion: algopy.UInt64
+    num_app_args: algopy.UInt64
+    num_accounts: algopy.UInt64
+    approval_program: algopy.Bytes
+    clear_state_program: algopy.Bytes
+    rekey_to: algopy.Account
+    config_asset: algopy.Asset
+    config_asset_total: algopy.UInt64
+    config_asset_decimals: algopy.UInt64
+    config_asset_default_frozen: bool
+    config_asset_unit_name: algopy.Bytes
+    config_asset_name: algopy.Bytes
+    config_asset_url: algopy.Bytes
+    config_asset_metadata_hash: algopy.Bytes
+    config_asset_manager: algopy.Account
+    config_asset_reserve: algopy.Account
+    config_asset_freeze: algopy.Account
+    config_asset_clawback: algopy.Account
+    freeze_asset: algopy.Asset
+    freeze_asset_account: algopy.Account
+    freeze_asset_frozen: bool
+    num_assets: algopy.UInt64
+    num_applications: algopy.UInt64
+    global_num_uint: algopy.UInt64
+    global_num_byte_slice: algopy.UInt64
+    local_num_uint: algopy.UInt64
+    local_num_byte_slice: algopy.UInt64
+    extra_program_pages: algopy.UInt64
+    nonparticipation: bool
+    num_logs: algopy.UInt64
+    created_asset_id: algopy.Asset
+    created_application_id: algopy.Application
+    last_log: algopy.Bytes
+    state_proof_pk: algopy.Bytes
+    num_approval_program_pages: algopy.UInt64
+    num_clear_state_program_pages: algopy.UInt64
+    application_args: tuple[algopy.Bytes, ...]
+    accounts: tuple[algopy.Account, ...]
+    assets: tuple[algopy.Asset, ...]
+    applications: tuple[algopy.Application, ...]
+    logs: tuple[algopy.Bytes, ...]
+    approval_program_pages: tuple[algopy.Bytes, ...]
+    clear_state_program_pages: tuple[algopy.Bytes, ...]
+
+
+class _Txn:
+    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 __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."
+            )
+        active_txn = context.get_active_transaction()
+        if name in context._txn_fields and context._txn_fields[name] is not None:  # type: ignore[literal-required]
+            return context._txn_fields[name]  # type: ignore[literal-required]
+        elif active_txn:
+            return getattr(active_txn, self._map_fields(name))
+        else:
+            raise AttributeError(
+                f"'Txn' object has no value set for attribute named '{name}'. "
+                f"Use `context.patch_txn_fields({name}=your_value)` to set the value "
+                "in your test setup."
+            )
+
+
+Txn = _Txn()

algopy_testing/models/unsigned_builtins.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import typing
+
+if typing.TYPE_CHECKING:
+    import algopy
+
+
+class urange:  # noqa: N801
+    def __init__(self, *args: int | algopy.UInt64) -> None:
+        pass
+
+
+def uenumerate(_iterable: typing.Any) -> typing.Any:
+    pass