feat: add algopy.public alias for algopy.arc4.abimethod decorator

Author: boblat

docs/coverage.md

@@ -40,6 +40,7 @@ See which `algorand-python` stubs are implemented by the `algorand-python-testin
 | algopy.ensure_budget                        | Emulated            |
 | algopy.log                                  | Emulated            |
 | algopy.logicsig                             | Emulated            |
+| algopy.public                               | Emulated            |
 | algopy.size_of                              | Emulated            |
 | algopy.subroutine                           | Native              |
 | algopy.uenumerate                           | Native              |

docs/index.md

@@ -62,7 +62,7 @@ class VotingContract(algopy.ARC4Contract):
         )
         self.voted = algopy.LocalState(algopy.UInt64, key="voted", description="Tracks if an account has voted")
 
-    @arc4.abimethod
+    @algopy.public
     def set_topic(self, topic: arc4.String) -> None:
         self.topic.value = topic.bytes
 
@@ -79,7 +79,7 @@ class VotingContract(algopy.ARC4Contract):
         self.voted[algopy.Txn.sender] = algopy.UInt64(1)
         return arc4.Bool(True)
 
-    @arc4.abimethod(readonly=True)
+    @algopy.public(readonly=True)
     def get_votes(self) -> arc4.UInt64:
         return arc4.UInt64(self.votes.value)
 
@@ -141,9 +141,9 @@ This example demonstrates key aspects of testing with `algorand-python-testing`
 1. ARC4 Contract Features:
 
     - Use of `algopy.ARC4Contract` as the base class for the contract.
-    - ABI methods defined using the `@arc4.abimethod` decorator.
+    - ABI methods defined using the `@arc4.abimethod`, or its alias `@algopy.public`, decorator.
     - Use of ARC4-specific types like `arc4.String`, `arc4.Bool`, and `arc4.UInt64`.
-    - Readonly method annotation with `@arc4.abimethod(readonly=True)`.
+    - Readonly method annotation with `@arc4.abimethod(readonly=True)` or `@algopy.public(readonly=True)` .
 
 2. Testing ARC4 Contracts:
 

docs/testing-guide/concepts.md

@@ -61,5 +61,5 @@ For a full list of all public `algopy` types and their corresponding implementat
 
 ## Data Validation
 
-Algorand Python and the puya compiler have functionality to perform validation of transaction inputs via the `--validate-abi-args`, `--validate-abi-return` CLI arguments, `arc4.abimethod(validate_encoding=...)` decorator and `.validate()` methods. 
-The Algorand Python Testing library does *NOT* implement this validation behaviour, as you should test invalid inputs using an integrated test against a real Algorand network. 
+Algorand Python and the puya compiler have functionality to perform validation of transaction inputs via the `--validate-abi-args`, `--validate-abi-return` CLI arguments, `arc4.abimethod(validate_encoding=...)` decorator (or its alias, `algopy.public`) and `.validate()` methods.
+The Algorand Python Testing library does _NOT_ implement this validation behaviour, as you should test invalid inputs using an integrated test against a real Algorand network.

docs/testing-guide/contract-testing.md

@@ -1,6 +1,6 @@
 # Smart Contract Testing
 
-This guide provides an overview of how to test smart contracts using the Algorand Python SDK (`algopy`). It covers the basics of testing `ARC4Contract` and `Contract` classes, focusing on the `abimethod` and `baremethod` decorators.
+This guide provides an overview of how to test smart contracts using the Algorand Python SDK (`algopy`). It covers the basics of testing `ARC4Contract` and `Contract` classes, focusing on the `baremethod`, `abimethod` and `public` (an alias of `abimethod`) decorators.
 
 ![](https://mermaid.ink/img/pako:eNqVkrFugzAQhl_Fujnp1ImhEiJrJNREWeoOV9sNVsFG9iEVBd69R5w0JE2llsk2n7-7_-AAymsDGewDtpXYrqQT_GyKFwl5vfcBnRZlT5V3IjYYSCjvKKAiCa-JzXfrObyzgTqsxRpVZZ25YOX2nnRrIomCneZzpszLkllktu0f8ratrUKyjFsXCZ1K2gTH7i01_8dGUjOT_55YeLdUFVr3zRunf5b6R5hZoFnBq9cX72_Br_Cj8bl4vJCHaVucvowYxHk5Xg_sfPkY6SbbphDL5dMgQZu29n0U5DMJwzTVGyApySKZKFSNMXKVxPJYYAGNCQ1azX_VYboqgSrTcAcZLzWGDwnSjcxhR37TOwUZhc4sIPhuX0H2jnXkXddqrrCyyKNpTqfjF5m74B8?type=png)
 
@@ -24,7 +24,7 @@ context = ctx_manager.__enter__()
 
 Subclasses of `algopy.ARC4Contract` are **required** to be instantiated with an active test context. As part of instantiation, the test context will automatically create a matching `algopy.Application` object instance.
 
-Within the class implementation, methods decorated with `algopy.arc4.abimethod` and `algopy.arc4.baremethod` will automatically assemble an `algopy.gtxn.ApplicationCallTransaction` to emulate the AVM application call. This behaviour can be overridden by setting the transaction group manually as part of test setup; this is done via implicit invocation of the `algopy_testing.context.any_application()` _value generator_ (refer to the [API](../api.md) for more details).
+Within the class implementation, methods decorated with `algopy.arc4.abimethod` (or its alias, `algopy.public`) and `algopy.arc4.baremethod` will automatically assemble an `algopy.gtxn.ApplicationCallTransaction` to emulate the AVM application call. This behaviour can be overridden by setting the transaction group manually as part of test setup; this is done via implicit invocation of the `algopy_testing.context.any_application()` _value generator_ (refer to the [API](../api.md) for more details).
 
 ```{testcode}
 class SimpleVotingContract(algopy.ARC4Contract):
