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.2b1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7c3d57ba9b4ba2d57a338dddd476c54464bcf7c8d524f50b40e8b23f6c76229a |
|
MD5 | eba2467bc51f59c10f2e9bfbddae71bd |
|
BLAKE2b-256 | 0714c396a89a60349f0b4844826400887e4267d9b231ebf5876a1c86960140fe |