chore: adding draft deprecation warnings; wip

docs/markdown/index.md

@@ -7,46 +7,47 @@ The goal of this library is to provide intuitive, productive utility functions t
 Largely these functions wrap the underlying Algorand SDK, but provide a higher level interface with sensible defaults and capabilities for common tasks.
 
 #### NOTE
+
 If you prefer TypeScript there’s an equivalent [TypeScript utility library](https://github.com/algorandfoundation/algokit-utils-ts).
 
 [Core principles]() | [Installation]() | [Usage]() | [Capabilities]() | [Reference docs]()
 
 # Contents
 
-* [Account management](capabilities/account.md)
-  * [`Account`](capabilities/account.md#account)
-* [Client management](capabilities/client.md)
-  * [Network configuration](capabilities/client.md#network-configuration)
-  * [Clients](capabilities/client.md#clients)
-* [App client](capabilities/app-client.md)
-  * [Design](capabilities/app-client.md#design)
-  * [Creating an application client](capabilities/app-client.md#creating-an-application-client)
-  * [Calling methods on the app](capabilities/app-client.md#calling-methods-on-the-app)
-  * [Composing calls](capabilities/app-client.md#composing-calls)
-  * [Reading state](capabilities/app-client.md#reading-state)
-  * [Handling logic errors and diagnosing errors](capabilities/app-client.md#handling-logic-errors-and-diagnosing-errors)
-* [App deployment](capabilities/app-deploy.md)
-  * [Design](capabilities/app-deploy.md#design)
-  * [Finding apps by creator](capabilities/app-deploy.md#finding-apps-by-creator)
-  * [Deploying an application](capabilities/app-deploy.md#deploying-an-application)
-* [Algo transfers](capabilities/transfer.md)
-  * [Transferring Algos](capabilities/transfer.md#transferring-algos)
-  * [Ensuring minimum Algos](capabilities/transfer.md#ensuring-minimum-algos)
-  * [Transfering Assets](capabilities/transfer.md#transfering-assets)
-  * [Dispenser](capabilities/transfer.md#dispenser)
-* [TestNet Dispenser Client](capabilities/dispenser-client.md)
-  * [Creating a Dispenser Client](capabilities/dispenser-client.md#creating-a-dispenser-client)
-  * [Funding an Account](capabilities/dispenser-client.md#funding-an-account)
-  * [Registering a Refund](capabilities/dispenser-client.md#registering-a-refund)
-  * [Getting Current Limit](capabilities/dispenser-client.md#getting-current-limit)
-  * [Error Handling](capabilities/dispenser-client.md#error-handling)
-* [Debugger](capabilities/debugger.md)
-  * [Configuration](capabilities/debugger.md#configuration)
-  * [Debugging Utilities](capabilities/debugger.md#debugging-utilities)
-* [`algokit_utils`](apidocs/algokit_utils/algokit_utils.md)
-  * [Data](apidocs/algokit_utils/algokit_utils.md#data)
-  * [Classes](apidocs/algokit_utils/algokit_utils.md#classes)
-  * [Functions](apidocs/algokit_utils/algokit_utils.md#functions)
+- [Account management](capabilities/account.md)
+  - [`Account`](capabilities/account.md#account)
+- [Client management](capabilities/client.md)
+  - [Network configuration](capabilities/client.md#network-configuration)
+  - [Clients](capabilities/client.md#clients)
+- [App client](capabilities/app-client.md)
+  - [Design](capabilities/app-client.md#design)
+  - [Creating an application client](capabilities/app-client.md#creating-an-application-client)
+  - [Calling methods on the app](capabilities/app-client.md#calling-methods-on-the-app)
+  - [Composing calls](capabilities/app-client.md#composing-calls)
+  - [Reading state](capabilities/app-client.md#reading-state)
+  - [Handling logic errors and diagnosing errors](capabilities/app-client.md#handling-logic-errors-and-diagnosing-errors)
+- [App deployment](capabilities/app-deploy.md)
+  - [Design](capabilities/app-deploy.md#design)
+  - [Finding apps by creator](capabilities/app-deploy.md#finding-apps-by-creator)
+  - [Deploying an application](capabilities/app-deploy.md#deploying-an-application)
+- [Algo transfers](capabilities/transfer.md)
+  - [Transferring Algos](capabilities/transfer.md#transferring-algos)
+  - [Ensuring minimum Algos](capabilities/transfer.md#ensuring-minimum-algos)
+  - [Transfering Assets](capabilities/transfer.md#transfering-assets)
+  - [Dispenser](capabilities/transfer.md#dispenser)
+- [TestNet Dispenser Client](capabilities/dispenser-client.md)
+  - [Creating a Dispenser Client](capabilities/dispenser-client.md#creating-a-dispenser-client)
+  - [Funding an Account](capabilities/dispenser-client.md#funding-an-account)
+  - [Registering a Refund](capabilities/dispenser-client.md#registering-a-refund)
+  - [Getting Current Limit](capabilities/dispenser-client.md#getting-current-limit)
+  - [Error Handling](capabilities/dispenser-client.md#error-handling)
+- [Debugger](capabilities/debugger.md)
+  - [Configuration](capabilities/debugger.md#configuration)
+  - [Debugging Utilities](capabilities/debugger.md#debugging-utilities)
+- [`algokit_utils`](apidocs/algokit_utils/algokit_utils.md)
+  - [Data](apidocs/algokit_utils/algokit_utils.md#data)
+  - [Classes](apidocs/algokit_utils/algokit_utils.md#classes)
+  - [Functions](apidocs/algokit_utils/algokit_utils.md#functions)
 
 <a id="core-principles"></a>
 

src/algokit_utils/_legacy_v2/_ensure_funded.py

@@ -4,6 +4,7 @@
 from algosdk.atomic_transaction_composer import AccountTransactionSigner
 from algosdk.transaction import SuggestedParams
 from algosdk.v2client.algod import AlgodClient
+from deprecated import deprecated
 
 from algokit_utils._legacy_v2._transfer import TransferParameters, transfer
 from algokit_utils._legacy_v2.account import get_dispenser_account
@@ -115,6 +116,7 @@ def _fund_using_transfer(
     return EnsureFundedResponse(transaction_id=transaction_id, amount=response.amt)
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def ensure_funded(
     client: AlgodClient,
     parameters: EnsureBalanceParameters,

src/algokit_utils/_legacy_v2/account.py

@@ -5,6 +5,7 @@
 from algosdk.account import address_from_private_key
 from algosdk.mnemonic import from_private_key, to_private_key
 from algosdk.util import algos_to_microalgos
+from deprecated import deprecated
 
 from algokit_utils._legacy_v2._transfer import TransferParameters, transfer
 from algokit_utils._legacy_v2.network_clients import get_kmd_client_from_algod_client, is_localnet
@@ -30,13 +31,15 @@
 _DEFAULT_ACCOUNT_MINIMUM_BALANCE = 1_000_000_000
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def get_account_from_mnemonic(mnemonic: str) -> Account:
     """Convert a mnemonic (25 word passphrase) into an Account"""
     private_key = to_private_key(mnemonic)
     address = address_from_private_key(private_key)
     return Account(private_key=private_key, address=address)
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def create_kmd_wallet_account(kmd_client: "KMDClient", name: str) -> Account:
     """Creates a wallet with specified name"""
     wallet_id = kmd_client.create_wallet(name, "")["id"]
@@ -50,6 +53,7 @@ def create_kmd_wallet_account(kmd_client: "KMDClient", name: str) -> Account:
     return get_account_from_mnemonic(from_private_key(private_account_key))
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def get_or_create_kmd_wallet_account(
     client: "AlgodClient", name: str, fund_with_algos: float = 1000, kmd_client: "KMDClient | None" = None
 ) -> Account:
@@ -90,6 +94,7 @@ def _is_default_account(account: dict[str, Any]) -> bool:
     return bool(account["status"] != "Offline" and account["amount"] > _DEFAULT_ACCOUNT_MINIMUM_BALANCE)
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def get_localnet_default_account(client: "AlgodClient") -> Account:
     """Returns the default Account in a LocalNet instance"""
     if not is_localnet(client):
@@ -102,13 +107,15 @@ def get_localnet_default_account(client: "AlgodClient") -> Account:
     return account
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def get_dispenser_account(client: "AlgodClient") -> Account:
     """Returns an Account based on DISPENSER_MNENOMIC environment variable or the default account on LocalNet"""
     if is_localnet(client):
         return get_localnet_default_account(client)
     return get_account(client, "DISPENSER")
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def get_kmd_wallet_account(
     client: "AlgodClient",
     kmd_client: "KMDClient",
@@ -142,6 +149,7 @@ def get_kmd_wallet_account(
     return get_account_from_mnemonic(from_private_key(private_account_key))
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def get_account(
     client: "AlgodClient", name: str, fund_with_algos: float = 1000, kmd_client: "KMDClient | None" = None
 ) -> Account:

src/algokit_utils/_legacy_v2/application_client.py

@@ -27,6 +27,7 @@
 from algosdk.constants import APP_PAGE_MAX_SIZE
 from algosdk.logic import get_application_address
 from algosdk.source_map import SourceMap
+from deprecated import deprecated
 
 import algokit_utils._legacy_v2.application_specification as au_spec
 import algokit_utils._legacy_v2.deploy as au_deploy
@@ -83,6 +84,7 @@ def num_extra_program_pages(approval: bytes, clear: bytes) -> int:
     return ceil(((len(approval) + len(clear)) - APP_PAGE_MAX_SIZE) / APP_PAGE_MAX_SIZE)
 
 
+@deprecated(reason="Use AppClient from algokit_utils.applications instead", version="3.0.0")
 class ApplicationClient:
     """A class that wraps an ARC-0032 app spec and provides high productivity methods to deploy and call the app"""
 
@@ -1254,6 +1256,7 @@ def _try_convert_to_logic_error(
     return None
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def execute_atc_with_logic_error(
     atc: AtomicTransactionComposer,
     algod_client: "AlgodClient",

src/algokit_utils/_legacy_v2/application_specification.py

@@ -8,6 +8,7 @@
 from algosdk.abi import Contract
 from algosdk.abi.method import MethodDict
 from algosdk.transaction import StateSchema
+from deprecated import deprecated
 
 __all__ = [
     "CallConfig",
@@ -136,6 +137,7 @@ def _decode_state_schema(data: dict[str, int]) -> StateSchema:
     )
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 @dataclasses.dataclass(kw_only=True)
 class ApplicationSpecification:
     """ARC-0032 application specification

src/algokit_utils/_legacy_v2/asset.py

@@ -4,6 +4,7 @@
 from algosdk.atomic_transaction_composer import AtomicTransactionComposer, TransactionWithSigner
 from algosdk.constants import TX_GROUP_LIMIT
 from algosdk.transaction import AssetTransferTxn
+from deprecated import deprecated
 
 if TYPE_CHECKING:
     from algosdk.v2client.algod import AlgodClient
@@ -68,6 +69,7 @@ def _ensure_asset_balance_conditions(
         raise ValueError(error_message)
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def opt_in(algod_client: "AlgodClient", account: Account, asset_ids: list[int]) -> dict[int, str]:
     """
     Opt-in to a list of assets on the Algorand blockchain. Before an account can receive a specific asset,
@@ -116,6 +118,7 @@ def opt_in(algod_client: "AlgodClient", account: Account, asset_ids: list[int])
     return result
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def opt_out(algod_client: "AlgodClient", account: Account, asset_ids: list[int]) -> dict[int, str]:
     """
     Opt out from a list of Algorand Standard Assets (ASAs) by transferring them back to their creators.

src/algokit_utils/_legacy_v2/deploy.py

@@ -175,6 +175,7 @@ def _parse_note(metadata_b64: str | None) -> AppDeployMetaData | None:
         return None
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def get_creator_apps(indexer: "IndexerClient", creator_account: Account | str) -> AppLookup:
     """Returns a mapping of Application names to {py:class}`AppMetaData` for all Applications created by specified
     creator that have a transaction note containing {py:class}`AppDeployMetaData`
@@ -255,6 +256,7 @@ class AppChanges:
     schema_change_description: str | None
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def check_for_app_changes(
     algod_client: "AlgodClient",
     *,

src/algokit_utils/_legacy_v2/network_clients.py

@@ -6,6 +6,7 @@
 from algosdk.kmd import KMDClient
 from algosdk.v2client.algod import AlgodClient
 from algosdk.v2client.indexer import IndexerClient
+from deprecated import deprecated
 
 __all__ = [
     "AlgoClientConfig",
@@ -40,12 +41,14 @@ class AlgoClientConfigs:
     kmd_config: AlgoClientConfig | None
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def get_default_localnet_config(config: Literal["algod", "indexer", "kmd"]) -> AlgoClientConfig:
     """Returns the client configuration to point to the default LocalNet"""
     port = {"algod": 4001, "indexer": 8980, "kmd": 4002}[config]
     return AlgoClientConfig(server=f"http://localhost:{port}", token="a" * 64)
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def get_algonode_config(
     network: Literal["testnet", "mainnet"], config: Literal["algod", "indexer"], token: str
 ) -> AlgoClientConfig:
@@ -56,6 +59,7 @@ def get_algonode_config(
     )
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def get_algod_client(config: AlgoClientConfig | None = None) -> AlgodClient:
     """Returns an {py:class}`algosdk.v2client.algod.AlgodClient` from `config` or environment
 
@@ -65,6 +69,7 @@ def get_algod_client(config: AlgoClientConfig | None = None) -> AlgodClient:
     return AlgodClient(config.token, config.server, headers)
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def get_kmd_client(config: AlgoClientConfig | None = None) -> KMDClient:
     """Returns an {py:class}`algosdk.kmd.KMDClient` from `config` or environment
 
@@ -73,6 +78,7 @@ def get_kmd_client(config: AlgoClientConfig | None = None) -> KMDClient:
     return KMDClient(config.token, config.server)
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def get_indexer_client(config: AlgoClientConfig | None = None) -> IndexerClient:
     """Returns an {py:class}`algosdk.v2client.indexer.IndexerClient` from `config` or environment.
 
@@ -82,24 +88,28 @@ def get_indexer_client(config: AlgoClientConfig | None = None) -> IndexerClient:
     return IndexerClient(config.token, config.server, headers)
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def is_localnet(client: AlgodClient) -> bool:
     """Returns True if client genesis is `devnet-v1` or `sandnet-v1`"""
     params = client.suggested_params()
     return params.gen in ["devnet-v1", "sandnet-v1", "dockernet-v1"]
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def is_mainnet(client: AlgodClient) -> bool:
     """Returns True if client genesis is `mainnet-v1`"""
     params = client.suggested_params()
     return params.gen in ["mainnet-v1.0", "mainnet-v1", "mainnet"]
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def is_testnet(client: AlgodClient) -> bool:
     """Returns True if client genesis is `testnet-v1`"""
     params = client.suggested_params()
     return params.gen in ["testnet-v1.0", "testnet-v1", "testnet"]
 
 
+@deprecated(reason="Deprecated", version="3.0.0")
 def get_kmd_client_from_algod_client(client: AlgodClient) -> KMDClient:
     """Returns an {py:class}`algosdk.kmd.KMDClient` from supplied `client`