@@ -42,14 +42,14 @@ class SimpleVotingContract(algopy.ARC4Contract):
         self.topic.value = initial_topic
         self.votes.value = algopy.UInt64(0)
 
-    @algopy.arc4.abimethod
+    @algopy.public
     def vote(self) -> algopy.UInt64:
         assert self.voted[algopy.Txn.sender] == algopy.UInt64(0), "Account has already voted"
         self.votes.value += algopy.UInt64(1)
         self.voted[algopy.Txn.sender] = algopy.UInt64(1)
         return self.votes.value
 
-    @algopy.arc4.abimethod(readonly=True)
+    @algopy.public(readonly=True)
     def get_votes(self) -> algopy.UInt64:
         return self.votes.value
 
@@ -74,7 +74,7 @@ assert contract.topic.value == initial_topic
 assert contract.votes.value == algopy.UInt64(0)
 
 # Act - Vote
-# The method `.vote()` is decorated with `algopy.arc4.abimethod`, which means it will assemble a transaction to emulate the AVM application call
+# The method `.vote()` is decorated with `algopy.public`, an alias of `algopy.arc4.abimethod`, which means it will assemble a transaction to emulate the AVM application call
 result = contract.vote()
 
 # Assert - you can access the corresponding auto generated application call transaction via test context

docs/testing-guide/transactions.md

