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

algopy_testing/decorators/abimethod.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import functools
+import typing
+
+import algosdk
+
+from algopy_testing.constants import UINT64_SIZE
+from algopy_testing.utils import (
+    abi_return_type_annotation_for_arg,
+    abi_type_name_for_arg,
+    int_to_bytes,
+)
+
+if typing.TYPE_CHECKING:
+    import algopy
+
+    from algopy_testing.context import AlgopyTestContext
+
+
+if typing.TYPE_CHECKING:
+    import algopy
+
+
+_P = typing.ParamSpec("_P")
+_R = typing.TypeVar("_R")
+
+
+def _generate_arc4_signature(
+    fn: typing.Callable[_P, _R], args: tuple[typing.Any, ...]
+) -> algopy.Bytes:
+    import algopy
+
+    args_without_txns = [
+        arg
+        for arg in args
+        if not isinstance(arg, algopy.gtxn.TransactionBase)  # type: ignore[arg-type, unused-ignore]
+    ]
+    arg_types = [algosdk.abi.Argument(abi_type_name_for_arg(arg=arg)) for arg in args_without_txns]
+    return_type = algosdk.abi.Returns(
+        abi_return_type_annotation_for_arg(fn.__annotations__.get("return"))
+    )
+    method = algosdk.abi.Method(name=fn.__name__, args=arg_types, returns=return_type)
+    return algopy.Bytes(method.get_selector())
+
+
+def _extract_refs_from_args(
+    args: tuple[typing.Any, ...], kwargs: dict[str, typing.Any], ref_type: type
+) -> list[typing.Any]:
+    import algopy
+
+    refs: list[typing.Any] = []
+    for arg in list(args) + list(kwargs.values()):
+        match arg:
+            case algopy.gtxn.TransactionBase() if ref_type is algopy.gtxn.TransactionBase:
+                refs.append(arg)
+            case algopy.Account() if ref_type is algopy.Account:
+                refs.append(arg)
+            case algopy.Asset() if ref_type is algopy.Asset:
+                refs.append(arg)
+            case algopy.Application() if ref_type is algopy.Application:
+                refs.append(arg)
+            case (
+                algopy.String()
+                | algopy.BigUInt()
+                | algopy.UInt64()
+                | algopy.BigUInt()
+                | algopy.arc4.Bool()
+                | algopy.arc4.BigUIntN()
+                | algopy.arc4.BigUFixedNxM()
+                | algopy.arc4.StaticArray()
+                | algopy.arc4.DynamicArray()
+                | algopy.arc4.DynamicBytes()
+                | algopy.arc4.Address()
+                | algopy.arc4.String()
+                | algopy.arc4.Byte()
+                | algopy.arc4.UIntN()
+                | int()
+            ) if ref_type is algopy.Bytes:
+                refs.append(_extract_bytes(arg))
+            case _:
+                continue
+    return refs
+
+
+def _extract_bytes(value: object) -> algopy.Bytes:
+    import algopy
+
+    if isinstance(value, algopy.Bytes):
+        return value
+    if isinstance(
+        value,
+        (
+            algopy.String
+            | algopy.BigUInt
+            | algopy.arc4.Bool
+            | algopy.arc4.BigUIntN
+            | algopy.arc4.BigUFixedNxM
+            | algopy.arc4.StaticArray
+            | algopy.arc4.DynamicArray
+            | algopy.arc4.DynamicBytes
+            | algopy.arc4.Address
+            | algopy.arc4.String
+            | algopy.arc4.Byte
+            | algopy.arc4.UIntN
+        ),
+    ):
+        return value.bytes  # type: ignore[union-attr, unused-ignore]
+    if isinstance(value, (algopy.UInt64 | int)):
+        return algopy.Bytes(int_to_bytes(int(value), UINT64_SIZE))
+    raise ValueError(f"Unsupported type: {type(value).__name__}")
+
+
+def _extract_and_append_txn_to_context(
+    context: AlgopyTestContext,
+    args: tuple[typing.Any, ...],
+    kwargs: dict[str, typing.Any],
+    fn: typing.Callable[_P, _R],
+) -> None:
+    import algopy
+
+    context.add_transactions(_extract_refs_from_args(args, kwargs, algopy.gtxn.TransactionBase))
+
+    context.add_transactions(
+        [
+            context.any_application_call_transaction(
+                sender=context.default_creator,
+                app_id=context.default_application,
+                accounts=_extract_refs_from_args(args, kwargs, algopy.Account),
+                assets=_extract_refs_from_args(args, kwargs, algopy.Asset),
+                apps=_extract_refs_from_args(args, kwargs, algopy.Application),
+                app_args=[
+                    _generate_arc4_signature(fn, args),
+                    *_extract_refs_from_args(args, kwargs, algopy.Bytes),
+                ],
+                approval_program_pages=_extract_refs_from_args(args, kwargs, algopy.Bytes),
+                clear_state_program_pages=_extract_refs_from_args(args, kwargs, algopy.Bytes),
+            ),
+        ]
+    )
+    new_active_txn_index = len(context.get_transaction_group()) - 1
+    context.set_active_transaction_index(new_active_txn_index if new_active_txn_index > 0 else 0)
+
+
+@typing.overload
+def abimethod(fn: typing.Callable[_P, _R], /) -> typing.Callable[_P, _R]: ...
+
+
+@typing.overload
+def abimethod(
+    *,
+    name: str | None = None,
+    create: typing.Literal["allow", "require", "disallow"] = "disallow",
+    allow_actions: typing.Sequence[
+        algopy.OnCompleteAction
+        | typing.Literal[
+            "NoOp",
+            "OptIn",
+            "CloseOut",
+            # ClearState has its own program, so is not considered as part of ARC4 routing
+            "UpdateApplication",
+            "DeleteApplication",
+        ]
+    ] = ("NoOp",),
+    readonly: bool = False,
+    default_args: typing.Mapping[str, str | object] = {},
+) -> typing.Callable[[typing.Callable[_P, _R]], typing.Callable[_P, _R]]: ...
+
+
+def abimethod(  # noqa: PLR0913
+    fn: typing.Callable[_P, _R] | None = None,
+    *,
+    name: str | None = None,  # noqa: ARG001
+    create: typing.Literal["allow", "require", "disallow"] = "disallow",  # noqa: ARG001
+    allow_actions: typing.Sequence[  # noqa: ARG001
+        algopy.OnCompleteAction
+        | typing.Literal[
+            "NoOp",
+            "OptIn",
+            "CloseOut",
+            "UpdateApplication",
+            "DeleteApplication",
+        ]
+    ] = ("NoOp",),
+    readonly: bool = False,  # noqa: ARG001
+    default_args: typing.Mapping[str, str | object] | None = None,  # noqa: ARG001
+) -> typing.Callable[[typing.Callable[_P, _R]], typing.Callable[_P, _R]] | typing.Callable[_P, _R]:
+    def decorator(fn: typing.Callable[_P, _R]) -> typing.Callable[_P, _R]:
+        @functools.wraps(fn)
+        def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+            from algopy_testing import get_test_context
+
+            context = get_test_context()
+            if context is None or context._active_transaction_index is not None:
+                return fn(*args, **kwargs)
+
+            _extract_and_append_txn_to_context(context, args[1:], kwargs, fn)
+            return fn(*args, **kwargs)
+
+        return wrapper
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator

