Skip to content

Commit 0d25ec0

Browse files
aorumbayevaorumbayev
committed
docs: remaining docstrings
1 parent 7bbe834 commit 0d25ec0

File tree

21 files changed

+2066
-710
lines changed

21 files changed

+2066
-710
lines changed

‎docs/markdown/autoapi/algokit_utils/applications/app_client/index.md

Lines changed: 103 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -280,6 +280,27 @@ methods for calling application methods, managing state, and handling transactio
280280

281281
* **Parameters:**
282282
**params** – Parameters for creating the app client
283+
* **Example:**
284+
```pycon
285+
>>> params = AppClientParams(
286+
... app_spec=Arc56Contract.from_json(app_spec_json),
287+
... algorand=algorand,
288+
... app_id=1234567890,
289+
... app_name="My App",
290+
... default_sender="SENDERADDRESS",
291+
... default_signer=TransactionSigner(
292+
... account="SIGNERACCOUNT",
293+
... private_key="SIGNERPRIVATEKEY",
294+
... ),
295+
... approval_source_map=SourceMap(
296+
... source="APPROVALSOURCE",
297+
... ),
298+
... clear_source_map=SourceMap(
299+
... source="CLEARSOURCE",
300+
... ),
301+
... )
302+
>>> client = AppClient(params)
303+
```
283304

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

@@ -329,6 +350,20 @@ Get the method parameters builder.
329350

330351
* **Returns:**
331352
The method parameters builder for this application
353+
* **Example:**
354+
```pycon
355+
>>> # Create a transaction in the future using Algorand Client
356+
>>> my_method_call = app_client.params.call(AppClientMethodCallParams(
357+
method='my_method',
358+
args=[123, 'hello']))
359+
>>> # ...
360+
>>> await algorand.send.AppMethodCall(my_method_call)
361+
>>> # Define a nested transaction as an ABI argument
362+
>>> my_method_call = app_client.params.call(AppClientMethodCallParams(
363+
method='my_method',
364+
args=[123, 'hello']))
365+
>>> app_client.send.call(AppClientMethodCallParams(method='my_method2', args=[my_method_call]))
366+
```
332367

333368
#### *property* send *: \_TransactionSender*
334369

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

351386
* **Parameters:**
352-
**app_spec** – The application specification to normalize
387+
**app_spec** – The application specification to normalize. Can be raw arc32 or arc56 json,
388+
or an Arc32Contract or Arc56Contract instance
353389
* **Returns:**
354390
The normalized ARC-56 contract specification
355391
* **Raises:**
356392
**ValueError** – If the app spec format is invalid
393+
* **Example:**
394+
```pycon
395+
>>> spec = AppClient.normalise_app_spec(app_spec_json)
396+
```
357397

358398
#### *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)
359399

@@ -371,6 +411,25 @@ Create an AppClient instance from network information.
371411
A new AppClient instance
372412
* **Raises:**
373413
**Exception** – If no app ID is found for the network
414+
* **Example:**
415+
```pycon
416+
>>> client = AppClient.from_network(
417+
... app_spec=Arc56Contract.from_json(app_spec_json),
418+
... algorand=algorand,
419+
... app_name="My App",
420+
... default_sender="SENDERADDRESS",
421+
... default_signer=TransactionSigner(
422+
... account="SIGNERACCOUNT",
423+
... private_key="SIGNERPRIVATEKEY",
424+
... ),
425+
... approval_source_map=SourceMap(
426+
... source="APPROVALSOURCE",
427+
... ),
428+
... clear_source_map=SourceMap(
429+
... source="CLEARSOURCE",
430+
... ),
431+
... )
432+
```
374433

375434
#### *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)
376435

@@ -391,6 +450,15 @@ Create an AppClient instance from creator address and application name.
391450
A new AppClient instance
392451
* **Raises:**
393452
**ValueError** – If the app is not found for the creator and name
453+
* **Example:**
454+
```pycon
455+
>>> client = AppClient.from_creator_and_name(
456+
... creator_address="CREATORADDRESS",
457+
... app_name="APPNAME",
458+
... app_spec=Arc56Contract.from_json(app_spec_json),
459+
... algorand=algorand,
460+
... )
461+
```
394462

395463
#### *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)
396464

@@ -425,7 +493,12 @@ Create a cloned AppClient instance with optionally overridden parameters.
425493
* **approval_source_map** – Optional new approval source map
426494
* **clear_source_map** – Optional new clear source map
427495
* **Returns:**
428-
A new AppClient instance with the specified parameters
496+
A new AppClient instance
497+
* **Example:**
498+
```pycon
499+
>>> client = AppClient(params)
500+
>>> cloned_client = client.clone(app_name="Cloned App", default_sender="NEW_SENDER")
501+
```
429502

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

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

461534
* **Returns:**
462535
The application’s global state
536+
* **Example:**
537+
```pycon
538+
>>> global_state = client.get_global_state()
539+
```
463540

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

466543
Get all box names for the application.
467544

468545
* **Returns:**
469546
List of box names
547+
* **Example:**
548+
```pycon
549+
>>> box_names = client.get_box_names()
550+
```
470551

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

