refactor: note that @subroutine is optional for contract methods

Author: boblat

docs/testing-guide/subroutines.md

@@ -18,6 +18,8 @@ context = ctx_manager.__enter__()
 
 The `@algopy.subroutine` decorator exposes contract methods for isolated testing within the Algorand Python Testing framework. This enables focused validation of core business logic without the overhead of full application deployment and execution.
 
+`@algopy.subroutine` decorator is optional for the methods in a contract which are not callable externally.
+
 ## Usage
 
 1. Decorate internal methods with `@algopy.subroutine`:
@@ -26,7 +28,7 @@ The `@algopy.subroutine` decorator exposes contract methods for isolated testing
 from algopy import subroutine, UInt64
 
 class MyContract:
-    @subroutine
+    @subroutine # optional
     def calculate_value(self, input: UInt64) -> UInt64:
         return input * UInt64(2)
 ```

examples/marketplace/contract.py

@@ -9,7 +9,6 @@
     gtxn,
     itxn,
     op,
-    subroutine,
 )
 from algopy.arc4 import abimethod
 
@@ -32,7 +31,6 @@ class DigitalMarketplace(ARC4Contract):
     def __init__(self) -> None:
         self.listings = BoxMap(ListingKey, ListingValue)
 
-    @subroutine
     def listings_box_mbr(self) -> UInt64:
         return (
             2_500
@@ -55,7 +53,6 @@ def listings_box_mbr(self) -> UInt64:
             * 400
         )
 
-    @subroutine
     def quantity_price(self, quantity: UInt64, price: UInt64, asset_decimals: UInt64) -> UInt64:
         amount_not_scaled_high, amount_not_scaled_low = op.mulw(price, quantity)
         scaling_factor_high, scaling_factor_low = op.expw(10, asset_decimals)

examples/simple_voting/contract.py

@@ -8,7 +8,6 @@
     Txn,
     UInt64,
     op,
-    subroutine,
 )
 
 VOTE_PRICE = 10_000
@@ -24,11 +23,9 @@ def __init__(self) -> None:
         )
         self.voted = LocalState(UInt64, key="voted", description="Tracks if an account has voted")
 
-    @subroutine
     def set_topic(self, topic: Bytes) -> None:
         self.topic.value = topic
 
-    @subroutine
     def vote(self, voter: Account) -> bool:
         assert op.Global.group_size == UInt64(2)
         assert op.GTxn.amount(1) == UInt64(VOTE_PRICE)
@@ -40,7 +37,6 @@ def vote(self, voter: Account) -> bool:
         self.voted[voter] = UInt64(1)
         return True
 
-    @subroutine
     def get_votes(self) -> UInt64:
         return self.votes.value
 

tests/artifacts/Arrays/data/StaticSizeContract.approval.teal

@@ -308,7 +308,7 @@ test_array_after_for@5:
     pushbytes "a"
     swap
     box_put
-    // tests/artifacts/Arrays/static_size.py:169
+    // tests/artifacts/Arrays/static_size.py:168
     // last_point = path[0]
     extract 0 144 // on error: index access is out of bounds
     dup
@@ -319,24 +319,24 @@ test_array_after_for@5:
     intc_2 // 8
     extract_uint64
     bury 6
-    // tests/artifacts/Arrays/static_size.py:170
+    // tests/artifacts/Arrays/static_size.py:169
     // length = UInt64()
     intc_0 // 0
     bury 5
-    // tests/artifacts/Arrays/static_size.py:171
+    // tests/artifacts/Arrays/static_size.py:170
     // for point_idx in urange(1, path.length):
     intc_1 // 1
     bury 3
 
 test_array_for_header@7:
-    // tests/artifacts/Arrays/static_size.py:171
+    // tests/artifacts/Arrays/static_size.py:170
     // for point_idx in urange(1, path.length):
     dig 2
     dig 8
     <
     bz test_array_after_for@15
     dig 1
-    // tests/artifacts/Arrays/static_size.py:172
+    // tests/artifacts/Arrays/static_size.py:171
     // point = path[point_idx]
     dig 3
     intc 4 // 144
@@ -349,45 +349,45 @@ test_array_for_header@7:
     intc_2 // 8
     extract_uint64
     bury 6
-    // tests/artifacts/Arrays/static_size.py:173
+    // tests/artifacts/Arrays/static_size.py:172
     // if point.x < last_point.x:
     dig 10
     b<
     bz test_array_else_body@10
-    // tests/artifacts/Arrays/static_size.py:174
+    // tests/artifacts/Arrays/static_size.py:173
     // dx = last_point.x.as_uint64() - point.x.as_uint64()
     dig 10
-    // tests/artifacts/Arrays/static_size.py:169
+    // tests/artifacts/Arrays/static_size.py:168
     // last_point = path[0]
     intc_0 // 0
-    // tests/artifacts/Arrays/static_size.py:174
+    // tests/artifacts/Arrays/static_size.py:173
     // dx = last_point.x.as_uint64() - point.x.as_uint64()
     extract_uint64
     swap
-    // tests/artifacts/Arrays/static_size.py:172
+    // tests/artifacts/Arrays/static_size.py:171
     // point = path[point_idx]
     intc_0 // 0
-    // tests/artifacts/Arrays/static_size.py:174
+    // tests/artifacts/Arrays/static_size.py:173
     // dx = last_point.x.as_uint64() - point.x.as_uint64()
     extract_uint64
     -
     bury 7
 
 test_array_after_if_else@11:
-    // tests/artifacts/Arrays/static_size.py:177
+    // tests/artifacts/Arrays/static_size.py:176
     // if point.y < last_point.y:
     dig 3
     dig 6
     <
     bz test_array_else_body@13
-    // tests/artifacts/Arrays/static_size.py:178
+    // tests/artifacts/Arrays/static_size.py:177
     // dy = last_point.y - point.y
     dig 5
     dig 4
     -
 
 test_array_after_if_else@14:
-    // tests/artifacts/Arrays/static_size.py:181
+    // tests/artifacts/Arrays/static_size.py:180
     // length += op.sqrt(dx * dx + dy * dy)
     dig 7
     dup
@@ -400,7 +400,7 @@ test_array_after_if_else@14:
     dig 5
     +
     bury 5
-    // tests/artifacts/Arrays/static_size.py:171
+    // tests/artifacts/Arrays/static_size.py:170
     // for point_idx in urange(1, path.length):
     dig 2
     intc_1 // 1
@@ -409,25 +409,25 @@ test_array_after_if_else@14:
     b test_array_for_header@7
 
 test_array_else_body@13:
-    // tests/artifacts/Arrays/static_size.py:180
+    // tests/artifacts/Arrays/static_size.py:179
     // dy = point.y - last_point.y
     dig 3
     dig 6
     -
     b test_array_after_if_else@14
 
 test_array_else_body@10:
-    // tests/artifacts/Arrays/static_size.py:172
+    // tests/artifacts/Arrays/static_size.py:171
     // point = path[point_idx]
     intc_0 // 0
-    // tests/artifacts/Arrays/static_size.py:176
+    // tests/artifacts/Arrays/static_size.py:175
     // dx = point.x.as_uint64() - last_point.x.as_uint64()
     extract_uint64
     dig 10
-    // tests/artifacts/Arrays/static_size.py:169
+    // tests/artifacts/Arrays/static_size.py:168
     // last_point = path[0]
     intc_0 // 0
-    // tests/artifacts/Arrays/static_size.py:176
+    // tests/artifacts/Arrays/static_size.py:175
     // dx = point.x.as_uint64() - last_point.x.as_uint64()
     extract_uint64
     -
@@ -842,7 +842,7 @@ sum_array_after_for@5:
 
 // tests.artifacts.Arrays.static_size.StaticSizeContract.test_arc4_bool[routing]() -> void:
 test_arc4_bool:
-    // tests/artifacts/Arrays/static_size.py:143
+    // tests/artifacts/Arrays/static_size.py:142
     // arr.append(arc4.Bool(Txn.sender == Txn.receiver))
     txn Sender
     txn Receiver
@@ -851,7 +851,7 @@ test_arc4_bool:
     intc_0 // 0
     uncover 2
     setbit
-    // tests/artifacts/Arrays/static_size.py:144
+    // tests/artifacts/Arrays/static_size.py:143
     // arr.append(arc4.Bool(Txn.sender != Txn.receiver))
     txn Sender
     txn Receiver
@@ -862,21 +862,21 @@ test_arc4_bool:
     setbit
     concat // on error: max array length exceeded
     dupn 2
-    // tests/artifacts/Arrays/static_size.py:147
+    // tests/artifacts/Arrays/static_size.py:146
     // dyn_arr.extend(arr)
     len
-    // tests/artifacts/Arrays/static_size.py:146
+    // tests/artifacts/Arrays/static_size.py:145
     // dyn_arr = arc4.DynamicArray[arc4.Bool]()
     bytec 4 // 0x0000
-    // tests/artifacts/Arrays/static_size.py:147
+    // tests/artifacts/Arrays/static_size.py:146
     // dyn_arr.extend(arr)
     dig 2
     uncover 2
     intc_2 // 8
     callsub dynamic_array_concat_bits
     dup
     cover 2
-    // tests/artifacts/Arrays/static_size.py:148
+    // tests/artifacts/Arrays/static_size.py:147
     // assert dyn_arr.length == 2, "expected correct length"
     dup
     intc_0 // 0
@@ -887,14 +887,14 @@ test_arc4_bool:
     pushint 2
     ==
     assert // expected correct length
-    // tests/artifacts/Arrays/static_size.py:149
+    // tests/artifacts/Arrays/static_size.py:148
     // assert dyn_arr.bytes.length == 3, "expected 3 bytes"
     dig 1
     len
     pushint 3
     ==
     assert // expected 3 bytes
-    // tests/artifacts/Arrays/static_size.py:150
+    // tests/artifacts/Arrays/static_size.py:149
     // assert dyn_arr[0] == (Txn.sender == Txn.receiver), "expected correct value at 0"
     dup
     assert // index access is out of bounds
@@ -912,7 +912,7 @@ test_arc4_bool:
     ==
     ==
     assert // expected correct value at 0
-    // tests/artifacts/Arrays/static_size.py:151
+    // tests/artifacts/Arrays/static_size.py:150
     // assert dyn_arr[1] == (Txn.sender != Txn.receiver), "expected correct value at 1"
     intc_1 // 1
     >
@@ -933,7 +933,7 @@ test_arc4_bool:
     intc_0 // 0
 
 test_arc4_bool_for_header@2:
-    // tests/artifacts/Arrays/static_size.py:154-156
+    // tests/artifacts/Arrays/static_size.py:153-155
     // # note: not supported currently
     // # arr2.extend(dyn_array)
     // for b in dyn_arr:
@@ -952,7 +952,7 @@ test_arc4_bool_for_header@2:
     uncover 2
     setbit
     dig 3
-    // tests/artifacts/Arrays/static_size.py:157
+    // tests/artifacts/Arrays/static_size.py:156
     // arr2.append(b)
     swap
     concat // on error: max array length exceeded
@@ -964,14 +964,14 @@ test_arc4_bool_for_header@2:
 
 test_arc4_bool_after_for@5:
     dig 1
-    // tests/artifacts/Arrays/static_size.py:158
+    // tests/artifacts/Arrays/static_size.py:157
     // assert arr2.length == 4, "expected correct length"
     dup
     len
     pushint 4
     ==
     assert // expected correct length
-    // tests/artifacts/Arrays/static_size.py:159
+    // tests/artifacts/Arrays/static_size.py:158
     // assert arr2[0] == (Txn.sender == Txn.receiver), "expected correct value at 0"
     dup
     extract 0 1 // on error: index access is out of bounds
@@ -982,7 +982,7 @@ test_arc4_bool_after_for@5:
     ==
     ==
     assert // expected correct value at 0
-    // tests/artifacts/Arrays/static_size.py:160
+    // tests/artifacts/Arrays/static_size.py:159
     // assert arr2[1] == (Txn.sender != Txn.receiver), "expected correct value at 1"
     dup
     extract 1 1 // on error: index access is out of bounds
@@ -993,7 +993,7 @@ test_arc4_bool_after_for@5:
     !=
     ==
     assert // expected correct value at 1
-    // tests/artifacts/Arrays/static_size.py:161
+    // tests/artifacts/Arrays/static_size.py:160
     // assert arr2[2] == (Txn.sender == Txn.receiver), "expected correct value at 2"
     dup
     extract 2 1 // on error: index access is out of bounds
@@ -1004,7 +1004,7 @@ test_arc4_bool_after_for@5:
     ==
     ==
     assert // expected correct value at 2
-    // tests/artifacts/Arrays/static_size.py:162
+    // tests/artifacts/Arrays/static_size.py:161
     // assert arr2[3] == (Txn.sender != Txn.receiver), "expected correct value at 3"
     extract 3 1 // on error: index access is out of bounds
     intc_0 // 0
@@ -1015,15 +1015,15 @@ test_arc4_bool_after_for@5:
     ==
     assert // expected correct value at 3
     dig 4
-    // tests/artifacts/Arrays/static_size.py:164
+    // tests/artifacts/Arrays/static_size.py:163
     // return arr.freeze()
     dup
     len
     bytec 4 // 0x0000
     cover 2
     intc_2 // 8
     callsub dynamic_array_concat_bits
-    // tests/artifacts/Arrays/static_size.py:140
+    // tests/artifacts/Arrays/static_size.py:139
     // @arc4.abimethod()
     bytec_1 // 0x151f7c75
     swap
@@ -1035,7 +1035,7 @@ test_arc4_bool_after_for@5:
 
 // tests.artifacts.Arrays.static_size.StaticSizeContract.xtra() -> uint64, uint64, bytes, bytes, bytes:
 xtra:
-    // tests/artifacts/Arrays/static_size.py:127
+    // tests/artifacts/Arrays/static_size.py:126
     // self.count += 1
     intc_0 // 0
     bytec_2 // "count"
@@ -1046,23 +1046,23 @@ xtra:
     bytec_2 // "count"
     dig 1
     app_global_put
-    // tests/artifacts/Arrays/static_size.py:129
+    // tests/artifacts/Arrays/static_size.py:128
     // a=Txn.num_app_args,
     txn NumAppArgs
-    // tests/artifacts/Arrays/static_size.py:131
+    // tests/artifacts/Arrays/static_size.py:130
     // c=Txn.sender,
     txn Sender
-    // tests/artifacts/Arrays/static_size.py:132
+    // tests/artifacts/Arrays/static_size.py:131
     // d=self.more(),
     callsub more
-    // tests/artifacts/Arrays/static_size.py:133
+    // tests/artifacts/Arrays/static_size.py:132
     // e=BigUInt(self.count),
     intc_0 // 0
     bytec_2 // "count"
     app_global_get_ex
     assert // check self.count exists
     itob
-    // tests/artifacts/Arrays/static_size.py:128-134
+    // tests/artifacts/Arrays/static_size.py:127-133
     // return Xtra(
     //     a=Txn.num_app_args,
     //     b=self.count,
@@ -1077,7 +1077,7 @@ xtra:
 
 // tests.artifacts.Arrays.static_size.StaticSizeContract.more() -> bytes:
 more:
-    // tests/artifacts/Arrays/static_size.py:138
+    // tests/artifacts/Arrays/static_size.py:137
     // return More(foo=arc4.UInt64(self.count + 1), bar=arc4.UInt64(self.count * self.count))
     intc_0 // 0
     bytec_2 // "count"