Skip to content

Commit 5b77a55

Browse files
aorumbayevaorumbayev
authored
docs: patch typed client md file (#150)
1 parent 956cf77 commit 5b77a55

File tree

6 files changed

+427
-468
lines changed

6 files changed

+427
-468
lines changed

‎docs/html/_sources/capabilities/typed-app-clients.md.txt‎

Lines changed: 103 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ Typed application clients are the recommended way of interacting with smart cont
88

99
You can generate an app spec file:
1010

11-
- Using [Algorand Python](https://algorandfoundation.github.io/puya/#quick-start)
12-
- Using [TEALScript](https://tealscript.netlify.app/tutorials/hello-world/0004-artifacts/)
13-
- By hand by following the specification [ARC-56](https://github.com/algorandfoundation/ARCs/pull/258)/[ARC-32](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032.md)
14-
- Using [Beaker](https://algorand-devrel.github.io/beaker/html/usage.html) (PyTEAL) _(DEPRECATED)_
11+
- Using [Algorand Python](https://algorandfoundation.github.io/puya/#quick-start)
12+
- Using [TEALScript](https://tealscript.netlify.app/tutorials/hello-world/0004-artifacts/)
13+
- By hand by following the specification [ARC-56](https://github.com/algorandfoundation/ARCs/pull/258)/[ARC-32](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032.md)
14+
- Using [Beaker](https://algorand-devrel.github.io/beaker/html/usage.html) (PyTEAL) _(DEPRECATED)_
1515

1616
## Generating a typed client
1717

@@ -27,174 +27,158 @@ Note: AlgoKit Utils >= 3.0.0 is compatible with the older 1.x.x generated typed
2727

2828
To get an instance of a typed client you can use an [`AlgorandClient`](./algorand-client.md) instance or a typed app [`Factory`](#creating-a-typed-factory-instance) instance.
2929

30-
The approach to obtaining a client instance depends on how many app clients you require for a given app spec and if the app has already been deployed, which is summarised below:
30+
The approach to obtaining a client instance depends on how many app clients you require for a given app spec and if the app has already been deployed:
3131

3232
### App is deployed
3333

34-
<table>
35-
<thead>
36-
<tr>
37-
<th colspan="2">Resolve App by ID</th>
38-
<th colspan="2">Resolve App by Creator and Name</th>
39-
</tr>
40-
<tr>
41-
<th>Single App Client Instance</th>
42-
<th>Multiple App Client Instances</th>
43-
<th>Single App Client Instance</th>
44-
<th>Multiple App Client Instances</th>
45-
</tr>
46-
</thead>
47-
<tbody>
48-
<tr>
49-
<td>
34+
#### Resolve App by ID
35+
36+
**Single Typed App Client Instance:**
5037

5138
```python
52-
app_client = algorand.client.get_typed_app_client_by_id(MyContractClient, {
53-
app_id=1234,
54-
# ...
55-
})
56-
# or
57-
app_client = MyContractClient({
58-
algorand,
59-
app_id=1234,
60-
# ...
61-
})
39+
# Typed: Using the AlgorandClient extension method
40+
typed_client = algorand.client.get_typed_app_client_by_id(
41+
MyContractClient, # Generated typed client class
42+
app_id=1234,
43+
# ...
44+
)
45+
# or Typed: Using the generated client class directly
46+
typed_client = MyContractClient(
47+
algorand,
48+
app_id=1234,
49+
# ...
50+
)
6251
```
6352

64-
</td>
65-
<td>
53+
**Multiple Typed App Client Instances:**
6654

6755
```python
68-
app_client1 = factory.get_app_client_by_id(
69-
app_id=1234,
70-
# ...
56+
# Typed: Using a typed factory to get multiple client instances
57+
typed_client1 = typed_factory.get_app_client_by_id(
58+
app_id=1234,
59+
# ...
7160
)
72-
app_client2 = factory.get_app_client_by_id(
73-
app_id=4321,
74-
# ...
61+
typed_client2 = typed_factory.get_app_client_by_id(
62+
app_id=4321,
63+
# ...
7564
)
7665
```
7766

78-
</td>
79-
<td>
67+
#### Resolve App by Creator and Name
68+
69+
**Single Typed App Client Instance:**
8070

8171
```python
82-
app_client = algorand.client.get_typed_app_client_by_creator_and_name(
83-
MyContractClient,
84-
creator_address="CREATORADDRESS",
85-
app_name="contract-name",
86-
# ...
72+
# Typed: Using the AlgorandClient extension method
73+
typed_client = algorand.client.get_typed_app_client_by_creator_and_name(
74+
MyContractClient, # Generated typed client class
75+
creator_address="CREATORADDRESS",
76+
app_name="contract-name",
77+
# ...
8778
)
88-
# or
89-
app_client = MyContractClient.from_creator_and_name(
90-
algorand,
91-
creator_address="CREATORADDRESS",
92-
app_name="contract-name",
93-
# ...
79+
# or Typed: Using the static method on the generated client class
80+
typed_client = MyContractClient.from_creator_and_name(
81+
algorand,
82+
creator_address="CREATORADDRESS",
83+
app_name="contract-name",
84+
# ...
9485
)
9586
```
9687

97-
</td>
98-
<td>
88+
**Multiple Typed App Client Instances:**
9989

10090
```python
101-
app_client1 = factory.get_app_client_by_creator_and_name(
102-
creator_address="CREATORADDRESS",
103-
app_name="contract-name",
104-
# ...
91+
# Typed: Using a typed factory to get multiple client instances by name
92+
typed_client1 = typed_factory.get_app_client_by_creator_and_name(
93+
creator_address="CREATORADDRESS",
94+
app_name="contract-name",
95+
# ...
10596
)
106-
app_client2 = factory.get_app_client_by_creator_and_name(
107-
creator_address="CREATORADDRESS",
108-
app_name="contract-name-2",
109-
# ...
97+
typed_client2 = typed_factory.get_app_client_by_creator_and_name(
98+
creator_address="CREATORADDRESS",
99+
app_name="contract-name-2",
100+
# ...
110101
)
111102
```
112103

113-
</td>
114-
</tr>
115-
</tbody>
116-
</table>
117-
118-
To understand the difference between resolving by ID vs by creator and name see the underlying [app client documentation](./app-client.md#appclient).
119-
120104
### App is not deployed
121105

122-
<table>
123-
<thead>
124-
<tr>
125-
<th>Deploy a New App</th>
126-
<th>Deploy or Resolve App Idempotently by Creator and Name</th>
127-
</tr>
128-
</thead>
129-
<tbody>
130-
<tr>
131-
<td>
106+
#### Deploy a New App
132107

133108
```python
134-
app_client, response = factory.deploy(
135-
args=[],
136-
# ...
137-
)
138-
# or
139-
app_client, response = factory.send.create.METHODNAME(
140-
args=[],
141-
# ...
109+
# Typed: For typed clients, you call a specific creation method rather than generic 'create'
110+
typed_client, response = typed_factory.send.create.{METHODNAME}(
111+
# ...
142112
)
143113
```
144114

145-
</td>
146-
<td>
115+
#### Deploy or Resolve App Idempotently by Creator and Name
147116

148117
```python
149-
app_client, response = factory.deploy(
150-
app_name="contract-name",
151-
# ...
118+
# Typed: Using the deploy method on a typed factory
119+
typed_client, response = typed_factory.deploy(
120+
on_update=OnUpdate.UpdateApp,
121+
on_schema_break=OnSchemaBreak.ReplaceApp,
122+
# The parameters for create/update/delete would be specific to your generated client
123+
app_name="contract-name",
124+
# ...
152125
)
153126
```
154127

155-
</td>
156-
</tr>
157-
</tbody>
158-
</table>
159-
160128
### Creating a typed factory instance
161129

162130
If your scenario calls for an app factory, you can create one using the below:
163131

164132
```python
165-
factory = algorand.client.get_typed_app_factory(MyContractFactory)
166-
# or
167-
factory = MyContractFactory(algorand)
133+
# Typed: Using the AlgorandClient extension method
134+
typed_factory = algorand.client.get_typed_app_factory(MyContractFactory) # Generated factory class
135+
# or Typed: Using the factory class constructor directly
136+
typed_factory = MyContractFactory(algorand)
168137
```
169138

170139
## Client usage
171140

172-
See the [official usage docs](https://github.com/algorandfoundation/algokit-client-generator-py/blob/main/docs/usage.md) for full details.
141+
See the [official usage docs](https://github.com/algorandfoundation/algokit-client-generator-py/blob/main/docs/usage.md) for full details about typed clients.
173142

174-
For a simple example that deploys a contract and calls a `"hello"` method, see below:
143+
Below is a realistic example that deploys a contract, funds it if newly created, and calls a `"hello"` method:
175144

176145
```python
177-
# A similar working example can be seen in the AlgoKit init production smart contract templates, when using Python deployment
178-
# In this case the generated factory is called `HelloWorldAppFactory` and is in `./artifacts/HelloWorldApp/client.py`
179-
from artifacts.hello_world_app.client import HelloWorldAppClient, HelloArgs
180-
from algokit_utils import AlgorandClient
146+
# Typed: Complete example using a typed application client
147+
import algokit_utils
148+
from artifacts.hello_world.hello_world_client import (
149+
HelloArgs, # Generated args class
150+
HelloWorldFactory, # Generated factory class
151+
)
181152

182-
# These require environment variables to be present, or it will retrieve from default LocalNet
183-
algorand = AlgorandClient.from_environment()
184-
deployer = algorand.account.from_environment("DEPLOYER", AlgoAmount.from_algo(1))
153+
# Get Algorand client from environment variables
154+
algorand = algokit_utils.AlgorandClient.from_environment()
155+
deployer = algorand.account.from_environment("DEPLOYER")
185156

186157
# Create the typed app factory
187-
factory = algorand.client.get_typed_app_factory(HelloWorldAppFactory,
188-
creator_address=deployer,
189-
default_sender=deployer,
158+
typed_factory = algorand.client.get_typed_app_factory(
159+
HelloWorldFactory, default_sender=deployer.address
190160
)
191161

192-
# Create the app and get a typed app client for the created app (note: this creates a new instance of the app every time,
193-
# you can use .deploy() to deploy idempotently if the app wasn't previously
194-
# deployed or needs to be updated if that's allowed)
195-
app_client, response = factory.send.create()
162+
# Deploy idempotently - creates if it doesn't exist or updates if changed
163+
typed_client, result = typed_factory.deploy(
164+
on_update=algokit_utils.OnUpdate.AppendApp,
165+
on_schema_break=algokit_utils.OnSchemaBreak.AppendApp,
166+
)
196167

197-
# Make a call to an ABI method and print the result
198-
response = app_client.send.hello(args=HelloArgs(name="world"))
199-
print(response)
168+
# Fund the app with 1 ALGO if it's newly created
169+
if result.operation_performed in [
170+
algokit_utils.OperationPerformed.Create,
171+
algokit_utils.OperationPerformed.Replace,
172+
]:
173+
algorand.send.payment(
174+
algokit_utils.PaymentParams(
175+
amount=algokit_utils.AlgoAmount(algo=1),
176+
sender=deployer.address,
177+
receiver=typed_client.app_address,
178+
)
179+
)
180+
181+
# Call the hello method on the smart contract
182+
name = "world"
183+
response = typed_client.send.hello(args=HelloArgs(name=name)) # Using generated args class
200184
```

0 commit comments

Comments
 (0)