@@ -476,6 +557,10 @@ Get the value of a box.
476557
**name** – The box identifier
477558
* **Returns:**
478559
The box value as bytes
560+
* **Example:**
561+
```pycon
562+
>>> box_value = client.get_box_value(box_name)
563+
```
479564

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

@@ -486,6 +571,10 @@ Get a box value decoded according to an ABI type.
486571
* **abi_type** – The ABI type to decode as
487572
* **Returns:**
488573
The decoded box value
574+
* **Example:**
575+
```pycon
576+
>>> box_value = client.get_box_value_from_abi_type(box_name, abi_type)
577+
```
489578

490579
#### 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)]
491580

@@ -495,6 +584,10 @@ Get values for multiple boxes.
495584
**filter_func** – Optional function to filter box names
496585
* **Returns:**
497586
List of box values
587+
* **Example:**
588+
```pycon
589+
>>> box_values = client.get_box_values()
590+
```
498591

499592
#### 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)]
500593

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

509606
#### 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)
510607

@@ -515,3 +612,7 @@ Fund the application’s account.
515612
* **send_params** – Send parameters, defaults to None
516613
* **Returns:**
517614
The transaction result
615+
* **Example:**
616+
```pycon
617+
>>> result = client.fund_app_account(params)
618+
```

‎docs/markdown/autoapi/algokit_utils/applications/app_deployer/index.md

Lines changed: 82 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -155,8 +155,89 @@ The delete result
155155

156156
Manages deployment and deployment metadata of applications
157157

158+
* **Parameters:**
159+
* **app_manager** – The app manager to use
160+
* **transaction_sender** – The transaction sender to use
161+
* **indexer** – The indexer to use
162+
* **Example:**
163+
```pycon
164+
>>> deployer = AppDeployer(app_manager, transaction_sender, indexer)
165+
```
166+
158167
#### deploy(deployment: [AppDeployParams](#algokit_utils.applications.app_deployer.AppDeployParams)) → [AppDeployResult](#algokit_utils.applications.app_deployer.AppDeployResult)
159168

169+
Idempotently deploy (create if not exists, update if changed) an app against the given name for the given
170+
creator account, including deploy-time TEAL template placeholder substitutions (if specified).
171+
172+
To understand the architecture decisions behind this functionality please see
173+
[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)
174+
175+
**Note:** When using the return from this function be sure to check operation_performed to get access to
176+
return properties like transaction, confirmation and delete_result.
177+
178+
**Note:** if there is a breaking state schema change to an existing app (and on_schema_break is set to
179+
‘replace’) the existing app will be deleted and re-created.
180+
181+
**Note:** if there is an update (different TEAL code) to an existing app (and on_update is set to ‘replace’)
182+
the existing app will be deleted and re-created.
183+
184+
* **Parameters:**
185+
**deployment** – The arguments to control the app deployment
186+
* **Returns:**
187+
The result of the deployment
188+
* **Raises:**
189+
**ValueError** – If the app spec format is invalid
190+
* **Example:**
191+
```pycon
192+
>>> deployer.deploy(AppDeployParams(
193+
... create_params=AppCreateParams(
194+
... sender='SENDER_ADDRESS',
195+
... approval_program='APPROVAL PROGRAM',
196+
... clear_state_program='CLEAR PROGRAM',
197+
... schema={
198+
... 'global_byte_slices': 0,
199+
... 'global_ints': 0,
200+
... 'local_byte_slices': 0,
201+
... 'local_ints': 0
202+
... }
203+
... ),
204+
... update_params=AppUpdateParams(
205+
... sender='SENDER_ADDRESS'
206+
... ),
207+
... delete_params=AppDeleteParams(
208+
... sender='SENDER_ADDRESS'
209+
... ),
210+
... metadata=AppDeploymentMetaData(
211+
... name='my_app',
212+
... version='2.0',
213+
... updatable=False,
214+
... deletable=False
215+
... ),
216+
... on_schema_break=OnSchemaBreak.AppendApp,
217+
... on_update=OnUpdate.AppendApp
218+
... )
219+
... )
220+
```
221+
160222
#### get_creator_apps_by_name(\*, creator_address: str, ignore_cache: bool = False) → [ApplicationLookup](#algokit_utils.applications.app_deployer.ApplicationLookup)
161223

162-
Get apps created by an account
224+
Returns a lookup of name => app metadata (id, address, …metadata) for all apps created by the given account
225+
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
226+
the transaction note of the app creation transaction.
227+
228+
This function caches the result for the given creator account so that subsequent calls won’t require an indexer
229+
lookup.
230+
231+
If the AppManager instance wasn’t created with an indexer client, this function will throw an error.
232+
233+
* **Parameters:**
234+
* **creator_address** – The address of the account that is the creator of the apps you want to search for
235+
* **ignore_cache** – Whether or not to ignore the cache and force a lookup, default: use the cache
236+
* **Returns:**
237+
A name-based lookup of the app metadata
238+
* **Raises:**
239+
**ValueError** – If the app spec format is invalid
240+
* **Example:**
241+
```pycon
242+
>>> result = await deployer.get_creator_apps_by_name(creator)
243+
```

0 commit comments

Comments
 (0)