algopy_testing/decorators/baremethod.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import functools
+import typing
+
+if typing.TYPE_CHECKING:
+    import algopy
+
+    from algopy_testing.context import AlgopyTestContext
+
+
+_P = typing.ParamSpec("_P")
+_R = typing.TypeVar("_R")
+
+
+def _append_bare_txn_to_context(
+    context: AlgopyTestContext,
+) -> None:
+    context.add_transactions(
+        [
+            context.any_application_call_transaction(
+                sender=context.default_creator,
+                app_id=context.default_application,
+            ),
+        ]
+    )
+    context.set_active_transaction_index(len(context.get_transaction_group()) - 1)
+
+
+@typing.overload
+def baremethod(fn: typing.Callable[_P, _R], /) -> typing.Callable[_P, _R]: ...
+
+
+@typing.overload
+def baremethod(
+    *,
+    create: typing.Literal["allow", "require", "disallow"] = "disallow",
+    allow_actions: typing.Sequence[
+        algopy.OnCompleteAction
+        | typing.Literal[
+            "NoOp",
+            "OptIn",
+            "CloseOut",
+            "UpdateApplication",
+            "DeleteApplication",
+        ]
+    ] = ("NoOp",),
+) -> typing.Callable[[typing.Callable[_P, _R]], typing.Callable[_P, _R]]: ...
+
+
+def baremethod(
+    fn: typing.Callable[_P, _R] | None = None,
+    *,
+    create: typing.Literal["allow", "require", "disallow"] = "disallow",  # noqa: ARG001
+    allow_actions: typing.Sequence[  # noqa: ARG001
+        algopy.OnCompleteAction
+        | typing.Literal[
+            "NoOp",
+            "OptIn",
+            "CloseOut",
+            "UpdateApplication",
+            "DeleteApplication",
+        ]
+    ] = ("NoOp",),
+) -> typing.Callable[[typing.Callable[_P, _R]], typing.Callable[_P, _R]] | typing.Callable[_P, _R]:
+    def decorator(fn: typing.Callable[_P, _R]) -> typing.Callable[_P, _R]:
+        @functools.wraps(fn)
+        def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+            from algopy_testing import get_test_context
+
+            context = get_test_context()
+            if context is None or context._active_transaction_index is not None:
+                return fn(*args, **kwargs)
+
+            # Custom logic for baremethod can be added here
+            _append_bare_txn_to_context(context)
+            return fn(*args, **kwargs)
+
+        return wrapper
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator

