Skip to content

Commit

Permalink
docs: remaining docstrings
Browse files Browse the repository at this point in the history
  • Loading branch information
@aorumbayev
aorumbayev committed Feb 15, 2025
1 parent 7bbe834 commit 0d25ec0
Show file tree
Hide file tree
Showing 21 changed files with 2,066 additions and 710 deletions.
105 changes: 103 additions & 2 deletions docs/markdown/autoapi/algokit_utils/applications/app_client/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -280,6 +280,27 @@ methods for calling application methods, managing state, and handling transactio

* **Parameters:**
**params** – Parameters for creating the app client
* **Example:**
```pycon
>>> 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)
```

#### *property* algorand *: [algokit_utils.algorand.AlgorandClient](../../algorand/index.md#algokit_utils.algorand.AlgorandClient)*

Expand Down Expand Up @@ -329,6 +350,20 @@ Get the method parameters builder.

* **Returns:**
The method parameters builder for this application
* **Example:**
```pycon
>>> # 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]))
```

#### *property* send *: \_TransactionSender*

Expand All @@ -349,11 +384,16 @@ Get the transaction creator.
Normalize an application specification to ARC-56 format.

* **Parameters:**
**app_spec** – The application specification to normalize
**app_spec** – The application specification to normalize. Can be raw arc32 or arc56 json,
or an Arc32Contract or Arc56Contract instance
* **Returns:**
The normalized ARC-56 contract specification
* **Raises:**
**ValueError** – If the app spec format is invalid
* **Example:**
```pycon
>>> spec = AppClient.normalise_app_spec(app_spec_json)
```

#### *static* from_network(app_spec: [algokit_utils.applications.app_spec.arc56.Arc56Contract](../app_spec/arc56/index.md#algokit_utils.applications.app_spec.arc56.Arc56Contract) | [algokit_utils.applications.app_spec.arc32.Arc32Contract](../app_spec/arc32/index.md#algokit_utils.applications.app_spec.arc32.Arc32Contract) | str, algorand: [algokit_utils.algorand.AlgorandClient](../../algorand/index.md#algokit_utils.algorand.AlgorandClient), app_name: str | None = None, default_sender: str | None = None, default_signer: algosdk.atomic_transaction_composer.TransactionSigner | None = None, approval_source_map: algosdk.source_map.SourceMap | None = None, clear_source_map: algosdk.source_map.SourceMap | None = None) → [AppClient](#algokit_utils.applications.app_client.AppClient)

Expand All @@ -371,6 +411,25 @@ Create an AppClient instance from network information.
A new AppClient instance
* **Raises:**
**Exception** – If no app ID is found for the network
* **Example:**
```pycon
>>> 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",
... ),
... )
```

#### *static* from_creator_and_name(creator_address: str, app_name: str, app_spec: [algokit_utils.applications.app_spec.arc56.Arc56Contract](../app_spec/arc56/index.md#algokit_utils.applications.app_spec.arc56.Arc56Contract) | [algokit_utils.applications.app_spec.arc32.Arc32Contract](../app_spec/arc32/index.md#algokit_utils.applications.app_spec.arc32.Arc32Contract) | str, algorand: [algokit_utils.algorand.AlgorandClient](../../algorand/index.md#algokit_utils.algorand.AlgorandClient), default_sender: str | None = None, default_signer: algosdk.atomic_transaction_composer.TransactionSigner | None = None, approval_source_map: algosdk.source_map.SourceMap | None = None, clear_source_map: algosdk.source_map.SourceMap | None = None, ignore_cache: bool | None = None, app_lookup_cache: [algokit_utils.applications.app_deployer.ApplicationLookup](../app_deployer/index.md#algokit_utils.applications.app_deployer.ApplicationLookup) | None = None) → [AppClient](#algokit_utils.applications.app_client.AppClient)

