Merge branch 'master' into avm8

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Unreleased
 
+# 0.18.1
+
+## Fixed
+* ABI methods without a docstring now have their arguments in the output Contract object. ([#524](https://github.com/algorand/pyteal/pull/524))
+
+# 0.18.0
+
+## Added
+
+* ABI Methods will now parse the docstring for the method and set the description for any parameters that are described. ([#518](https://github.com/algorand/pyteal/pull/518))
+  * Note: the docstring must adhere to one of google, rst, numpy , or epy formatting styles.
+
+## Fixed
+* Subroutines annotated with a `TupleX` class are now invoked with an instance of that exact class, instead of the more general `Tuple` class ([#519](https://github.com/algorand/pyteal/pull/519))
+
 # 0.17.0
 
 ## Added

Makefile

@@ -2,7 +2,7 @@
 
 setup-development:
 	pip install -e .
-	pip install -r requirements.txt
+	pip install -r requirements.txt --upgrade
 
 setup-docs:
 	pip install -r docs/requirements.txt

docs/requirements.txt

@@ -3,3 +3,4 @@ sphinx-rtd-theme==1.0.0
 # dependencies from setup.py
 py-algorand-sdk>=1.9.0,<2.0.0
 semantic-version>=2.9.0,<3.0.0
+docstring-parser==0.14.1

examples/application/abi/algobank.json

@@ -6,28 +6,32 @@
             "args": [
                 {
                     "type": "pay",
-                    "name": "payment"
+                    "name": "payment",
+                    "desc": "A payment transaction containing the amount of Algos the user wishes to deposit. The receiver of this transaction must be this app's escrow account."
                 },
                 {
                     "type": "account",
-                    "name": "sender"
+                    "name": "sender",
+                    "desc": "An account that is opted into this app (or will opt in during this method call). The deposited funds will be recorded in this account's local state. This account must be the same as the sender of the `payment` transaction."
                 }
             ],
             "returns": {
                 "type": "void"
             },
-            "desc": "This method receives a payment from an account opted into this app and records it in their local state. The caller may opt into this app during this call."
+            "desc": "This method receives a payment from an account opted into this app and records it as a deposit.\nThe caller may opt into this app during this call."
         },
         {
             "name": "getBalance",
             "args": [
                 {
                     "type": "account",
-                    "name": "user"
+                    "name": "user",
+                    "desc": "The user whose balance you wish to look up. This user must be opted into this app."
                 }
             ],
             "returns": {
-                "type": "uint64"
+                "type": "uint64",
+                "desc": "The balance corresponding to the given user, in microAlgos."
             },
             "desc": "Lookup the balance of a user held by this app."
         },
@@ -36,17 +40,19 @@
             "args": [
                 {
                     "type": "uint64",
-                    "name": "amount"
+                    "name": "amount",
+                    "desc": "The amount of Algos requested to be withdraw, in microAlgos. This method will fail if this amount exceeds the amount of Algos held by this app for the method call sender."
                 },
                 {
                     "type": "account",
-                    "name": "recipient"
+                    "name": "recipient",
+                    "desc": "An account who will receive the withdrawn Algos. This may or may not be the same as the method call sender."
                 }
             ],
             "returns": {
                 "type": "void"
             },
-            "desc": "Withdraw an amount of Algos held by this app. The sender of this method call will be the source of the Algos, and the destination will be the `recipient` argument. This may or may not be the same as the sender's address. This method will fail if the amount of Algos requested to be withdrawn exceeds the amount of Algos held by this app for the sender. The Algos will be transferred to the recipient using an inner transaction whose fee is set to 0, meaning the caller's transaction must include a surplus fee to cover the inner transaction."
+            "desc": "Withdraw an amount of Algos held by this app.\nThe sender of this method call will be the source of the Algos, and the destination will be the `recipient` argument.\nThe Algos will be transferred to the recipient using an inner transaction whose fee is set to 0, meaning the caller's transaction must include a surplus fee to cover the inner transaction."
         }
     ],
     "networks": {}

examples/application/abi/algobank.py

@@ -41,10 +41,16 @@ def assert_sender_is_creator() -> Expr:
 
 @router.method(no_op=CallConfig.CALL, opt_in=CallConfig.CALL)
 def deposit(payment: abi.PaymentTransaction, sender: abi.Account) -> Expr:
-    """This method receives a payment from an account opted into this app and records it in
-    their local state.
+    """This method receives a payment from an account opted into this app and records it as a deposit.
 
     The caller may opt into this app during this call.
+
+    Args:
+        payment: A payment transaction containing the amount of Algos the user wishes to deposit.
+            The receiver of this transaction must be this app's escrow account.
+        sender: An account that is opted into this app (or will opt in during this method call).
+            The deposited funds will be recorded in this account's local state. This account must
+            be the same as the sender of the `payment` transaction.
     """
     return Seq(
         Assert(payment.get().sender() == sender.address()),
@@ -59,7 +65,14 @@ def deposit(payment: abi.PaymentTransaction, sender: abi.Account) -> Expr:
 
 @router.method
 def getBalance(user: abi.Account, *, output: abi.Uint64) -> Expr:
-    """Lookup the balance of a user held by this app."""
+    """Lookup the balance of a user held by this app.
+
+    Args:
+        user: The user whose balance you wish to look up. This user must be opted into this app.
+
+    Returns:
+        The balance corresponding to the given user, in microAlgos.
+    """
     return output.set(App.localGet(user.address(), Bytes("balance")))
 
 
@@ -68,14 +81,17 @@ def withdraw(amount: abi.Uint64, recipient: abi.Account) -> Expr:
     """Withdraw an amount of Algos held by this app.
 
     The sender of this method call will be the source of the Algos, and the destination will be
-    the `recipient` argument. This may or may not be the same as the sender's address.
-
-    This method will fail if the amount of Algos requested to be withdrawn exceeds the amount of
-    Algos held by this app for the sender.
+    the `recipient` argument.
 
     The Algos will be transferred to the recipient using an inner transaction whose fee is set
     to 0, meaning the caller's transaction must include a surplus fee to cover the inner
     transaction.
+
+    Args:
+        amount: The amount of Algos requested to be withdraw, in microAlgos. This method will fail
+            if this amount exceeds the amount of Algos held by this app for the method call sender.
+        recipient: An account who will receive the withdrawn Algos. This may or may not be the same
+            as the method call sender.
     """
     return Seq(
         # if amount is larger than App.localGet(Txn.sender(), Bytes("balance")), the subtraction

pyteal/ast/abi/tuple.py

@@ -224,7 +224,21 @@ def length_static(self) -> int:
         return len(self.value_specs)
 
     def new_instance(self) -> "Tuple":
-        return Tuple(self)
+        match self.length_static():
+            case 0:
+                return Tuple0()
+            case 1:
+                return Tuple1(self)
+            case 2:
+                return Tuple2(self)
+            case 3:
+                return Tuple3(self)
+            case 4:
+                return Tuple4(self)
+            case 5:
+                return Tuple5(self)
+            case _:
+                return Tuple(self)
 
     def annotation_type(self) -> "type[Tuple]":
         vtses = self.value_type_specs()