Skip to content

chore: Add setup instructions for running example scripts #195

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+88 −62
Open

chore: Add setup instructions for running example scripts #195

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 88 additions & 62 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,103 +1,92 @@
# Hiero SDK in Python
This is a Python SDK for interacting with the Hedera Hashgraph platform. It allows developers to:

[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hiero-ledger/hiero-sdk-python/badge)](https://scorecard.dev/viewer/?uri=github.com/hiero-ledger/hiero-sdk-python)
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/10697/badge)](https://bestpractices.coreinfrastructure.org/projects/10697)
[![License](https://img.shields.io/badge/license-apache2-blue.svg)](LICENSE)
Manage Token Transactions like Create, Mint Fungible, Mint Non-Fungible, Associate, Dissociate, Transfer, Freeze, Unfreeze & Delete

This is a Python SDK for interacting with the Hedera Hashgraph platform. It allows developers to:
Manage Consensus Transactions like Topic Create, Update, Delete

Submit Topic Messages

Query Account Balance, Transaction Receipts, Topic Infos and Messages

Table of Contents

Installation

Installing from PyPI

Installing from Source

Local Editable Installation

- Manage Token Transactions like Create, Mint Fungible, Mint Non-Fungible, Associate, Dissociate, Transfer, Freeze, Unfreeze & Delete
- Manage Consensus Transactions like Topic Create, Update, Delete
- Submit Topic Messages
- Query Account Balance, Transaction Receipts, Topic Infos and Messages
Environment Setup

## Table of Contents
Running Tests

- [Installation](#installation)
- [Installing from PyPI](#installing-from-pypi)
- [Installing from Source](#installing-from-source)
- [Local Editable Installation](#local-editable-installation)
- [Environment Setup](#environment-setup)
- [Running Tests](#running-tests)
- [Contributing](#contributing)
Running Example Scripts

## Installation
Contributing

### Installing from PyPI
Installation

Installing from PyPI

The latest release of this SDK is published to PyPI. You can install it with:

```
pip install --upgrade pip
pip install hiero_sdk_python
```

This will pull down a stable release along with the required dependencies.


### Installing from Source
Installing from Source

You can also clone the repo and install dependencies using uv:

1. Install `uv`:
Install uv:

`uv` is an ultra-fast Python package and project manager. It replaces `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`,
`virtualenv`, and more.
uv is an ultra-fast Python package and project manager. It replaces pip, pip-tools, pipx, poetry, pyenv,
virtualenv, and more.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

If on macOS, you can also install `uv` using Homebrew:
If on macOS, you can also install uv using Homebrew:

```bash
brew install uv
```

Other installation methods can be found [here](https://docs.astral.sh/uv/getting-started/installation/).
Other installation methods can be found here.

2. Clone this repository:
Clone this repository:

```bash
git clone https://github.com/hiero-ledger/hiero-sdk-python.git
cd hiero-sdk-python
```

3. Install dependencies:
Install dependencies:

One of the really nice features of `uv` is that it will download and manage the correct version of python and build
with the correct version of python based on the `.python-version` file in the project. This means you don't have to
One of the really nice features of uv is that it will download and manage the correct version of python and build
with the correct version of python based on the .python-version file in the project. This means you don't have to
worry about managing multiple versions of python on your machine!

```bash
uv sync
sh generate_proto.sh
```

To update to a newer version of the protobuf libraries, edit the `generate_proto.py` file and change the version number
To update to a newer version of the protobuf libraries, edit the generate_proto.py file and change the version number
and then rerun it.


### Local Editable Installation
Local Editable Installation

For active development, you can install the repo in editable mode. That way, changes in your local code are immediately reflected when you import:

```
git clone https://github.com/hiero-ledger/hiero-sdk-python.git
cd hiero-sdk-python
pip install --upgrade pip
pip install -e .
```

Now you can run example scripts like python `examples/account_create.py`, and it will import from your local hiero_sdk_python code.
Now you can run example scripts like python examples/account_create.py, and it will import from your local hiero_sdk_python code.


## Environment Setup
Environment Setup

Before using the SDK, you need to configure your environment variables for the operator account and other credentials.
Create a .env file in the root of your project with the following (replace with your environment variables):

```
OPERATOR_ID=0.0.1234xx
OPERATOR_KEY=af20e47d590300506032b657004220420...
ADMIN_KEY=af20e47d59032b65700321009308ecfdf...
Expand All @@ -108,27 +97,26 @@ TOKEN_ID=0.0.100xx
TOPIC_ID=0.0.200xx
FREEZE_ACCOUNT_ID=0.0.100
NETWORK=testnet
```

A [sample .env](.env.example) file is provided in the root of this project. If you do not have an account on
the Hedera testnet, you can easily get one from the [Hedera Portal](https://portal.hedera.com/). Learn more about
testnet [here](https://docs.hedera.com/guides/testnet).
A sample .env file is provided in the root of this project. If you do not have an account on
the Hedera testnet, you can easily get one from the Hedera Portal. Learn more about
testnet here.

## Running Tests
Running Tests

To run the test suite for the SDK, use the following command:
```
uv run pytest
```

uv run pytest

The test file in the root of this project will be automatically run when pushing onto a branch.
This is done by running 'Hiero Solo Action'. Read more about it here:

- [Github Marketplace](https://github.com/marketplace/actions/hiero-solo-action)
- [Blog Post by Hendrik Ebbers](https://dev.to/hendrikebbers/ci-for-hedera-based-projects-2nja)
Github Marketplace

Blog Post by Hendrik Ebbers

Output:

#### Output:
```
Account creation successful. New Account ID: 0.0.5025xxx
New Account Private Key: 228a06c363b0eb328434d51xxx...
New Account Public Key: 8f444e36e8926def492adxxx...
Expand All @@ -144,7 +132,45 @@ Topic creation successful.
Topic Message submitted.
Topic update successful.
Topic deletion successful.
```

Running Example Scripts

To run the example scripts inside the examples/ directory, follow these steps:

1️⃣ Create a .env file inside /examples

cd examples
touch .env

2️⃣ Add the following content to .env

OPERATOR_ID=0.0.xxxxx
OPERATOR_KEY=302e020100300506032b6570...

You only need these two fields for most examples. Add more if the script requires.

3️⃣ Get your Testnet credentials

Go to https://portal.hedera.com

Sign up or log in

Copy your Account ID and Private Key

Paste into the .env file you just created

4️⃣ Run an example script

cd examples
python3 account_create.py

Make sure dependencies are installed using:

pip install -r requirements.txt

Now you're ready to explore and run all the example scripts! 🎉



## Contributing

Expand Down
Loading