docs: add initial documentation for common functionality (#8)

BREAKING CHANGE: 1.0 release

Author: daniel-makerx

README.md

@@ -1 +1,29 @@
-# algokit-utils-py
+# AlgoKit Python Utilities
+
+A set of core Algorand utilities written in Python and released via PyPi that make it easier to build solutions on Algorand. This project is part of [AlgoKit](https://github.com/algorandfoundation/algokit-cli).
+
+The goal of this library is to provide intuitive, productive utility functions that make it easier, quicker and safer to build applications on Algorand. 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 [Typesript utility library](https://github.com/algorandfoundation/algokit-utils-ts).
+
+## Install
+
+This library can be installed using pip, e.g.:
+
+```
+pip install algokit-utils
+```
+
+## Guiding principles
+
+This library follows the [Guiding Principles of AlgoKit](https://github.com/algorandfoundation/algokit-cli#guiding-principles).
+
+## Contributing
+
+This is an open source project managed by the Algorand Foundation. See the [AlgoKit contributing page](https://github.com/algorandfoundation/algokit-cli/blob/main/CONTRIBUTING.MD) to learn about making improvements.
+
+To successfully run the tests in this repository you need to be running LocalNet via [AlgoKit](https://github.com/algorandfoundation/algokit-cli):
+
+```
+algokit localnet start
+```

pyproject.toml

@@ -91,7 +91,7 @@ version_toml = "pyproject.toml:tool.poetry.version"
 remove_dist = false
 build_command = "poetry build --format wheel"
 version_source = "tag"
-major_on_zero = false
+major_on_zero = true
 upload_to_repository = false
 tag_commit = true
 branch = "main"

src/algokit_utils/account.py

@@ -131,6 +131,32 @@ def get_kmd_wallet_account(
 def get_account(
     client: AlgodClient, name: str, fund_with_algos: float = 1000, kmd_client: KMDClient | None = None
 ) -> Account:
+    """Returns an Algorand account with private key loaded by convention based on the given name identifier.
+
+    ## Convention:
+
+    **Non-LocalNet:** will load os.environ['{name}_MNEMONIC'] as a mnemonic secret;
+    Be careful how the mnemonic is handled, never commit it into source control and ideally load it via a
+    secret storage service rather than the file system.
+
+    **LocalNet:** will load the account from a KMD wallet called {name} and if that wallet doesn't exist it will
+    create it and fund the account for you
+
+    This allows you to write code that will work seamlessly in production and local development (LocalNet) without
+    manual config locally (including when you reset the LocalNet).
+
+    @example Default
+
+    If you have a mnemonic secret loaded into `os.environ['ACCOUNT_MNEMONIC'] then you can call the following to get
+    that private key loaded into an account object:
+    ```python
+    account = await get_account('ACCOUNT', algod)
+    ```
+
+    If that code runs against LocalNet then a wallet called 'ACCOUNT' will automatically be created with an account
+    that is automatically funded with 1000 (default) ALGOs from the default LocalNet dispenser.
+    """
+
     mnemonic_key = f"{name.upper()}_MNEMONIC"
     mnemonic = os.getenv(mnemonic_key)
     if mnemonic:

src/algokit_utils/application_client.py

@@ -1,4 +1,5 @@
 import base64
+import copy
 import dataclasses
 import logging
 import re
@@ -87,6 +88,8 @@ def num_extra_program_pages(approval: bytes, clear: bytes) -> int:
 
 @dataclasses.dataclass(kw_only=True)
 class CommonCallParameters:
+    """Common transaction parameters used when making update, delete, opt_in, close_out or clear_state calls"""
+
     signer: TransactionSigner | None = None
     sender: str | None = None
     suggested_params: transaction.SuggestedParams | None = None
@@ -101,11 +104,15 @@ class CommonCallParameters:
 
 @dataclasses.dataclass(kw_only=True)
 class OnCompleteCallParameters(CommonCallParameters):
+    """Transaction parameters used when making any call to an Application"""
+
     on_complete: transaction.OnComplete | None = None
 
 
 @dataclasses.dataclass(kw_only=True)
 class CreateCallParameters(OnCompleteCallParameters):
+    """Transaction parameters used when making a create call for Application"""
+
     extra_pages: int | None = None
 
 
@@ -127,6 +134,8 @@ class CreateCallParametersDict(TypedDict, OnCompleteCallParametersDict, total=Fa
 
 @dataclasses.dataclass(kw_only=True)
 class ABICallArgs:
+    """Parameters used to update or delete an application when calling deploy()"""
+
     method: ABIMethod | bool | None = None
     args: ABIArgsDict = dataclasses.field(default_factory=dict)
     suggested_params: transaction.SuggestedParams | None = None
@@ -140,6 +149,8 @@ class ABICallArgs:
 
 @dataclasses.dataclass(kw_only=True)
 class ABICreateCallArgs(ABICallArgs):
+    """Parameters used to create an application when calling deploy()"""
+
     extra_pages: int | None = None
     on_complete: transaction.OnComplete | None = None
 
@@ -162,6 +173,8 @@ class ABICreateCallArgsDict(TypedDict, ABICallArgsDict, total=False):
 
 
 class ApplicationClient:
+    """A class that wraps an ARC-0032 app spec and provides high productivity methods to deploy and call the app"""
+
     @overload
     def __init__(
         self,
@@ -280,8 +293,8 @@ def prepare(
         app_id: int | None = None,
         template_values: au_deploy.TemplateValueDict | None = None,
     ) -> "ApplicationClient":
-        import copy
-
+        """Creates a copy of this ApplicationClient, using the new signer, sender and app_id values if provided.
+        Will also substitute provided template_values into the associated app_spec"""
         new_client = copy.copy(self)
         new_client._prepare(new_client, signer=signer, sender=sender, app_id=app_id, template_values=template_values)
         return new_client
@@ -319,6 +332,15 @@ def deploy(
         update_args: ABICallArgs | ABICallArgsDict | None = None,
         delete_args: ABICallArgs | ABICallArgsDict | None = None,
     ) -> au_deploy.DeployResponse:
+        """Idempotently deploy (create, update/delete if changed) an app against the given name via the given creator
+        account, including deploy-time template placeholder substitutions. To understand the architecture decisions
+        behind this functionality please see
+        https://github.com/algorandfoundation/algokit-cli/blob/main/docs/architecture-decisions/2023-01-12_smart-contract-deployment.md
+        Note: if there is a breaking state schema change to an existing app (and `on_schema_break` is set to
+        'ReplaceApp' the existing app will be deleted and re-created.
+        Note: if there is an update (different TEAL code) to an existing app (and `on_update` is set to 'ReplaceApp')
+        the existing app will be deleted and re-created.
+        """
         before = self._approval_program, self._clear_program, self.sender, self.signer, self.app_id
         try:
             return self._deploy(
@@ -932,7 +954,7 @@ def clear_state(
         return self._execute_atc_tr(atc)
 
     def get_global_state(self, *, raw: bool = False) -> dict[bytes | str, bytes | str | int]:
-        """gets the global state info for the app id set"""
+        """Gets the global state info associated with app_id"""
         global_state = self.algod_client.application_info(self.app_id)
         assert isinstance(global_state, dict)
         return cast(
@@ -941,7 +963,7 @@ def get_global_state(self, *, raw: bool = False) -> dict[bytes | str, bytes | st
         )
 
     def get_local_state(self, account: str | None = None, *, raw: bool = False) -> dict[bytes | str, bytes | str | int]:
-        """gets the local state info for the app id set and the account specified"""
+        """Gets the local state info for associated app_id and account/sender"""
 
         if account is None:
             _, account = self._resolve_signer_sender(self.signer, self.sender)
@@ -954,6 +976,8 @@ def get_local_state(self, account: str | None = None, *, raw: bool = False) -> d
         )
 
     def resolve(self, to_resolve: au_spec.DefaultArgumentDict) -> int | str | bytes:
+        """Resolves the default value for an ABI method, based on app_spec"""
+
         def _data_check(value: Any) -> int | str | bytes:
             if isinstance(value, int | str | bytes):
                 return value
@@ -1258,6 +1282,7 @@ def substitute_template_and_compile(
     app_spec: au_spec.ApplicationSpecification,
     template_values: au_deploy.TemplateValueDict,
 ) -> tuple[Program, Program]:
+    """Substitutes the provided template_values into app_spec and compiles"""
     template_values = dict(template_values or {})
     clear = au_deploy.replace_template_variables(app_spec.clear_program, template_values)
 
@@ -1298,6 +1323,8 @@ def execute_atc_with_logic_error(
     approval_program: str | None = None,
     approval_source_map: SourceMap | None = None,
 ) -> AtomicTransactionResponse:
+    """Calls execute on provided atc, but will parse any errors into a LogicError,
+    if approval_program and approval_source_map are specifed"""
     try:
         return atc.execute(algod_client, wait_rounds=wait_rounds)
     except Exception as ex:

src/algokit_utils/network_clients.py

@@ -24,23 +24,30 @@ class AlgoClientConfig:
 
 
 def get_algod_client(config: AlgoClientConfig | None = None) -> AlgodClient:
+    """Returns an algod SDK client using configuration from environment variables
+    ALGOD_SERVER, ALGOD_PORT and ALGOD_TOKEN"""
     config = config or _get_config_from_environment("ALGOD")
     headers = _get_headers(config)
     return AlgodClient(config.token, config.server, headers)
 
 
 def get_indexer_client(config: AlgoClientConfig | None = None) -> IndexerClient:
+    """Returns an indexer SDK client using configuration from environment variables
+    INDEXER_SERVER, INDEXER_PORT and INDEXER_TOKEN"""
     config = config or _get_config_from_environment("INDEXER")
     headers = _get_headers(config)
     return IndexerClient(config.token, config.server, headers)  # type: ignore[no-untyped-call]
 
 
 def is_sandbox(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"]
 
 
 def get_kmd_client_from_algod_client(client: AlgodClient) -> KMDClient:
+    """Returns and SDK KMDClient using the same address as provided AlgodClient, but on port specified by
+    KMD_PORT environment variable, or 4092 by default"""
     # We can only use Kmd on the Sandbox otherwise it's not exposed so this makes some assumptions
     # (e.g. same token and server as algod and port 4002 by default)
     port = os.getenv("KMD_PORT", "4002")