@@ -143,7 +143,7 @@ When testing smart contracts, to stay consistent with AVM, the framework _does n
 
 ```{testcode}
 class MyContract(algopy.ARC4Contract):
-    @algopy.arc4.abimethod
+    @algopy.public
     def pay_via_itxn(self, asset: algopy.Asset) -> None:
         algopy.itxn.Payment(
             receiver=algopy.Txn.sender,
@@ -180,7 +180,7 @@ first_payment_txn = first_itxn_group.payment(0)
 
 In this example, we define a contract method `pay_via_itxn` that creates and submits an inner payment transaction. The test context automatically captures and stores the inner transactions submitted by the contract method.
 
-Note that we don't need to wrap the execution in a `create_group` context manager because the method is decorated with `@algopy.arc4.abimethod`, which automatically creates a transaction group for the method. The `create_group` context manager is only needed when you want to create more complex transaction groups or patch transaction fields for various transaction-related opcodes in AVM.
+Note that we don't need to wrap the execution in a `create_group` context manager because the method is decorated with `@algopy.public`, an alias of `@algopy.arc4.abimethod`, which automatically creates a transaction group for the method. The `create_group` context manager is only needed when you want to create more complex transaction groups or patch transaction fields for various transaction-related opcodes in AVM.
 
 To access the submitted inner transactions:
 

examples/proof_of_attendance/contract.py

@@ -8,12 +8,12 @@ def __init__(self) -> None:
         self.total_attendees = algopy.UInt64(0)
         self.box_map = algopy.BoxMap(algopy.Bytes, algopy.UInt64)
 
-    @algopy.arc4.abimethod(create="require")
+    @algopy.public(create="require")
     def init(self, max_attendees: algopy.UInt64) -> None:
         assert algopy.Txn.sender == algopy.Global.creator_address, "Only creator can initialize"
         self.max_attendees = max_attendees
 
-    @algopy.arc4.abimethod()
+    @algopy.public()
     def confirm_attendance(self) -> None:
         assert self.total_attendees < self.max_attendees, "Max attendees reached"
 
@@ -25,7 +25,7 @@ def confirm_attendance(self) -> None:
 
         algopy.op.Box.put(algopy.Txn.sender.bytes, algopy.op.itob(minted_asset.id))
 
-    @algopy.arc4.abimethod()
+    @algopy.public()
     def confirm_attendance_with_box(self) -> None:
         assert self.total_attendees < self.max_attendees, "Max attendees reached"
 
@@ -38,7 +38,7 @@ def confirm_attendance_with_box(self) -> None:
 
         box.value = minted_asset.id
 
-    @algopy.arc4.abimethod()
+    @algopy.public()
     def confirm_attendance_with_box_ref(self) -> None:
         assert self.total_attendees < self.max_attendees, "Max attendees reached"
 
@@ -51,7 +51,7 @@ def confirm_attendance_with_box_ref(self) -> None:
 
         box_ref.value = algopy.op.itob(minted_asset.id)
 
-    @algopy.arc4.abimethod()
+    @algopy.public()
     def confirm_attendance_with_box_map(self) -> None:
         assert self.total_attendees < self.max_attendees, "Max attendees reached"
 
@@ -63,33 +63,33 @@ def confirm_attendance_with_box_map(self) -> None:
 
         self.box_map[algopy.Txn.sender.bytes] = minted_asset.id
 
-    @algopy.arc4.abimethod(readonly=True)
+    @algopy.public(readonly=True)
     def get_poa_id(self) -> algopy.UInt64:
         poa_id, exists = algopy.op.Box.get(algopy.Txn.sender.bytes)
         assert exists, "POA not found"
         return algopy.op.btoi(poa_id)
 
-    @algopy.arc4.abimethod(readonly=True)
+    @algopy.public(readonly=True)
     def get_poa_id_with_box(self) -> algopy.UInt64:
         box = algopy.Box(algopy.UInt64, key=algopy.Txn.sender.bytes)
         poa_id, exists = box.maybe()
         assert exists, "POA not found"
         return poa_id
 
-    @algopy.arc4.abimethod(readonly=True)
+    @algopy.public(readonly=True)
     def get_poa_id_with_box_ref(self) -> algopy.UInt64:
         box_ref = algopy.Box(algopy.Bytes, key=algopy.Txn.sender.bytes)
         poa_id, exists = box_ref.maybe()
         assert exists, "POA not found"
         return algopy.op.btoi(poa_id)
 
-    @algopy.arc4.abimethod(readonly=True)
+    @algopy.public(readonly=True)
     def get_poa_id_with_box_map(self) -> algopy.UInt64:
         poa_id, exists = self.box_map.maybe(algopy.Txn.sender.bytes)
         assert exists, "POA not found"
         return poa_id
 
-    @algopy.arc4.abimethod()
+    @algopy.public()
     def claim_poa(self, opt_in_txn: algopy.gtxn.AssetTransferTransaction) -> None:
         poa_id, exists = algopy.op.Box.get(algopy.Txn.sender.bytes)
         assert exists, "POA not found, attendance validation failed!"
@@ -108,7 +108,7 @@ def claim_poa(self, opt_in_txn: algopy.gtxn.AssetTransferTransaction) -> None:
             algopy.op.btoi(poa_id),
         )
 
-    @algopy.arc4.abimethod()
+    @algopy.public()
     def claim_poa_with_box(self, opt_in_txn: algopy.gtxn.AssetTransferTransaction) -> None:
         box = algopy.Box(algopy.UInt64, key=algopy.Txn.sender.bytes)
         poa_id, exists = box.maybe()
@@ -128,7 +128,7 @@ def claim_poa_with_box(self, opt_in_txn: algopy.gtxn.AssetTransferTransaction) -
             poa_id,
         )
 
-    @algopy.arc4.abimethod()
+    @algopy.public()
     def claim_poa_with_box_ref(self, opt_in_txn: algopy.gtxn.AssetTransferTransaction) -> None:
         box_ref = algopy.Box(algopy.Bytes, key=algopy.Txn.sender.bytes)
         poa_id, exists = box_ref.maybe()
@@ -148,7 +148,7 @@ def claim_poa_with_box_ref(self, opt_in_txn: algopy.gtxn.AssetTransferTransactio
             algopy.op.btoi(poa_id),
         )
 
-    @algopy.arc4.abimethod()
+    @algopy.public()
     def claim_poa_with_box_map(self, opt_in_txn: algopy.gtxn.AssetTransferTransaction) -> None:
         poa_id, exists = self.box_map.maybe(algopy.Txn.sender.bytes)
         assert exists, "POA not found, attendance validation failed!"

src/_algopy_testing/__init__.py

@@ -1,3 +1,4 @@
+# ruff: noqa: I001
 from _algopy_testing import arc4, gtxn, itxn
 from _algopy_testing.context import AlgopyTestContext
 from _algopy_testing.context_helpers.context_storage import algopy_testing_context
@@ -24,6 +25,9 @@
 from _algopy_testing.value_generators.arc4 import ARC4ValueGenerator
 from _algopy_testing.value_generators.avm import AVMValueGenerator
 from _algopy_testing.value_generators.txn import TxnValueGenerator
+from _algopy_testing.decorators.arc4 import (
+    abimethod as public,
+)
 
 __all__ = [
     "ARC4Contract",
@@ -60,6 +64,7 @@
     "gtxn",
     "itxn",
     "logicsig",
+    "public",
     "subroutine",
     "uenumerate",
     "urange",

src/algopy/__init__.py

@@ -1,3 +1,4 @@
+# ruff: noqa: I001
 from _algopy_testing.compiled import (
     CompiledContract,
     CompiledLogicSig,
@@ -33,6 +34,9 @@
 from _algopy_testing.utilities import OpUpFeeSource, ensure_budget, log, size_of
 
 from . import arc4, gtxn, itxn, op
+from _algopy_testing.decorators.arc4 import (
+    abimethod as public,
+)
 
 __all__ = [
     "ARC4Contract",
@@ -76,6 +80,7 @@
     "log",
     "logicsig",
     "op",
+    "public",
     "size_of",
     "subroutine",
     "uenumerate",

tests/arc4/test_abi_call.py

@@ -4,12 +4,12 @@
 import pytest
 from _algopy_testing import AlgopyTestContext, algopy_testing_context
 from _algopy_testing.itxn import ApplicationCallInnerTransaction
-from algopy import ARC4Contract, arc4
+from algopy import ARC4Contract, arc4, public
 from pytest_mock import MockerFixture
 
 
 class Logger(ARC4Contract):
-    @arc4.abimethod
+    @public
     def echo(self, value: arc4.String) -> arc4.String:
         return "echo: " + value
 

tests/models/test_contract.py

@@ -11,7 +11,6 @@
 
 
 class ContractTxnInit(algopy.Contract):
-
     def __init__(self) -> None:
         self.arg1 = algopy.Txn.app_args(0) if algopy.Txn.num_app_args else algopy.Bytes()
         self.creator = algopy.Txn.sender
@@ -32,14 +31,13 @@ class ContractARC4Create(
         local_uints=7,
     ),
 ):
-
     def __init__(self) -> None:
         self.creator = algopy.Txn.sender
         self._name = algopy.String("name")
         self._scratch_slots = algopy.UInt64()
         self._state_totals = algopy.UInt64()
 
-    @algopy.arc4.abimethod(create="require")
+    @algopy.public(create="require")
     def create(self, val: algopy.UInt64) -> None:
         self.arg1 = val
         assert algopy.Global.current_application_id.global_num_bytes == 4