Expand All @@ -391,6 +450,15 @@ Create an AppClient instance from creator address and application name.
A new AppClient instance
* **Raises:**
**ValueError** – If the app is not found for the creator and name
* **Example:**
```pycon
>>> client = AppClient.from_creator_and_name(
... creator_address="CREATORADDRESS",
... app_name="APPNAME",
... app_spec=Arc56Contract.from_json(app_spec_json),
... algorand=algorand,
... )
```

#### *static* compile(app_spec: [algokit_utils.applications.app_spec.arc56.Arc56Contract](../app_spec/arc56/index.md#algokit_utils.applications.app_spec.arc56.Arc56Contract), app_manager: [algokit_utils.applications.app_manager.AppManager](../app_manager/index.md#algokit_utils.applications.app_manager.AppManager), compilation_params: [AppClientCompilationParams](#algokit_utils.applications.app_client.AppClientCompilationParams) | None = None) → [AppClientCompilationResult](#algokit_utils.applications.app_client.AppClientCompilationResult)

Expand Down Expand Up @@ -425,7 +493,12 @@ Create a cloned AppClient instance with optionally overridden parameters.
* **approval_source_map** – Optional new approval source map
* **clear_source_map** – Optional new clear source map
* **Returns:**
A new AppClient instance with the specified parameters
A new AppClient instance
* **Example:**
```pycon
>>> client = AppClient(params)
>>> cloned_client = client.clone(app_name="Cloned App", default_sender="NEW_SENDER")
```

#### export_source_maps() → [algokit_utils.models.application.AppSourceMaps](../../models/application/index.md#algokit_utils.models.application.AppSourceMaps)

Expand Down Expand Up @@ -460,13 +533,21 @@ Get the application’s global state.

* **Returns:**
The application’s global state
* **Example:**
```pycon
>>> global_state = client.get_global_state()
```

#### get_box_names() → list[[algokit_utils.models.state.BoxName](../../models/state/index.md#algokit_utils.models.state.BoxName)]

Get all box names for the application.

* **Returns:**
List of box names
* **Example:**
```pycon
>>> box_names = client.get_box_names()
```

#### get_box_value(name: algokit_utils.models.state.BoxIdentifier) → bytes

Expand All @@ -476,6 +557,10 @@ Get the value of a box.
**name** – The box identifier
* **Returns:**
The box value as bytes
* **Example:**
```pycon
>>> box_value = client.get_box_value(box_name)
```

#### get_box_value_from_abi_type(name: algokit_utils.models.state.BoxIdentifier, abi_type: algokit_utils.applications.abi.ABIType) → algokit_utils.applications.abi.ABIValue

Expand All @@ -486,6 +571,10 @@ Get a box value decoded according to an ABI type.
* **abi_type** – The ABI type to decode as
* **Returns:**
The decoded box value
* **Example:**
```pycon
>>> box_value = client.get_box_value_from_abi_type(box_name, abi_type)
```

#### get_box_values(filter_func: collections.abc.Callable[[[algokit_utils.models.state.BoxName](../../models/state/index.md#algokit_utils.models.state.BoxName)], bool] | None = None) → list[[algokit_utils.models.state.BoxValue](../../models/state/index.md#algokit_utils.models.state.BoxValue)]

Expand All @@ -495,6 +584,10 @@ Get values for multiple boxes.
**filter_func** – Optional function to filter box names
* **Returns:**
List of box values
* **Example:**
```pycon
>>> box_values = client.get_box_values()
```

#### get_box_values_from_abi_type(abi_type: algokit_utils.applications.abi.ABIType, filter_func: collections.abc.Callable[[[algokit_utils.models.state.BoxName](../../models/state/index.md#algokit_utils.models.state.BoxName)], bool] | None = None) → list[[algokit_utils.applications.abi.BoxABIValue](../abi/index.md#algokit_utils.applications.abi.BoxABIValue)]

Expand All @@ -505,6 +598,10 @@ Get multiple box values decoded according to an ABI type.
* **filter_func** – Optional function to filter box names
* **Returns:**
List of decoded box values
* **Example:**
```pycon
>>> box_values = client.get_box_values_from_abi_type(abi_type)
```

