algokit-utils 3.0.0b10__py3-none-any.whl → 3.0.0b11__py3-none-any.whl

algokit_utils/algorand.py

@@ -58,6 +58,8 @@ class AlgorandClient:
 
         :param validity_window: The number of rounds between the first and last valid rounds
         :return: The `AlgorandClient` so method calls can be chained
+        :example:
+            >>> algorand = AlgorandClient.mainnet().set_default_validity_window(1000);
         """
         self._default_validity_window = validity_window
         return self
@@ -70,6 +72,9 @@ class AlgorandClient:
 
         :param signer: The signer to use, either a `TransactionSigner` or a `TransactionSignerAccountProtocol`
         :return: The `AlgorandClient` so method calls can be chained
+        :example:
+            >>> signer = SigningAccount(private_key=..., address=...)
+            >>> algorand = AlgorandClient.mainnet().set_default_signer(signer)
         """
         self._account_manager.set_default_signer(signer)
         return self
@@ -81,21 +86,31 @@ class AlgorandClient:
         :param sender: The sender address to use this signer for
         :param signer: The signer to sign transactions with for the given sender
         :return: The `AlgorandClient` so method calls can be chained
+        :example:
+            >>> signer = SigningAccount(private_key=..., address=...)
+            >>> algorand = AlgorandClient.mainnet().set_signer(signer.addr, signer.signer)
         """
         self._account_manager.set_signer(sender, signer)
         return self
 
-    def set_signer_account(self, signer: TransactionSignerAccountProtocol) -> typing_extensions.Self:
+    def set_signer_from_account(self, signer: TransactionSignerAccountProtocol) -> typing_extensions.Self:
         """
         Sets the default signer to use if no other signer is specified.
 
         :param signer: The signer to use, either a `TransactionSigner` or a `TransactionSignerAccountProtocol`
         :return: The `AlgorandClient` so method calls can be chained
+        :example:
+            >>> accountManager = AlgorandClient.mainnet()
+            >>> accountManager.set_signer_from_account(TransactionSignerAccount(address=..., signer=...))
+            >>> accountManager.set_signer_from_account(algosdk.LogicSigAccount(program, args))
+            >>> accountManager.set_signer_from_account(SigningAccount(private_key=..., address=...))
+            >>> accountManager.set_signer_from_account(MultisigAccount(metadata, signing_accounts))
+            >>> accountManager.set_signer_from_account(account)
         """
         self._account_manager.set_default_signer(signer)
         return self
 
-    def set_suggested_params(
+    def set_suggested_params_cache(
         self, suggested_params: SuggestedParams, until: float | None = None
     ) -> typing_extensions.Self:
         """
@@ -104,23 +119,32 @@ class AlgorandClient:
         :param suggested_params: The suggested params to use
         :param until: A timestamp until which to cache, or if not specified then the timeout is used
         :return: The `AlgorandClient` so method calls can be chained
+        :example:
+            >>> algorand = AlgorandClient.mainnet().set_suggested_params_cache(suggested_params, time.time() + 3.6e6)
         """
         self._cached_suggested_params = suggested_params
         self._cached_suggested_params_expiry = until or time.time() + self._cached_suggested_params_timeout
         return self
 
-    def set_suggested_params_timeout(self, timeout: int) -> typing_extensions.Self:
+    def set_suggested_params_cache_timeout(self, timeout: int) -> typing_extensions.Self:
         """
         Sets the timeout for caching suggested params.
 
         :param timeout: The timeout in milliseconds
         :return: The `AlgorandClient` so method calls can be chained
