AlgoKit Python client generator (algokit-client-generator-py)

This project generates a type-safe smart contract client in Python for the Algorand Blockchain that wraps the application client in AlgoKit Utils and tailors it to a specific smart contract. It does this by reading an ARC-56 or ARC-32 application spec file and generating a client which exposes methods for each ABI method in the target smart contract, along with helpers to create, update, and delete the application.

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@^4.0.1

Note: version 2 of the generator requires algokit-utils@^4.0.1 (with py-algorand-sdk v2); it is not compatible with AlgoKit Utils v5, which decoupled from py-algorand-sdk.

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

Generation modes

The generator supports two modes:

Full mode (default)

algokitgen-py path/to/application.json path/to/output/client_generated.py

• Includes factory class for creating and deploying smart contracts
• Includes deployment types and methods
• Includes all deployment-related metadata (source code, bytecode, template variables)
• Includes client class for interacting with already deployed contracts
• Best for development, deployment and interaction workflows or where output size is less important

Minimal mode

algokitgen-py path/to/application.json path/to/output/client_generated.py --mode minimal

• Excludes factory class and deployment capabilities
• Excludes deployment-related metadata to reduce output size
• Only includes client class for interacting with already deployed contracts
• Best for scenarios that only need to interact with existing contracts

Examples

There are a range of examples that you can look at to see a source smart contract (e.g. {app_name}/contract.py), the generated client (artifacts/{app_name}/{app_name}_client.py) and some tests that demonstrate how you can use the client (tests/{app_name}_test_client.py).

Contributing

If you want to contribute to this project the following information will be helpful.

Initial setup

1. Clone this repository locally

2. Install pre-requisites:

   • Install AlgoKit - Link: Ensure you can execute algokit --version.
   • Bootstrap your local environment; run algokit project bootstrap all within this folder, which will:
     • Install uv - Link if it is not already installed. Ensure you can execute uv --version
     • Run uv sync in the root directory, which will set up a .venv folder with a Python virtual environment and also install all Python dependencies

3. Open the project and start debugging/developing via:

   • VS Code
     1. Open the repository root in VS Code
     2. Install recommended extensions
     3. Run tests via test explorer
   • IDEA (e.g. PyCharm)
     1. Open the repository root in the IDE
     2. It should automatically detect it's a uv project and set up a Python interpreter and virtual environment.
     3. Run tests
   • Other
     1. Open the repository root in your text editor of choice
     2. Run uv run pytest

Subsequently

1. If you update to the latest source code and there are new dependencies you will need to run algokit project bootstrap all again
2. 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 originally written in various languages including Algorand Python, Algorand TypeScript, and TealScript.

Some contracts are directly imported through the ARC-32/56 app spec and not through contract source code.

If you want to make changes to any of the smart contract examples and re-generate the ARC-32/56 JSON specs files then change the corresponding examples/smart_contracts/{app_name}/contract.py file and then run:

uv run python -m examples

Or in Visual Studio Code you can use the default build task (Ctrl+Shift+B).

To regenerate the generated clients run uv run poe update-approvals.

This package currently depends on Python 3.10, however the development depends on Python 3.12. This is represented by the pyproject.toml file which requires 3.10 with additional requirements on dev dependencies.

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.py. 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 uv run poe update-approvals to update all approved clients in one go.