#### fund_app_account(params: [FundAppAccountParams](#algokit_utils.applications.app_client.FundAppAccountParams), send_params: [algokit_utils.models.transaction.SendParams](../../models/transaction/index.md#algokit_utils.models.transaction.SendParams) | None = None) → [algokit_utils.transactions.transaction_sender.SendSingleTransactionResult](../../transactions/transaction_sender/index.md#algokit_utils.transactions.transaction_sender.SendSingleTransactionResult)

Expand All @@ -515,3 +612,7 @@ Fund the application’s account.
* **send_params** – Send parameters, defaults to None
* **Returns:**
The transaction result
* **Example:**
```pycon
>>> result = client.fund_app_account(params)
```
83 changes: 82 additions & 1 deletion docs/markdown/autoapi/algokit_utils/applications/app_deployer/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,8 +155,89 @@ The delete result

Manages deployment and deployment metadata of applications

* **Parameters:**
* **app_manager** – The app manager to use
* **transaction_sender** – The transaction sender to use
* **indexer** – The indexer to use
* **Example:**
```pycon
>>> deployer = AppDeployer(app_manager, transaction_sender, indexer)
```

#### deploy(deployment: [AppDeployParams](#algokit_utils.applications.app_deployer.AppDeployParams)) → [AppDeployResult](#algokit_utils.applications.app_deployer.AppDeployResult)

Idempotently deploy (create if not exists, update if changed) an app against the given name for the given
creator account, including deploy-time TEAL template placeholder substitutions (if specified).

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](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/architecture-decisions/2023-01-12_smart-contract-deployment.md)

**Note:** When using the return from this function be sure to check operation_performed to get access to
return properties like transaction, confirmation and delete_result.

**Note:** if there is a breaking state schema change to an existing app (and on_schema_break is set to
‘replace’) 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 ‘replace’)
the existing app will be deleted and re-created.

* **Parameters:**
**deployment** – The arguments to control the app deployment
* **Returns:**
The result of the deployment
* **Raises:**
**ValueError** – If the app spec format is invalid
* **Example:**
```pycon
>>> deployer.deploy(AppDeployParams(
... create_params=AppCreateParams(
... sender='SENDER_ADDRESS',
... approval_program='APPROVAL PROGRAM',
... clear_state_program='CLEAR PROGRAM',
... schema={
... 'global_byte_slices': 0,
... 'global_ints': 0,
... 'local_byte_slices': 0,
... 'local_ints': 0
... }
... ),
... update_params=AppUpdateParams(
... sender='SENDER_ADDRESS'
... ),
... delete_params=AppDeleteParams(
... sender='SENDER_ADDRESS'
... ),
... metadata=AppDeploymentMetaData(
... name='my_app',
... version='2.0',
... updatable=False,
... deletable=False
... ),
... on_schema_break=OnSchemaBreak.AppendApp,
... on_update=OnUpdate.AppendApp
... )
... )
```

#### get_creator_apps_by_name(\*, creator_address: str, ignore_cache: bool = False) → [ApplicationLookup](#algokit_utils.applications.app_deployer.ApplicationLookup)

Get apps created by an account
Returns a lookup of name => app metadata (id, address, …metadata) for all apps created by the given account
that have an [ARC-2]([https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0002.md](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0002.md)) AppDeployNote as
the transaction note of the app creation transaction.

This function caches the result for the given creator account so that subsequent calls won’t require an indexer
lookup.

If the AppManager instance wasn’t created with an indexer client, this function will throw an error.

* **Parameters:**
* **creator_address** – The address of the account that is the creator of the apps you want to search for
* **ignore_cache** – Whether or not to ignore the cache and force a lookup, default: use the cache
* **Returns:**
A name-based lookup of the app metadata
* **Raises:**
**ValueError** – If the app spec format is invalid
* **Example:**
```pycon
>>> result = await deployer.get_creator_apps_by_name(creator)
```
Loading

0 comments on commit 0d25ec0

Please sign in to comment.