+        :example:
+            >>> algorand = AlgorandClient.mainnet().set_suggested_params_cache_timeout(10_000)
         """
         self._cached_suggested_params_timeout = timeout
         return self
 
     def get_suggested_params(self) -> SuggestedParams:
-        """Get suggested params for a transaction (either cached or from algod if the cache is stale or empty)"""
+        """
+        Get suggested params for a transaction (either cached or from algod if the cache is stale or empty)
+
+        :example:
+            >>> algorand = AlgorandClient.mainnet().get_suggested_params()
+        """
         if self._cached_suggested_params and (
             self._cached_suggested_params_expiry is None or self._cached_suggested_params_expiry > time.time()
         ):
@@ -132,7 +156,14 @@ class AlgorandClient:
         return copy.deepcopy(self._cached_suggested_params)
 
     def new_group(self) -> TransactionComposer:
-        """Start a new `TransactionComposer` transaction group"""
+        """
+        Start a new `TransactionComposer` transaction group
+
+        :example:
+            >>> composer = AlgorandClient.mainnet().new_group()
+            >>> result = await composer.add_transaction(payment).send()
+        """
+
         return TransactionComposer(
             algod=self.client.algod,
             get_signer=lambda addr: self.account.get_signer(addr),
@@ -142,36 +173,81 @@ class AlgorandClient:
 
     @property
     def client(self) -> ClientManager:
-        """Get clients, including algosdk clients and app clients."""
+        """
+        Get clients, including algosdk clients and app clients.
+
+        :example:
+            >>> clientManager = AlgorandClient.mainnet().client
+        """
         return self._client_manager
 
     @property
     def account(self) -> AccountManager:
-        """Get or create accounts that can sign transactions."""
+        """Get or create accounts that can sign transactions.
+
+        :example:
+            >>> accountManager = AlgorandClient.mainnet().account
+        """
         return self._account_manager
 
     @property
     def asset(self) -> AssetManager:
-        """Get or create assets."""
+        """
+        Get or create assets.
+
+        :example:
+            >>> assetManager = AlgorandClient.mainnet().asset
+        """
         return self._asset_manager
 
     @property
     def app(self) -> AppManager:
+        """
+        Get or create applications.
+
+        :example:
+            >>> appManager = AlgorandClient.mainnet().app
+        """
         return self._app_manager
 
     @property
     def app_deployer(self) -> AppDeployer:
-        """Get or create applications."""
+        """
+        Get or create applications.
+
+        :example:
+            >>> appDeployer = AlgorandClient.mainnet().app_deployer
+        """
         return self._app_deployer
 
     @property
     def send(self) -> AlgorandClientTransactionSender:
-        """Methods for sending a transaction and waiting for confirmation"""
+        """
+        Methods for sending a transaction and waiting for confirmation
+
+        :example:
+            >>> result = await AlgorandClient.mainnet().send.payment(
+            >>> PaymentParams(
+            >>>  sender="SENDERADDRESS",
+            >>>  receiver="RECEIVERADDRESS",
+            >>>  amount=AlgoAmount(algo-1)
+            >>> ))
+        """
         return self._transaction_sender
 
     @property
     def create_transaction(self) -> AlgorandClientTransactionCreator:
-        """Methods for building transactions"""
+        """
+        Methods for building transactions
+
+        :example:
+            >>> transaction = AlgorandClient.mainnet().create_transaction.payment(
+            >>> PaymentParams(
+            >>>  sender="SENDERADDRESS",
+            >>>  receiver="RECEIVERADDRESS",
+            >>>  amount=AlgoAmount(algo=1)
+            >>> ))
+        """
         return self._transaction_creator
 
     @staticmethod
@@ -180,6 +256,9 @@ class AlgorandClient:
         Returns an `AlgorandClient` pointing at default LocalNet ports and API token.
 
         :return: The `AlgorandClient`
+
+        :example:
+            >>> algorand = AlgorandClient.default_localnet()
         """
         return AlgorandClient(
             AlgoClientConfigs(
@@ -195,6 +274,9 @@ class AlgorandClient:
         Returns an `AlgorandClient` pointing at TestNet using AlgoNode.
 
         :return: The `AlgorandClient`
+
+        :example:
+            >>> algorand = AlgorandClient.testnet()
         """
         return AlgorandClient(
             AlgoClientConfigs(
@@ -210,6 +292,9 @@ class AlgorandClient:
         Returns an `AlgorandClient` pointing at MainNet using AlgoNode.
 
         :return: The `AlgorandClient`
+
+        :example:
+            >>> algorand = AlgorandClient.mainnet()
         """
         return AlgorandClient(
             AlgoClientConfigs(
@@ -230,6 +315,9 @@ class AlgorandClient:
         :param indexer: The indexer client to use
         :param kmd: The kmd client to use
         :return: The `AlgorandClient`
+
+        :example:
+            >>> algorand = AlgorandClient.from_clients(algod, indexer, kmd)
         """
         return AlgorandClient(AlgoSdkClients(algod=algod, indexer=indexer, kmd=kmd))
 
@@ -243,6 +331,9 @@ class AlgorandClient:
         Expects to be called from a Python environment.
 
         :return: The `AlgorandClient`
+
+        :example:
+            >>> algorand = AlgorandClient.from_environment()
         """
         return AlgorandClient(ClientManager.get_config_from_environment_or_localnet())
 
@@ -259,6 +350,9 @@ class AlgorandClient:
         :param indexer_config: The config to use for the indexer client
         :param kmd_config: The config to use for the kmd client
         :return: The `AlgorandClient`
+
+        :example:
+            >>> algorand = AlgorandClient.from_config(algod_config, indexer_config, kmd_config)
         """
         return AlgorandClient(
             AlgoClientConfigs(algod_config=algod_config, indexer_config=indexer_config, kmd_config=kmd_config)

algokit_utils/application_specification.py

@@ -7,7 +7,7 @@ warnings.warn(
     Use `from algokit_utils.applications.app_spec.arc32 import ...` to access Arc32 app spec instead.
     By default, the ARC52Contract is a recommended app spec to use, serving as a replacement
     for legacy 'ApplicationSpecification' class.
-    To convert legacy app specs to ARC52, use `arc32_to_arc52` function from algokit_utils.applications.utils.
+    To convert legacy app specs to ARC52, use `Arc56Contract.from_arc32`.
 """,
     DeprecationWarning,
     stacklevel=2,

algokit_utils/applications/abi.py

@@ -45,20 +45,18 @@ class ABIReturn:
     """Represents the return value from an ABI method call.
 
     Wraps the raw return value and decoded value along with any decode errors.
-
-    :ivar result: The ABIResult object containing the method call results
-    :ivar raw_value: The raw return value from the method call
-    :ivar value: The decoded return value from the method call
-    :ivar method: The ABI method definition
-    :ivar decode_error: The exception that occurred during decoding, if any
-    :ivar tx_info: The transaction info for the method call from raw algosdk `ABIResult`
     """
 
     raw_value: bytes | None = None
+    """The raw return value from the method call"""
     value: ABIValue | None = None
+    """The decoded return value from the method call"""
     method: AlgorandABIMethod | None = None
+    """The ABI method definition"""
     decode_error: Exception | None = None
+    """The exception that occurred during decoding, if any"""
     tx_info: dict[str, Any] | None = None
+    """The transaction info for the method call from raw algosdk `ABIResult`"""
 
     def __init__(self, result: ABIResult) -> None:
         self.decode_error = result.decode_error
@@ -269,11 +267,9 @@ def get_abi_struct_from_abi_tuple(
 
 @dataclass(kw_only=True, frozen=True)
 class BoxABIValue:
-    """Represents an ABI value stored in a box.
-
-    :ivar name: The name of the box
-    :ivar value: The ABI value stored in the box
-    """
+    """Represents an ABI value stored in a box."""
 
     name: BoxName
+    """The name of the box"""
     value: ABIValue
+    """The ABI value stored in the box"""

algokit_utils/applications/app_client.py

@@ -177,17 +177,16 @@ class AppClientCompilationResult:
     """Result of compiling an application's TEAL code.
 
     Contains the compiled approval and clear state programs along with optional compilation artifacts.
-
-    :ivar approval_program: The compiled approval program bytes
-    :ivar clear_state_program: The compiled clear state program bytes
-    :ivar compiled_approval: Optional compilation artifacts for approval program
-    :ivar compiled_clear: Optional compilation artifacts for clear state program
     """
 
     approval_program: bytes
+    """The compiled approval program bytes"""
     clear_state_program: bytes
+    """The compiled clear state program bytes"""
     compiled_approval: CompiledTeal | None = None
+    """Optional compilation artifacts for approval program"""
     compiled_clear: CompiledTeal | None = None
+    """Optional compilation artifacts for clear state program"""
 
 
 class AppClientCompilationParams(TypedDict, total=False):
@@ -209,52 +208,50 @@ MethodT = TypeVar("MethodT")
 
 @dataclass(kw_only=True, frozen=True)
 class CommonAppCallParams:
-    """Common configuration for app call transaction parameters
-
-    :ivar account_references: List of account addresses to reference
-    :ivar app_references: List of app IDs to reference
-    :ivar asset_references: List of asset IDs to reference
-    :ivar box_references: List of box references to include
-    :ivar extra_fee: Additional fee to add to transaction
-    :ivar lease: Transaction lease value
-    :ivar max_fee: Maximum fee allowed for transaction
-    :ivar note: Arbitrary note for the transaction
-    :ivar rekey_to: Address to rekey account to
-    :ivar sender: Sender address override
-    :ivar signer: Custom transaction signer
-    :ivar static_fee: Fixed fee for transaction
-    :ivar validity_window: Number of rounds valid
-    :ivar first_valid_round: First valid round number
-    :ivar last_valid_round: Last valid round number"""
+    """Common configuration for app call transaction parameters"""
 
     account_references: list[str] | None = None
+    """List of account addresses to reference"""
     app_references: list[int] | None = None
+    """List of app IDs to reference"""
     asset_references: list[int] | None = None
+    """List of asset IDs to reference"""
     box_references: list[BoxReference | BoxIdentifier] | None = None
+    """List of box references to include"""
     extra_fee: AlgoAmount | None = None
+    """Additional fee to add to transaction"""
     lease: bytes | None = None
+    """Transaction lease value"""
     max_fee: AlgoAmount | None = None
+    """Maximum fee allowed for transaction"""
     note: bytes | None = None
+    """Custom note for the transaction"""
     rekey_to: str | None = None
+    """Address to rekey account to"""
     sender: str | None = None
+    """Sender address override"""
     signer: TransactionSigner | None = None
+    """Custom transaction signer"""
     static_fee: AlgoAmount | None = None
+    """Fixed fee for transaction"""
     validity_window: int | None = None
+    """Number of rounds valid"""
     first_valid_round: int | None = None
+    """First valid round number"""
     last_valid_round: int | None = None
+    """Last valid round number"""
     on_complete: OnComplete | None = None
+    """Optional on complete action"""
 
 
 @dataclass(frozen=True)
 class AppClientCreateSchema:
-    """Schema for application creation.
-
-    :ivar extra_program_pages: Optional number of extra program pages
-    :ivar schema: Optional application creation schema
-    """
+    """Schema for application creation."""
 
     extra_program_pages: int | None = None
+    """Optional number of extra program pages"""
     schema: AppCreateSchema | None = None
+    """Optional application creation schema"""
 
 
 @dataclass(kw_only=True, frozen=True)
@@ -262,28 +259,25 @@ class CommonAppCallCreateParams(AppClientCreateSchema, CommonAppCallParams):
     """Common configuration for app create call transaction parameters."""
 
     on_complete: CreateOnComplete | None = None
+    """Optional on complete action"""
 
 
 @dataclass(kw_only=True, frozen=True)
 class FundAppAccountParams(CommonAppCallParams):
-    """Parameters for funding an application's account.
-
-    :ivar amount: Amount to fund
-    :ivar close_remainder_to: Optional address to close remainder to
-    """
+    """Parameters for funding an application's account."""
 
     amount: AlgoAmount
+    """Amount to fund"""
     close_remainder_to: str | None = None
+    """Optional address to close remainder to"""
 
 
 @dataclass(kw_only=True, frozen=True)
 class AppClientBareCallParams(CommonAppCallParams):
-    """Parameters for bare application calls.
-
-    :ivar args: Optional arguments
-    """
+    """Parameters for bare application calls."""
 
     args: list[bytes] | None = None
+    """Optional arguments"""
 
 
 @dataclass(frozen=True)
@@ -291,19 +285,17 @@ class AppClientBareCallCreateParams(CommonAppCallCreateParams):
     """Parameters for creating application with bare call."""
 
     on_complete: CreateOnComplete | None = None
+    """Optional on complete action"""
 
 
 @dataclass(kw_only=True, frozen=True)
 class BaseAppClientMethodCallParams(Generic[ArgsT, MethodT], CommonAppCallParams):
-    """Base parameters for application method calls.
-
-    :ivar method: Method to call
-    :ivar args: Optional arguments to pass to method
-    :ivar on_complete: Optional on complete action
-    """
+    """Base parameters for application method calls."""
 
     method: MethodT
+    """Method to call"""
     args: ArgsT | None = None
+    """Arguments to pass to the application method call"""
 
 
 @dataclass(kw_only=True, frozen=True)
@@ -321,6 +313,7 @@ class AppClientMethodCallCreateParams(AppClientCreateSchema, AppClientMethodCall
     """Parameters for creating application with method call"""
 
     on_complete: CreateOnComplete | None = None
+    """Optional on complete action"""
 
 
 class _AppClientStateMethods:
@@ -1261,13 +1254,21 @@ class AppClientParams:
     """Full parameters for creating an app client"""
 
     app_spec: Arc56Contract | Arc32Contract | str
+    """The application specification"""
     algorand: AlgorandClient
+    """The Algorand client"""
     app_id: int
+    """The application ID"""
     app_name: str | None = None
+    """The application name"""
     default_sender: str | None = None
+    """The default sender address"""
     default_signer: TransactionSigner | None = None
+    """The default transaction signer"""
     approval_source_map: SourceMap | None = None
+    """The approval source map"""
     clear_source_map: SourceMap | None = None
+    """The clear source map"""
 
 
 class AppClient:
@@ -1277,6 +1278,26 @@ class AppClient:
     methods for calling application methods, managing state, and handling transactions.
 
     :param params: Parameters for creating the app client
+
+    :example:
+        >>> params = AppClientParams(
+        ...     app_spec=Arc56Contract.from_json(app_spec_json),
+        ...     algorand=algorand,
+        ...     app_id=1234567890,
+        ...     app_name="My App",
+        ...     default_sender="SENDERADDRESS",
+        ...     default_signer=TransactionSigner(
+        ...         account="SIGNERACCOUNT",
+        ...         private_key="SIGNERPRIVATEKEY",
+        ...     ),
+        ...     approval_source_map=SourceMap(
+        ...         source="APPROVALSOURCE",
+        ...     ),
+        ...     clear_source_map=SourceMap(
+        ...         source="CLEARSOURCE",
+        ...     ),
+        ... )
+        >>> client = AppClient(params)
     """
 
     def __init__(self, params: AppClientParams) -> None:
@@ -1347,6 +1368,19 @@ class AppClient:
         """Get the method parameters builder.
 
         :return: The method parameters builder for this application
+
+        :example:
+            >>> # Create a transaction in the future using Algorand Client
+            >>> my_method_call = app_client.params.call(AppClientMethodCallParams(
+                    method='my_method',
+                    args=[123, 'hello']))
+            >>> # ...
+            >>> await algorand.send.AppMethodCall(my_method_call)
+            >>> # Define a nested transaction as an ABI argument
+            >>> my_method_call = app_client.params.call(AppClientMethodCallParams(
+                    method='my_method',
+                    args=[123, 'hello']))
+            >>> app_client.send.call(AppClientMethodCallParams(method='my_method2', args=[my_method_call]))
         """
         return self._params_accessor
 
@@ -1370,9 +1404,13 @@ class AppClient:
     def normalise_app_spec(app_spec: Arc56Contract | Arc32Contract | str) -> Arc56Contract:
         """Normalize an application specification to ARC-56 format.
 
-        :param app_spec: The application specification to normalize
+        :param app_spec: The application specification to normalize. Can be raw arc32 or arc56 json,
+            or an Arc32Contract or Arc56Contract instance
         :return: The normalized ARC-56 contract specification
         :raises ValueError: If the app spec format is invalid
+
+        :example:
+            >>> spec = AppClient.normalise_app_spec(app_spec_json)
         """
         if isinstance(app_spec, str):
             spec_dict = json.loads(app_spec)
@@ -1411,6 +1449,24 @@ class AppClient:
         :param clear_source_map: Optional clear program source map
         :return: A new AppClient instance
         :raises Exception: If no app ID is found for the network
+
+        :example:
+            >>> client = AppClient.from_network(
+            ...     app_spec=Arc56Contract.from_json(app_spec_json),
+            ...     algorand=algorand,
+            ...     app_name="My App",
+            ...     default_sender="SENDERADDRESS",
+            ...     default_signer=TransactionSigner(
+            ...         account="SIGNERACCOUNT",
+            ...         private_key="SIGNERPRIVATEKEY",
+            ...     ),
+            ...     approval_source_map=SourceMap(
+            ...         source="APPROVALSOURCE",
+            ...     ),
+            ...     clear_source_map=SourceMap(
+            ...         source="CLEARSOURCE",
+            ...     ),
+            ... )
         """
         network = algorand.client.network()
         app_spec = AppClient.normalise_app_spec(app_spec)
@@ -1471,6 +1527,14 @@ class AppClient:
         :param app_lookup_cache: Optional app lookup cache
         :return: A new AppClient instance
         :raises ValueError: If the app is not found for the creator and name
+
+        :example:
+            >>> client = AppClient.from_creator_and_name(
+            ...     creator_address="CREATORADDRESS",
+            ...     app_name="APPNAME",
+            ...     app_spec=Arc56Contract.from_json(app_spec_json),
+            ...     algorand=algorand,
+            ... )
         """
         app_spec_ = AppClient.normalise_app_spec(app_spec)
         app_lookup = app_lookup_cache or algorand.app_deployer.get_creator_apps_by_name(
@@ -1693,7 +1757,11 @@ class AppClient:
         :param default_signer: Optional new default signer
         :param approval_source_map: Optional new approval source map
         :param clear_source_map: Optional new clear source map
-        :return: A new AppClient instance with the specified parameters
+        :return: A new AppClient instance
+
+        :example:
+            >>> client = AppClient(params)
+            >>> cloned_client = client.clone(app_name="Cloned App", default_sender="NEW_SENDER")
         """
         return AppClient(
             AppClientParams(
@@ -1770,6 +1838,8 @@ class AppClient:
         """Get the application's global state.
 
         :return: The application's global state
+        :example:
+            >>> global_state = client.get_global_state()
         """
         return self._state_accessor.get_global_state()
 
@@ -1777,6 +1847,9 @@ class AppClient:
         """Get all box names for the application.
 
         :return: List of box names
+
+        :example:
+            >>> box_names = client.get_box_names()
         """
         return self._algorand.app.get_box_names(self._app_id)
 
@@ -1785,6 +1858,9 @@ class AppClient:
 
         :param name: The box identifier
         :return: The box value as bytes
+
+        :example:
+            >>> box_value = client.get_box_value(box_name)
         """
         return self._algorand.app.get_box_value(self._app_id, name)
 
@@ -1794,6 +1870,9 @@ class AppClient:
         :param name: The box identifier
         :param abi_type: The ABI type to decode as
         :return: The decoded box value
+
+        :example:
+            >>> box_value = client.get_box_value_from_abi_type(box_name, abi_type)
         """
         return self._algorand.app.get_box_value_from_abi_type(self._app_id, name, abi_type)
 
@@ -1802,6 +1881,9 @@ class AppClient:
 
         :param filter_func: Optional function to filter box names
         :return: List of box values
+
+        :example:
+            >>> box_values = client.get_box_values()
         """
         names = [n for n in self.get_box_names() if not filter_func or filter_func(n)]
         values = self._algorand.app.get_box_values(self.app_id, [n.name_raw for n in names])
@@ -1815,6 +1897,9 @@ class AppClient:
         :param abi_type: The ABI type to decode as
         :param filter_func: Optional function to filter box names
         :return: List of decoded box values
+
+        :example:
+            >>> box_values = client.get_box_values_from_abi_type(abi_type)
         """
         names = self.get_box_names()
         if filter_func:
@@ -1834,6 +1919,9 @@ class AppClient:
         :param params: The funding parameters
         :param send_params: Send parameters, defaults to None
         :return: The transaction result
+
+        :example:
+            >>> result = client.fund_app_account(params)
         """
         return self.send.fund_app_account(params, send_params)