algopy_testing/decorators/subroutine.py

@@ -0,0 +1,9 @@
+from collections.abc import Callable
+from typing import ParamSpec, TypeVar
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+
+def subroutine(sub: Callable[_P, _R]) -> Callable[_P, _R]:
+    return sub

algopy_testing/enums.py

@@ -0,0 +1,42 @@
+from enum import Enum, IntEnum, StrEnum
+
+
+class OnCompleteAction(Enum):
+    NoOp = 0
+    OptIn = 1
+    CloseOut = 2
+    ClearState = 3
+    UpdateApplication = 4
+    DeleteApplication = 5
+
+
+class TransactionType(IntEnum):
+    Payment = 0
+    KeyRegistration = 1
+    AssetConfig = 2
+    AssetTransfer = 3
+    AssetFreeze = 4
+    ApplicationCall = 5
+
+
+class ECDSA(Enum):
+    Secp256k1 = 0
+    Secp256r1 = 1
+
+
+class VrfVerify(Enum):
+    VrfAlgorand = 0
+
+
+class Base64(Enum):
+    URLEncoding = 0
+    StdEncoding = 1
+
+
+class EC(StrEnum):
+    """Available values for the `EC` enum"""
+
+    BN254g1 = "BN254g1"
+    BN254g2 = "BN254g2"
+    BLS12_381g1 = "BLS12_381g1"
+    BLS12_381g2 = "BLS12_381g2"

