Algorand typed client Generator
Project description
AlgoKit Python client generator
This project generates a type-safe smart contract client in Python for the Algorand Blockchain that wraps the application client in AlgoKit Utils. It does this by reading an ARC-0032 application spec file.
Note There is also an equivalent TypeScript client generator.
Usage
Prerequisites
To be able to consume the generated file you need to include it in a Python project that has (at least) the following package installed:
poetry add algokit-utils@^1.2
Use
To install the generator as a CLI tool:
pipx install algokit-client-generator
Then to use it
algokitgen-py path/to/application.json path/to/output/client_generated.py
Or if you have AlgoKit 1.1+ installed
algokit generate client path/to/application.json --output path/to/output/client_generated.py
Examples
There are a range of examples that you can look at to see a source smart contract ({contract.py}
),
the generated client (client_generated.py
) and some tests that demonstrate how you can use the client (test_client.py
).
Contributing
If you want to contribute to this project the following information will be helpful.
Initial setup
-
Clone this repository locally
-
Install pre-requisites:
- Install
AlgoKit
- Link: Ensure you can executealgokit --version
. - Bootstrap your local environment; run
algokit bootstrap all
within this folder, which will:- Install
Poetry
- Link: The minimum required version is1.2
. Ensure you can executepoetry -V
and get1.2
+ - Run
poetry install
in the root directory, which will set up a.venv
folder with a Python virtual environment and also install all Python dependencies
- Install
- Install
-
Open the project and start debugging / developing via:
- VS Code
- Open the repository root in VS Code
- Install recommended extensions
- Run tests via test explorer
- IDEA (e.g. PyCharm)
- Open the repository root in the IDE
- It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment.
- Run tests
- Other
- Open the repository root in your text editor of choice
- Run
poetry run pytest
- VS Code
Subsequently
- If you update to the latest source code and there are new dependencies you will need to run
algokit bootstrap all
again - Follow step 3 above
Building examples
In the examples
folder there is a series of example contracts along with their generated client. These contracts are built using Beaker.
If you want to make changes to any of the smart contract examples and re-generate the ARC-0032 application.json files then change the corresponding examples/{contract}/{contract}.py
file and then run:
poetry run python -m examples
Or in Visual Studio Code you can use the default build task (Ctrl+Shift+B).
Continuous Integration / Continuous Deployment (CI/CD)
This project uses GitHub Actions to define CI/CD workflows, which are located in the .github/workflows
folder.
Approval tests
Making any changes to the generated code will result in the approval tests failing. The approval tests work by generating a version of client
and outputting it to ./examples/APP_NAME/client_generated.py
then comparing to the approved version ./examples/APP_NAME/client.ts
. If you
make a change and break the approval tests, you will need to update the approved version by overwriting it with the generated version.
You can run poe update-approvals
to update all approved clients in one go.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for algokit_client_generator-1.1.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 63b386431247913e6d4dc4668793c6eb60c71d59e9cca0ee05f803f284676783 |
|
MD5 | dbdf2148b6571df545689e16ade15933 |
|
BLAKE2b-256 | 3b397613ddc399ad7c33fb0ecec308c9b80d140e3ad57a404b69a5b7ba5eec0a |