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

algokit_utils/assets/asset_manager.py

@@ -19,63 +19,58 @@ __all__ = ["AccountAssetInformation", "AssetInformation", "AssetManager", "BulkA
 
 @dataclass(kw_only=True, frozen=True)
 class AccountAssetInformation:
-    """Information about an account's holding of a particular asset.
-
-    :ivar asset_id: The ID of the asset
-    :ivar balance: The amount of the asset held by the account
-    :ivar frozen: Whether the asset is frozen for this account
-    :ivar round: The round this information was retrieved at
-    """
+    """Information about an account's holding of a particular asset."""
 
     asset_id: int
+    """The ID of the asset"""
     balance: int
+    """The amount of the asset held by the account"""
     frozen: bool
+    """Whether the asset is frozen for this account"""
     round: int
+    """The round this information was retrieved at"""
 
 
 @dataclass(kw_only=True, frozen=True)
 class AssetInformation:
-    """Information about an Algorand Standard Asset (ASA).
-
-    :ivar asset_id: The ID of the asset
-    :ivar creator: The address of the account that created the asset
-    :ivar total: The total amount of the smallest divisible units that were created of the asset
-    :ivar decimals: The amount of decimal places the asset was created with
-    :ivar default_frozen: Whether the asset was frozen by default for all accounts, defaults to None
-    :ivar manager: The address of the optional account that can manage the configuration of the asset and destroy it,
-        defaults to None
-    :ivar reserve: The address of the optional account that holds the reserve (uncirculated supply) units of the asset,
-        defaults to None
-    :ivar freeze: The address of the optional account that can be used to freeze or unfreeze holdings of this asset,
-        defaults to None
-    :ivar clawback: The address of the optional account that can clawback holdings of this asset from any account,
-        defaults to None
-    :ivar unit_name: The optional name of the unit of this asset (e.g. ticker name), defaults to None
-    :ivar unit_name_b64: The optional name of the unit of this asset as bytes, defaults to None
-    :ivar asset_name: The optional name of the asset, defaults to None
-    :ivar asset_name_b64: The optional name of the asset as bytes, defaults to None
-    :ivar url: Optional URL where more information about the asset can be retrieved, defaults to None
-    :ivar url_b64: Optional URL where more information about the asset can be retrieved as bytes, defaults to None
-    :ivar metadata_hash: 32-byte hash of some metadata that is relevant to the asset and/or asset holders,
-        defaults to None
-    """
+    """Information about an Algorand Standard Asset (ASA)."""
 
     asset_id: int
+    """The ID of the asset"""
     creator: str
+    """The address of the account that created the asset"""
     total: int
+    """The total amount of the smallest divisible units that were created of the asset"""
     decimals: int
+    """The amount of decimal places the asset was created with"""
     default_frozen: bool | None = None
+    """Whether the asset was frozen by default for all accounts, defaults to None"""
     manager: str | None = None
+    """The address of the optional account that can manage the configuration of the asset and destroy it,
+        defaults to None"""
     reserve: str | None = None
+    """The address of the optional account that holds the reserve (uncirculated supply) units of the asset,
+        defaults to None"""
     freeze: str | None = None
+    """The address of the optional account that can be used to freeze or unfreeze holdings of this asset,
+        defaults to None"""
     clawback: str | None = None
+    """The address of the optional account that can clawback holdings of this asset from any account,
+        defaults to None"""
     unit_name: str | None = None
+    """The optional name of the unit of this asset (e.g. ticker name), defaults to None"""
     unit_name_b64: bytes | None = None
+    """The optional name of the unit of this asset as bytes, defaults to None"""
     asset_name: str | None = None
+    """The optional name of the asset, defaults to None"""
     asset_name_b64: bytes | None = None
+    """The optional name of the asset as bytes, defaults to None"""
     url: str | None = None
+    """The optional URL where more information about the asset can be retrieved, defaults to None"""
     url_b64: bytes | None = None
+    """The optional URL where more information about the asset can be retrieved as bytes, defaults to None"""
     metadata_hash: bytes | None = None
+    """The 32-byte hash of some metadata that is relevant to the asset and/or asset holders, defaults to None"""
 
 
 @dataclass(kw_only=True, frozen=True)
@@ -87,7 +82,9 @@ class BulkAssetOptInOutResult:
     """
 
     asset_id: int
+    """The ID of the asset opted into / out of"""
     transaction_id: str
+    """The transaction ID of the resulting opt in / out"""
 
 
 class AssetManager:
@@ -95,6 +92,9 @@ class AssetManager:
 
     :param algod_client: An algod client
     :param new_group: A function that creates a new TransactionComposer transaction group
+
+    :example:
+        >>> asset_manager = AssetManager(algod_client)
     """
 
     def __init__(self, algod_client: algod.AlgodClient, new_group: Callable[[], TransactionComposer]):
@@ -106,6 +106,10 @@ class AssetManager:
 
         :param asset_id: The ID of the asset
         :return: The asset information
+
+        :example:
+            >>> asset_manager = AssetManager(algod_client)
+            >>> asset_info = asset_manager.get_by_id(1234567890)
         """
         asset = self._algod.asset_info(asset_id)
         assert isinstance(asset, dict)
@@ -138,6 +142,10 @@ class AssetManager:
         :param sender: The address of the sender/account to look up
         :param asset_id: The ID of the asset to return a holding for
         :return: The account asset holding information
+
+        :example:
+            >>> asset_manager = AssetManager(algod_client)
+            >>> account_asset_info = asset_manager.get_account_information(sender, asset_id)
         """
         address = self._get_address_from_sender(sender)
         info = self._algod.account_asset_info(address, asset_id)
@@ -182,6 +190,10 @@ class AssetManager:
         :param last_valid_round: The last valid round to include in the transaction, defaults to None
         :param send_params: The send parameters to use for the transaction, defaults to None
         :return: An array of records matching asset ID to transaction ID of the opt in
+
+        :example:
+            >>> asset_manager = AssetManager(algod_client)
+            >>> results = asset_manager.bulk_opt_in(account, asset_ids)
         """
         results: list[BulkAssetOptInOutResult] = []
         sender = self._get_address_from_sender(account)
@@ -249,6 +261,10 @@ class AssetManager:
         :param send_params: The send parameters to use for the transaction, defaults to None
         :raises ValueError: If ensure_zero_balance is True and account has non-zero balance or is not opted in
         :return: An array of records matching asset ID to transaction ID of the opt out
+
+        :example:
+            >>> asset_manager = AssetManager(algod_client)
+            >>> results = asset_manager.bulk_opt_out(account, asset_ids)
         """
         results: list[BulkAssetOptInOutResult] = []
         sender = self._get_address_from_sender(account)

algokit_utils/clients/client_manager.py

@@ -64,10 +64,15 @@ class NetworkDetail:
     """
 
     is_testnet: bool
+    """Whether the network is a testnet"""
     is_mainnet: bool
+    """Whether the network is a mainnet"""
     is_localnet: bool
+    """Whether the network is a localnet"""
     genesis_id: str
+    """The genesis ID of the network"""
     genesis_hash: str
+    """The genesis hash of the network"""
 
 
 def _get_config_from_environment(environment_prefix: str) -> AlgoClientNetworkConfig:
@@ -88,6 +93,17 @@ class ClientManager:
 
     :param clients_or_configs: Either client instances or client configurations
     :param algorand_client: AlgorandClient instance
+
+    :example:
+        >>> # Algod only
+        >>> client_manager = ClientManager(algod_client)
+        >>> # Algod and Indexer
+        >>> client_manager = ClientManager(algod_client, indexer_client)
+        >>> # Algod config only
+        >>> client_manager = ClientManager(ClientManager.get_algod_config_from_environment())
+        >>> # Algod and Indexer config
+        >>> client_manager = ClientManager(ClientManager.get_algod_config_from_environment(),
+        ...     ClientManager.get_indexer_config_from_environment())
     """
 
     def __init__(self, clients_or_configs: AlgoClientConfigs | AlgoSdkClients, algorand_client: AlgorandClient):
@@ -151,6 +167,10 @@ class ClientManager:
         """Get details about the connected Algorand network.
 
         :return: Network details including type and genesis information
+
+        :example:
+            >>> client_manager = ClientManager(algod_client)
+            >>> network_detail = client_manager.network()
         """
         if self._suggested_params is None:
             self._suggested_params = self._algod.suggested_params()
@@ -417,6 +437,9 @@ class ClientManager:
 
         :param genesis_id: Genesis ID to check
         :return: True if genesis ID indicates a local network
+
+        :example:
+            >>> ClientManager.genesis_id_is_localnet("devnet-v1")
         """
         return genesis_id in ["devnet-v1", "sandnet-v1", "dockernet-v1"]
 
@@ -442,6 +465,14 @@ class ClientManager:
         :param app_lookup_cache: Optional app lookup cache
         :raises ValueError: If no Algorand client is configured
         :return: Typed application client instance
+
+        :example:
+            >>> client_manager = ClientManager(algod_client)
+            >>> typed_app_client = client_manager.get_typed_app_client_by_creator_and_name(
+            ...     typed_client=MyAppClient,
+            ...     creator_address="creator_address",
+            ...     app_name="app_name",
+            ... )
         """
         if not self._algorand:
             raise ValueError("Attempt to get app client from a ClientManager without an Algorand client")
@@ -478,6 +509,13 @@ class ClientManager:
         :param clear_source_map: Optional clear program source map
         :raises ValueError: If no Algorand client is configured
         :return: Typed application client instance
+
+        :example:
+            >>> client_manager = ClientManager(algod_client)
+            >>> typed_app_client = client_manager.get_typed_app_client_by_id(
+            ...     typed_client=MyAppClient,
+            ...     app_id=1234567890,
+            ... )
         """
         if not self._algorand:
             raise ValueError("Attempt to get app client from a ClientManager without an Algorand client")
@@ -515,6 +553,13 @@ class ClientManager:
         :param clear_source_map: Optional clear program source map
         :raises ValueError: If no Algorand client is configured
         :return: The typed client instance
+
+        :example:
+            >>> client_manager = ClientManager(algod_client)
+            >>> typed_app_client = client_manager.get_typed_app_client_by_network(
+            ...     typed_client=MyAppClient,
+            ...     app_name="app_name",
+            ... )
         """
         if not self._algorand:
             raise ValueError("Attempt to get app client from a ClientManager without an Algorand client")
@@ -548,6 +593,13 @@ class ClientManager:
         :param compilation_params: Optional compilation parameters
         :raises ValueError: If no Algorand client is configured
         :return: Typed application factory instance
+
+        :example:
+            >>> client_manager = ClientManager(algod_client)
+            >>> typed_app_factory = client_manager.get_typed_app_factory(
+            ...     typed_factory=MyAppFactory,
+            ...     app_name="app_name",
+            ... )
         """
         if not self._algorand:
             raise ValueError("Attempt to get app factory from a ClientManager without an Algorand client")
@@ -569,6 +621,10 @@ class ClientManager:
         otherwise it will use default localnet configuration.
 
         :return: Configuration for algod, indexer, and optionally kmd
+
+        :example:
+            >>> client_manager = ClientManager(algod_client)
+            >>> config = client_manager.get_config_from_environment_or_localnet()
         """
         algod_server = os.getenv("ALGOD_SERVER")
 
@@ -609,6 +665,10 @@ class ClientManager:
 
         :param config_or_port: Service name or port number
         :return: Client configuration for local network
+
+        :example:
+            >>> client_manager = ClientManager(algod_client)
+            >>> config = client_manager.get_default_localnet_config("algod")
         """
         port = (
             config_or_port
@@ -624,6 +684,10 @@ class ClientManager:
         Will raise an error if ALGOD_SERVER environment variable is not set
 
         :return: Algod client configuration
+
+        :example:
+            >>> client_manager = ClientManager(algod_client)
+            >>> config = client_manager.get_algod_config_from_environment()
         """
         return _get_config_from_environment("ALGOD")
 
@@ -633,6 +697,10 @@ class ClientManager:
         Will raise an error if INDEXER_SERVER environment variable is not set
 
         :return: Indexer client configuration
+
+        :example:
+            >>> client_manager = ClientManager(algod_client)
+            >>> config = client_manager.get_indexer_config_from_environment()
         """
         return _get_config_from_environment("INDEXER")
 
@@ -641,6 +709,10 @@ class ClientManager:
         """Retrieve the kmd configuration from environment variables.
 
         :return: KMD client configuration
+
+        :example:
+            >>> client_manager = ClientManager(algod_client)
+            >>> config = client_manager.get_kmd_config_from_environment()
         """
         return _get_config_from_environment("KMD")
 
@@ -653,6 +725,10 @@ class ClientManager:
         :param network: Which network to connect to - TestNet or MainNet
         :param config: Which algod config to return - Algod or Indexer
         :return: Configuration for the specified network and service
+
+        :example:
+            >>> client_manager = ClientManager(algod_client)
+            >>> config = client_manager.get_algonode_config("testnet", "algod")
         """
         service_type = "api" if config == "algod" else "idx"
         return AlgoClientNetworkConfig(

algokit_utils/clients/dispenser_api_client.py

@@ -2,8 +2,10 @@ import contextlib
 import enum
 import os
 from dataclasses import dataclass
+from typing import overload
 
 import httpx
+from typing_extensions import deprecated
 
 from algokit_utils.config import config
 
@@ -34,19 +36,25 @@ class DispenserAssetName(enum.IntEnum):
 @dataclass
 class DispenserAsset:
     asset_id: int
+    """The ID of the asset"""
     decimals: int
+    """The amount of decimal places the asset was created with"""
     description: str
+    """The description of the asset"""
 
 
 @dataclass
 class DispenserFundResponse:
     tx_id: str
+    """The transaction ID of the funded transaction"""
     amount: int
+    """The amount of Algos funded"""
 
 
 @dataclass
 class DispenserLimitResponse:
     amount: int
+    """The amount of Algos that can be funded"""
 
 
 DISPENSER_ASSETS = {
@@ -136,16 +144,37 @@ class TestNetDispenserApiClient:
             logger.debug(f"{error_message}: {err}", exc_info=True)
             raise err
 
-    def fund(self, address: str, amount: int, asset_id: int) -> DispenserFundResponse:
+    @overload
+    def fund(self, address: str, amount: int) -> DispenserFundResponse: ...
+
+    @deprecated("Asset ID parameter is deprecated. Can now use `fund(address, amount)` instead.")
+    @overload
+    def fund(self, address: str, amount: int, asset_id: int | None = None) -> DispenserFundResponse: ...
+
+    def fund(self, address: str, amount: int, asset_id: int | None = None) -> DispenserFundResponse:  # noqa: ARG002
         """
         Fund an account with Algos from the dispenser API
+
+        :param address: The address to fund
+        :param amount: The amount of Algos to fund
+        :param asset_id: The asset ID to fund (deprecated)
+        :return: The transaction ID of the funded transaction
+        :raises Exception: If the dispenser API request fails
+
+        :example:
+            >>> dispenser_client = TestNetDispenserApiClient()
+            >>> dispenser_client.fund(address="SENDER_ADDRESS", amount=1000000)
         """
 
         try:
             response = self._process_dispenser_request(
                 auth_token=self.auth_token,
-                url_suffix=f"fund/{asset_id}",
-                data={"receiver": address, "amount": amount, "assetID": asset_id},
+                url_suffix=f"fund/{DISPENSER_ASSETS[DispenserAssetName.ALGO].asset_id}",
+                data={
+                    "receiver": address,
+                    "amount": amount,
+                    "assetID": DISPENSER_ASSETS[DispenserAssetName.ALGO].asset_id,
+                },
                 method="POST",
             )
 

algokit_utils/models/application.py

@@ -19,43 +19,73 @@ __all__ = [
 @dataclass(kw_only=True, frozen=True)
 class AppState:
     key_raw: bytes
+    """The key of the state as raw bytes"""
     key_base64: str
+    """The key of the state"""
     value_raw: bytes | None
+    """The value of the state as raw bytes"""
     value_base64: str | None
+    """The value of the state as base64 encoded string"""
     value: str | int
+    """The value of the state as a string or integer"""
 
 
 @dataclass(kw_only=True, frozen=True)
 class AppInformation:
     app_id: int
+    """The ID of the application"""
     app_address: str
+    """The address of the application"""
     approval_program: bytes
+    """The approval program"""
     clear_state_program: bytes
+    """The clear state program"""
     creator: str
+    """The creator of the application"""
     global_state: dict[str, AppState]
+    """The global state of the application"""
     local_ints: int
+    """The number of local ints"""
     local_byte_slices: int
+    """The number of local byte slices"""
     global_ints: int
+    """The number of global ints"""
     global_byte_slices: int
+    """The number of global byte slices"""
     extra_program_pages: int | None
+    """The number of extra program pages"""
 
 
 @dataclass(kw_only=True, frozen=True)
 class CompiledTeal:
+    """The compiled teal code"""
+
     teal: str
+    """The teal code"""
     compiled: str
+    """The compiled teal code"""
     compiled_hash: str
+    """The compiled hash"""
     compiled_base64_to_bytes: bytes
+    """The compiled base64 to bytes"""
     source_map: algosdk.source_map.SourceMap | None
 
 
 @dataclass(kw_only=True, frozen=True)
 class AppCompilationResult:
+    """The compiled teal code"""
+
     compiled_approval: CompiledTeal
+    """The compiled approval program"""
     compiled_clear: CompiledTeal
+    """The compiled clear state program"""
 
 
 @dataclass(kw_only=True, frozen=True)
 class AppSourceMaps:
+    """The source maps for the application"""
+
     approval_source_map: SourceMap | None = None
+    """The source map for the approval program"""
     clear_source_map: SourceMap | None = None
+    """The source map for the clear state program"""

algokit_utils/models/state.py

@@ -19,15 +19,24 @@ __all__ = [
 
 @dataclass(kw_only=True, frozen=True)
 class BoxName:
+    """The name of the box"""
+
     name: str
+    """The name of the box as a string"""
     name_raw: bytes
+    """The name of the box as raw bytes"""
     name_base64: str
+    """The name of the box as a base64 encoded string"""
 
 
 @dataclass(kw_only=True, frozen=True)
 class BoxValue:
+    """The value of the box"""
+
     name: BoxName
+    """The name of the box"""
     value: bytes
+    """The value of the box as raw bytes"""
 
 
 class DataTypeFlag(IntEnum):