algopy_testing/gtxn.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import typing
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from algopy_testing.models.transactions import (
+    ApplicationCallFields,
+    AssetConfigFields,
+    AssetFreezeFields,
+    AssetTransferFields,
+    KeyRegistrationFields,
+    PaymentFields,
+    _ApplicationCallBaseFields,
+    _AssetConfigBaseFields,
+    _AssetFreezeBaseFields,
+    _AssetTransferBaseFields,
+    _KeyRegistrationBaseFields,
+    _PaymentBaseFields,
+    _TransactionBaseFields,
+)
+from algopy_testing.utils import txn_type_to_bytes
+
+if TYPE_CHECKING:
+    import algopy
+
+# NOTE: The actual access by group_index is not used, its there to comply with stubs
+# but user has no need to deal with that as we can reason on the index based
+# on position in gtxn group
+NULL_GTXN_GROUP_INDEX = -1
+
+
+@dataclass
+class _GroupTransaction:
+    _fields: dict[str, typing.Any] = field(default_factory=dict)
+
+    group_index: algopy.UInt64 | int = field(default=NULL_GTXN_GROUP_INDEX)
+
+    def __init__(self, group_index: algopy.UInt64 | int) -> None:
+        self.group_index = group_index
+        self._fields = {}
+
+
+class TransactionFields(
+    _TransactionBaseFields,
+    _AssetTransferBaseFields,
+    _PaymentBaseFields,
+    _ApplicationCallBaseFields,
+    _KeyRegistrationBaseFields,
+    _AssetConfigBaseFields,
+    _AssetFreezeBaseFields,
+    total=False,
+):
+    pass
+
+
+@dataclass
+class TransactionBase(_GroupTransaction):
+    def __init__(
+        self, group_index: algopy.UInt64 | int, **kwargs: typing.Unpack[_TransactionBaseFields]
+    ):
+        from algopy_testing import get_test_context
+
+        context = get_test_context()
+        try:
+            existing_txn = context._gtxns[group_index]
+        except IndexError:
+            existing_txn = None
+
+        if (
+            existing_txn
+            and isinstance(existing_txn, self.__class__)
+            or self.__class__ == Transaction
+        ):
+            self.__dict__.update(existing_txn.__dict__)
+        else:
+            super().__init__(group_index=group_index)
+            self._fields.update(kwargs)
+
+    def set(self, **kwargs: typing.Unpack[_TransactionBaseFields]) -> None:
+        """Updates inner transaction parameter values"""
+        self._fields.update(kwargs)
+
+    def __getattr__(self, name: str) -> object:
+        if name not in _TransactionBaseFields.__annotations__:
+            raise AttributeError(f"'{type(self)}' object has no attribute '{name}'")
+
+        return self._fields.get(name)
+
+
+@dataclass
+class AssetTransferTransaction(TransactionBase):
+    def __init__(
+        self, group_index: algopy.UInt64 | int, **kwargs: typing.Unpack[AssetTransferFields]
+    ):
+        super().__init__(group_index=group_index)
+        self._fields.update(kwargs)
+
+    def set(self, **kwargs: typing.Unpack[AssetTransferFields]) -> None:
+        """Updates inner transaction parameter values"""
+        self._fields.update(kwargs)
+
+    def __getattr__(self, name: str) -> typing.Any:
+        if name in AssetTransferFields.__annotations__:
+            return self._fields.get(name)
+
+        raise AttributeError(f"'{type(self)}' object has no attribute '{name}'")
+
+
+@dataclass
+class PaymentTransaction(TransactionBase):
+    def __init__(self, group_index: algopy.UInt64 | int, **kwargs: typing.Unpack[PaymentFields]):
+        import algopy
+
+        super().__init__(group_index=group_index)
+        self._fields.update(
+            {
+                "type": algopy.TransactionType.Payment,
+                "type_bytes": txn_type_to_bytes(int(algopy.TransactionType.Payment)),
+                **kwargs,
+            }
+        )
+
+    def __getattr__(self, name: str) -> typing.Any:
+        if name in PaymentFields.__annotations__:
+            return self._fields.get(name)
+
+        raise AttributeError(f"'{type(self)}' object has no attribute '{name}'")
+
+
+@dataclass
+class ApplicationCallTransaction(TransactionBase):
+    def __init__(
+        self, group_index: algopy.UInt64 | int, **kwargs: typing.Unpack[ApplicationCallFields]
+    ):
+        import algopy
+
+        super().__init__(group_index=group_index)
+        self._fields.update(
+            {
+                "type": algopy.TransactionType.ApplicationCall,
+                "type_bytes": txn_type_to_bytes(int(algopy.TransactionType.ApplicationCall)),
+                **kwargs,
+            }
+        )
+
+    def __getattr__(self, name: str) -> typing.Any:
+        if name in ApplicationCallFields.__annotations__:
+            return self._fields.get(name)
+
+        raise AttributeError(f"'{type(self)}' object has no attribute '{name}'")
+
+
+class KeyRegistrationTransaction(TransactionBase):
+    def __init__(
+        self, group_index: algopy.UInt64 | int, **kwargs: typing.Unpack[KeyRegistrationFields]
+    ):
+        import algopy
+
+        super().__init__(group_index=group_index)
+        self._fields.update(
+            {
+                "type": algopy.TransactionType.KeyRegistration,
+                "type_bytes": txn_type_to_bytes(int(algopy.TransactionType.KeyRegistration)),
+                **kwargs,
+            }
+        )
+
+    def __getattr__(self, name: str) -> typing.Any:
+        if name in KeyRegistrationFields.__annotations__:
+            return self._fields.get(name)
+
+        raise AttributeError(f"'{type(self)}' object has no attribute '{name}'")
+
+
+@dataclass
+class AssetConfigTransaction(TransactionBase):
+    def __init__(
+        self, group_index: algopy.UInt64 | int, **kwargs: typing.Unpack[AssetConfigFields]
+    ):
+        import algopy
+
+        super().__init__(group_index=group_index)
+        self._fields.update(
+            {
+                "type": algopy.TransactionType.AssetConfig,
+                "type_bytes": txn_type_to_bytes(int(algopy.TransactionType.AssetConfig)),
+                **kwargs,
+            }
+        )
+
+    def __getattr__(self, name: str) -> typing.Any:
+        if name in AssetConfigFields.__annotations__:
+            return self._fields.get(name)
+
+        raise AttributeError(f"'{type(self)}' object has no attribute '{name}'")
+
+
+@dataclass
+class AssetFreezeTransaction(TransactionBase):
+    def __init__(
+        self,
+        group_index: algopy.UInt64 | int,
+        **kwargs: typing.Unpack[AssetFreezeFields],
+    ):
+        import algopy
+
+        super().__init__(group_index=group_index)
+        self._fields.update(
+            {
+                "type": algopy.TransactionType.AssetFreeze,
+                "type_bytes": txn_type_to_bytes(int(algopy.TransactionType.AssetFreeze)),
+                **kwargs,
+            }
+        )
+
+    def __getattr__(self, name: str) -> typing.Any:
+        if name in AssetFreezeFields.__annotations__:
+            return self._fields.get(name)
+
+        raise AttributeError(f"'{type(self)}' object has no attribute '{name}'")
+
+
+@dataclass
+class Transaction(TransactionBase):
+    def __init__(
+        self,
+        group_index: algopy.UInt64 | int,
+        **kwargs: typing.Unpack[TransactionFields],
+    ):
+        super().__init__(group_index=group_index)
+        self._fields.update(kwargs)
+        # in case we still got no type after super attempts to load
+        # existing txn fro _gtxns then fail
+        if "type" not in self._fields:
+            raise ValueError("Transaction 'type' field is required")
+
+    def __getattr__(self, name: str) -> typing.Any:
+        if name in TransactionFields.__annotations__:
+            return self._fields.get(name)
+
+        raise AttributeError(f"'{type(self)}' object has no attribute '{name}'")
+
+
+__all__ = [
+    "ApplicationCallFields",
+    "ApplicationCallTransaction",
+    "AssetConfigFields",
+    "AssetConfigTransaction",
+    "AssetFreezeFields",
+    "AssetFreezeTransaction",
+    "AssetTransferFields",
+    "AssetTransferTransaction",
+    "KeyRegistrationFields",
+    "KeyRegistrationTransaction",
+    "NULL_GTXN_GROUP_INDEX",
+    "PaymentFields",
+    "PaymentTransaction",
+    "Transaction",
+    "TransactionBase",
+]