Skip to content

Commit 403ad15

Browse files
exploreriiiexploreriii
authored
chore: Hiero python developer setup training (#920)
Signed-off-by: exploreriii <133720349+exploreriii@users.noreply.github.com>
1 parent 968d4cb commit 403ad15

File tree

8 files changed

+348
-0
lines changed

8 files changed

+348
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
88

99
### Added
1010

11+
- Added docs/sdk_developers/training/setup: a training to set up as a developer to the python sdk
1112
- Add example demonstrating usage of `CustomFeeLimit` in `examples/transaction/custom_fee_limit.py`
1213
- Added `.github/workflows/merge-conflict-bot.yml` to automatically detect and notify users of merge conflicts in Pull Requests.
1314
- Added validation logic in `.github/workflows/pr-checks.yml` to detect when no new chnagelog entries are added under [Unreleased]

‎docs/sdk_developers/training/setup/01_introduction_hiero_python_sdk.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
## What is the Hiero Python SDK?
2+
3+
The Hiero Python SDK enables developers to use Python to interact with the Hedera Blockchain/DLT Network.
4+
5+
For example, the Hiero Python SDK lets you:
6+
- Create a token on the Hedera network
7+
- Transfer Hbars between accounts
8+
- Mint NFTs
9+
- Create smart contracts
10+
11+
All using python code.
12+
13+
For example:
14+
```python
15+
create_tx = (
16+
TokenCreateTransaction()
17+
.set_token_name("Example Token")
18+
.set_token_symbol("EXT")
19+
.set_treasury_account_id(operator_id)
20+
.freeze_with(client)
21+
.sign(operator_key)
22+
.execute(client)
23+
)
24+
25+
token_id = create_tx.token_id
26+
print(f"🎉 Created a new token on the Hedera network with ID: {token_id}")
27+
```
28+

‎docs/sdk_developers/training/setup/02_installing_hiero_python_sdk.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
## Quick Set-up
2+
3+
### Fork the Hiero Python SDK
4+
Create your GitHub fork, then clone your fork locally and connect it to the upstream repo to make it easy to sync in the future.
5+
6+
```bash
7+
git clone https://github.com/YOUR_GITHUB_USERNAME/hiero-sdk-python.git
8+
cd hiero-sdk-python
9+
# Add upstream for future syncing
10+
git remote add upstream https://github.com/hiero-ledger/hiero-sdk-python.git
11+
```
12+
13+
### Install Packages
14+
This installs the package manager uv:
15+
```bash
16+
curl -LsSf https://astral.sh/uv/install.sh | sh
17+
exec $SHELL
18+
```
19+
20+
Now install dependencies as per pyproject.toml:
21+
```bash
22+
uv sync
23+
```
24+
25+
### Generate Protobufs
26+
The SDK uses protobuf definitions to generate gRPC and model classes.
27+
28+
Run:
29+
```bash
30+
uv run python generate_proto.py
31+
```
32+

‎docs/sdk_developers/training/setup/03_setting_up_env.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
## Quick Start Env
2+
3+
### 1. Create Testnet Account
4+
5+
Create a testnet Hedera Portal account [here](https://portal.hedera.com/dashboard).
6+
7+
### 2. Create .env
8+
Create a file named `.env` in your project root.
9+
10+
Add, ignoring the < > and without any quotation marks:
11+
12+
```bash
13+
OPERATOR_ID=<YOUR_OPERATOR_ID> #your account id
14+
OPERATOR_KEY=<YOUR_PRIVATE_KEY> #your testnet private key (can be ECDSA, ED25519 or DER)
15+
NETWORK=testnet
16+
```
17+
18+
For example:
19+
```bash
20+
OPERATOR_ID=0.0.1000000
21+
OPERATOR_KEY=123456789
22+
NETWORK=testnet
23+
```
24+
25+
We have added `.env` to `.gitignore` to help ensure its never committed.
26+
27+

‎docs/sdk_developers/training/setup/04_using_env_variables.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
## Loading Credentials Into Scripts
2+
3+
Your credentials stored at .env are required to run transactions on Hedera testnet.
4+
5+
- dotenv has load_dotenv() to load credentails
6+
- os has getenv() to read the credentials
7+
8+
We use both, for example:
9+
10+
```python
11+
# Import dotenv and os
12+
from dotenv import load_dotenv
13+
from os import getenv
14+
15+
# Load variables from .env into environment
16+
load_dotenv()
17+
18+
# Read the variables
19+
operator_id_string = getenv('OPERATOR_ID')
20+
operator_key_string = getenv('OPERATOR_KEY')
21+
22+
# Printing confirming loading and reading
23+
print(f"Congratulations! We loaded your operator ID: {operator_id_string}.")
24+
print("Your operator key was loaded successfully (not printed for security).")
25+
26+
```
27+

‎docs/sdk_developers/training/setup/05_network_client_setup.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
## Setup Network and Client
2+
3+
All transactions and queries on the Hedera network require a network and client set-up.
4+
5+
To do this you'll need to import the relevant functionality, variables from .env and attach them to the Network and Client classes as appropriate.
6+
7+
### Worked Example
8+
```python
9+
import sys
10+
from dotenv import load_dotenv
11+
from os import getenv
12+
13+
from hiero_sdk_python.account.account_id import AccountId
14+
from hiero_sdk_python.crypto.private_key import PrivateKey
15+
from hiero_sdk_python.client.client import Client
16+
from hiero_sdk_python.client.network import Network
17+
from hiero_sdk_python.tokens.token_create_transaction import TokenCreateTransaction
18+
from hiero_sdk_python.client import client
19+
from hiero_sdk_python.response_code import ResponseCode
20+
21+
# 1. Setup Client
22+
load_dotenv()
23+
operator_id = AccountId.from_string(getenv('OPERATOR_ID',''))
24+
operator_key = PrivateKey.from_string(getenv('OPERATOR_KEY',''))
25+
26+
network = Network(getenv('NETWORK',''))
27+
client = Client(network)
28+
client.set_operator(operator_id, operator_key)
29+
30+
# 2. Build the transaction
31+
create_tx = (
32+
TokenCreateTransaction()
33+
.set_token_name("Example Token")
34+
.set_token_symbol("EXT")
35+
.set_treasury_account_id(operator_id)
36+
.set_initial_supply(100000)
37+
.freeze_with(client)
38+
.sign(operator_key)
39+
)
40+
41+
# 3. Execute and get receipt
42+
receipt = create_tx.execute(client)
43+
44+
# 4. Validate Success
45+
if receipt.status != ResponseCode.SUCCESS:
46+
print(f"Token creation on Hedera failed: {ResponseCode(receipt.status).name}")
47+
sys.exit(1)
48+
49+
# 5. Extract the Token ID
50+
token_id = receipt.token_id
51+
print(f"🎉 Created new token on the Hedera network with ID: {token_id}")
52+
```
53+
54+
### Extra Support
55+
Read about Network and Client in more detail [here](docs/sdk_developers/training/network_and_client.md)

‎docs/sdk_developers/training/setup/06_importing_hiero_files.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
## Importing Functionality To Use In Scripts
2+
3+
Import all modules, classes and types required for your transaction to work by specifying their exact path after src/.
4+
5+
### Example: Importing TokenCreateTransactionClass
6+
TokenCreateTransaction class is located inside src/hiero_sdk_python/tokens/token_create_transaction.py:
7+
8+
Therefore:
9+
```python
10+
from hiero_sdk_python.tokens.token_create_transaction import TokenCreateTransaction
11+
```
12+
13+
### Example: Importing token_create_transaction.py
14+
token_create_transaction.py is located at src/hiero_sdk_python/tokens.py:
15+
16+
Therefore:
17+
```python
18+
from hiero_sdk_python.tokens import token_create_transaction
19+
```
20+
21+
### Advanced Example
22+
You'll need to import everything you require.
23+
24+
In this more advanced example, we are using imports to load env, to set up the client and network, and to form the Token Create Transaction and check the response:
25+
26+
```python
27+
import sys
28+
from dotenv import load_dotenv
29+
from os import getenv
30+
31+
from hiero_sdk_python.account.account_id import AccountId
32+
from hiero_sdk_python.crypto.private_key import PrivateKey
33+
from hiero_sdk_python.client.client import Client
34+
from hiero_sdk_python.client.network import Network
35+
from hiero_sdk_python.tokens.token_create_transaction import TokenCreateTransaction
36+
from hiero_sdk_python.response_code import ResponseCode
37+
38+
# 1. Setup Client
39+
load_dotenv()
40+
operator_id = AccountId.from_string(getenv('OPERATOR_ID',''))
41+
operator_key = PrivateKey.from_string(getenv('OPERATOR_KEY',''))
42+
43+
network = Network(getenv('NETWORK',''))
44+
client = Client(network)
45+
client.set_operator(operator_id, operator_key)
46+
47+
# 2. Build the transaction
48+
create_tx = (
49+
TokenCreateTransaction()
50+
.set_token_name("Example Token")
51+
.set_token_symbol("EXT")
52+
.set_treasury_account_id(operator_id)
53+
.set_initial_supply(100000)
54+
.freeze_with(client)
55+
.sign(operator_key)
56+
)
57+
58+
# 3. Execute and get receipt
59+
receipt = create_tx.execute(client)
60+
61+
# 4. Validate Success
62+
if receipt.status != ResponseCode.SUCCESS:
63+
print(f"Token creation on Hedera failed: {ResponseCode(receipt.status).name}")
64+
sys.exit(1)
65+
66+
# 5. Extract the Token ID
67+
token_id = receipt.token_id
68+
print(f"🎉 Created new token on the Hedera network with ID: {token_id}")
69+
```
70+
71+
## Extra Support
72+
It takes time to be familiar with where everything is located to import correctly.
73+
74+
- For reference, look at the [examples](examples/)
75+
- For an explanation of the project structure read [project_structure.md](docs/sdk_developers/project_structure.md).
76+
- Set up [Pylance](docs/sdk_developers/pylance.md) to help you spot errors in your import locations

‎docs/sdk_developers/training/setup/07_lab_set_up.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
## Lab: Setup
2+
3+
In this lab, you'll set up a Network and Client instance and run an account balance query on the Hedera network.
4+
5+
## Step 1: Create a file at /examples/lab1.py
6+
Create a lab1 practice file and add a main function:
7+
```python
8+
def main():
9+
# Placeholder to call functions
10+
11+
if __name__ == "__main__":
12+
main()
13+
```
14+
You'll be running this by: "uv run /examples/practice.py"
15+
16+
## Step 2: Create a function: set_up_network_and_client
17+
In this function be sure to:
18+
- Import required packages
19+
- Load OPERATOR_ID as operator_id_string, OPERATOR_KEY as operator_key_string
20+
- Connect to Hedera testnet
21+
- Connect your credentials to the Client
22+
23+
Note: Check it works by running the file at "uv run /examples/practice.py"
24+
```python
25+
def set_up_network_and_client():
26+
# Placeholder to set up network and client
27+
28+
def main():
29+
# Call the function and return any needed variables
30+
set_up_network_and_client()
31+
32+
if __name__ == "__main__":
33+
main()
34+
```
35+
36+
## Step 3: Create query_account_balance
37+
- Pass in the client and operator_key
38+
- Perform an account balance query
39+
- Print the hbar balance
40+
- Print the token balance
41+
- Call this from main()
42+
43+
Syntax:
44+
```python
45+
balance = CryptoGetAccountBalanceQuery(operator_id).execute(client)
46+
print(f" Hbar balance is {balance.hbars}")
47+
print(f" Token balance is {balance.token_balances}")
48+
```
49+
50+
Your main will now look more like this:
51+
```python
52+
def main():
53+
client, operator_id = set_up_network_and_client()
54+
query_account_balance(client, operator_id)
55+
56+
if __name__ == "__main__":
57+
main()
58+
```
59+
60+
Check it all works by running it "uv run /examples/practice.py"
61+
62+
63+
#### Solution: WARNING!
64+
65+
```python
66+
from dotenv import load_dotenv
67+
from os import getenv
68+
from hiero_sdk_python.account.account_id import AccountId
69+
from hiero_sdk_python.crypto.private_key import PrivateKey
70+
from hiero_sdk_python.client.client import Client
71+
from hiero_sdk_python.client.network import Network
72+
from hiero_sdk_python.query.account_balance_query import CryptoGetAccountBalanceQuery
73+
74+
def set_up_network_and_client():
75+
load_dotenv()
76+
77+
network_name = getenv('NETWORK','')
78+
network = Network(network_name)
79+
client = Client(network)
80+
81+
operator_id_string = getenv('OPERATOR_ID','')
82+
operator_key_string = getenv('OPERATOR_KEY','')
83+
84+
operator_id = AccountId.from_string(operator_id_string)
85+
operator_key = PrivateKey.from_string(operator_key_string)
86+
87+
client.set_operator(operator_id, operator_key)
88+
print(f"Connected to Hedera {network_name} as operator {client.operator_account_id}")
89+
return client, operator_id
90+
91+
def query_account_balance(client, operator_id):
92+
balance = CryptoGetAccountBalanceQuery(operator_id).execute(client)
93+
print(f" Hbar balance is {balance.hbars}")
94+
print(f" Token balance is {balance.token_balances}")
95+
96+
def main():
97+
client, operator_id = set_up_network_and_client()
98+
query_account_balance(client, operator_id)
99+
100+
if __name__ == "__main__":
101+
main()
102+
```

0 commit comments

Comments
 (0)