algokit-client-generator 2.2.1b3__tar.gz

algokit_client_generator-2.2.1b3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Algorand Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

algokit_client_generator-2.2.1b3/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: algokit-client-generator
+Version: 2.2.1b3
+Summary: Algorand typed client Generator
+Author: Algorand Foundation
+Author-email: Algorand Foundation <contact@algorand.foundation>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: algokit-utils>=4.0.1,<5
+Requires-Python: >=3.10, <4
+Description-Content-Type: text/markdown
+
+# 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](https://github.com/algorandfoundation/algokit-utils-py/blob/main/docs/src/content/docs/concepts/building/app-client.md) in [AlgoKit Utils](https://github.com/algorandfoundation/algokit-utils-py) and tailors it to a specific smart contract. It does this by reading an [ARC-56](https://github.com/algorandfoundation/ARCs/pull/258) or [ARC-32](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032.md) 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:
+
+```bash
+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](https://github.com/algorandfoundation/algokit-cli) 1.1+ installed
+
+```commandline
+algokit generate client path/to/application.json --output path/to/output/client_generated.py
+```
+
+### Generation modes
+
+The generator supports two modes:
+
+#### Full mode (default)
+
+```bash
+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
+
+```bash
+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](./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](https://github.com/algorandfoundation/algokit-cli#install): Ensure you can execute `algokit --version`.
+    - Bootstrap your local environment; run `algokit project bootstrap all` within this folder, which will:
+        - Install `uv` - [Link](https://docs.astral.sh/uv/getting-started/installation/) 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](https://github.com/algorandfoundation/puya), [Algorand TypeScript](https://github.com/algorandfoundation/puya-ts), and [TealScript](https://github.com/algorandfoundation/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:
+
+```bash
+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](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions) to define CI/CD workflows, which are located in the [`.github/workflows`](./.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.

algokit_client_generator-2.2.1b3/README.md

@@ -0,0 +1,124 @@
+# 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](https://github.com/algorandfoundation/algokit-utils-py/blob/main/docs/src/content/docs/concepts/building/app-client.md) in [AlgoKit Utils](https://github.com/algorandfoundation/algokit-utils-py) and tailors it to a specific smart contract. It does this by reading an [ARC-56](https://github.com/algorandfoundation/ARCs/pull/258) or [ARC-32](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032.md) 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:
+
+```bash
+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](https://github.com/algorandfoundation/algokit-cli) 1.1+ installed
+
+```commandline
+algokit generate client path/to/application.json --output path/to/output/client_generated.py
+```
+
+### Generation modes
+
+The generator supports two modes:
+
+#### Full mode (default)
+
+```bash
+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
+
+```bash
+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](./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](https://github.com/algorandfoundation/algokit-cli#install): Ensure you can execute `algokit --version`.
+    - Bootstrap your local environment; run `algokit project bootstrap all` within this folder, which will:
+        - Install `uv` - [Link](https://docs.astral.sh/uv/getting-started/installation/) 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](https://github.com/algorandfoundation/puya), [Algorand TypeScript](https://github.com/algorandfoundation/puya-ts), and [TealScript](https://github.com/algorandfoundation/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:
+
+```bash
+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](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions) to define CI/CD workflows, which are located in the [`.github/workflows`](./.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.

algokit_client_generator-2.2.1b3/pyproject.toml

@@ -0,0 +1,186 @@
+[project]
+name = "algokit-client-generator"
+version = "2.2.1-beta.3"
+description = "Algorand typed client Generator"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.10,<4"
+dependencies = ["algokit-utils>=4.0.1,<5"]
+
+[[project.authors]]
+name = "Algorand Foundation"
+email = "contact@algorand.foundation"
+
+[project.scripts]
+algokitgen-py = "algokit_client_generator.cli:main"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.8.6,<0.13.0",
+    "mypy",
+    "pytest",
+    "pytest-cov",
+    "pip-audit>=2.5.5,<3",
+    "python-semantic-release>=10,<11",
+    "pre-commit>=3.3.2,<5.0.0",
+    "poethepoet>=0.20,<0.37",
+    "pytest-xdist>=3.5.0,<4",
+    "puyapy>=5.8.0,<6; python_version >= '3.12'",
+    "algorand-python>=3.4.0,<4; python_version >= '3.12'",
+    "setuptools>=83.0,<84.0",
+    "pytest-sugar>=1.0.0,<2",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.12"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 120
+extend-exclude = ["docs"]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "F",
+    "E",
+    "W",
+    "C90",
+    "I",
+    "N",
+    "UP",
+    "YTT",
+    "ANN",
+    "FBT",
+    "B",
+    "A",
+    "C4",
+    "DTZ",
+    "T10",
+    "ISC",
+    "ICN",
+    "PIE",
+    "PYI",
+    "PT",
+    "Q",
+    "RSE",
+    "RET",
+    "SLF",
+    "SIM",
+    "TID",
+    "PTH",
+    "ERA",
+    "PGH",
+    "PL",
+    "RUF",
+]
+ignore = [
+    "RET505",
+    "SIM108",
+    "PLR2004",
+    "E111",
+    "E117",
+    "ISC001",
+    "ISC002",
+    "Q000",
+    "Q001",
+    "Q002",
+    "Q003",
+    "W191",
+    "B018",
+    "N815",
+    "N801",
+    "PGH004",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/algokit_client_generator/generator.py" = ["ARG001"]
+
+[tool.ruff.lint.flake8-annotations]
+allow-star-arg-any = true
+suppress-none-returning = true
+
+[tool.poe.tasks]
+update-approvals = "uv run python -m scripts.update_approvals"
+
+[tool.poe.tasks.release-preview]
+help = "Preview current and next prerelease version"
+
+[[tool.poe.tasks.release-preview.sequence]]
+cmd = "git describe --tags --abbrev=0"
+
+[[tool.poe.tasks.release-preview.sequence]]
+cmd = "uv run semantic-release version --print-tag --as-prerelease"
+
+[tool.poe.tasks.release-dry-run-beta]
+shell = "uv run semantic-release --noop -vv version --as-prerelease --prerelease-token beta --print-tag"
+help = "Dry-run beta release (no changes made)"
+
+[tool.pytest.ini_options]
+pythonpath = [
+    "src",
+    "tests",
+]
+
+[tool.mypy]
+files = [
+    "src",
+    "tests",
+]
+exclude = ["dist"]
+python_version = "3.10"
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unused_configs = true
+warn_unreachable = true
+warn_return_any = true
+strict = true
+disallow_untyped_decorators = true
+disallow_any_generics = false
+implicit_reexport = false
+show_error_codes = true
+disable_error_code = ["return"]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+build_command = "uv build"
+major_on_zero = true
+commit_message = """
+{version}
+
+skip-checks: true"""
+tag_format = "v{version}"
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease_token = "beta"
+prerelease = false
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = [
+    "build",
+    "chore",
+    "ci",
+    "docs",
+    "feat",
+    "fix",
+    "perf",
+    "style",
+    "refactor",
+    "test",
+]
+minor_tags = ["feat"]
+patch_tags = [
+    "fix",
+    "perf",
+    "build",
+    "chore",
+    "refactor",
+]
+
+[tool.semantic_release.remote]
+type = "github"
+
+[tool.semantic_release.remote.token]
+env = "GH_TOKEN"

algokit_client_generator-2.2.1b3/pyproject.toml.orig

@@ -0,0 +1,186 @@
+[project]
+name = "algokit-client-generator"
+version = "2.2.1-beta.3"
+description = "Algorand typed client Generator"
+authors = [
+    { name = "Algorand Foundation", email = "contact@algorand.foundation" },
+]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.10,<4"
+dependencies = [
+    "algokit-utils>=4.0.1,<5",
+]
+
+[project.scripts]
+algokitgen-py = "algokit_client_generator.cli:main"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.8.6,<0.13.0",
+    "mypy",
+    "pytest",
+    "pytest-cov",
+    "pip-audit>=2.5.5,<3",
+    "python-semantic-release>=10,<11",
+    "pre-commit>=3.3.2,<5.0.0",
+    "poethepoet>=0.20,<0.37",
+    "pytest-xdist>=3.5.0,<4",
+    "puyapy>=5.8.0,<6; python_version >= '3.12'",
+    "algorand-python>=3.4.0,<4; python_version >= '3.12'",
+    "setuptools>=83.0,<84.0",
+    "pytest-sugar>=1.0.0,<2",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.12"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 120
+lint.select = [
+    # all possible codes as of this ruff version are listed here,
+    # ones we don't want/need are commented out to make it clear
+    # which have been omitted on purpose vs which ones get added
+    # in new ruff releases and should be considered for enabling
+    "F",   # pyflakes
+    "E",
+    "W",   # pycodestyle
+    "C90", # mccabe
+    "I",   # isort
+    "N",   # PEP8 naming
+    "UP",  # pyupgrade
+    "YTT", # flake8-2020
+    "ANN", # flake8-annotations
+    # "S",    # flake8-bandit
+    # "BLE",  # flake8-blind-except
+    "FBT", # flake8-boolean-trap
+    "B",   # flake8-bugbear
+    "A",   # flake8-builtins
+    # "COM",  # flake8-commas
+    "C4",  # flake8-comprehensions
+    "DTZ", # flake8-datetimez
+    "T10", # flake8-debugger
+    # "DJ",   # flake8-django
+    # "EM",   # flake8-errmsg
+    # "EXE",  # flake8-executable
+    "ISC", # flake8-implicit-str-concat
+    "ICN", # flake8-import-conventions
+    # "G",    # flake8-logging-format
+    # "INP",  # flake8-no-pep420
+    "PIE", # flake8-pie
+    # "T20",    # flake8-print
+    "PYI", # flake8-pyi
+    "PT",  # flake8-pytest-style
+    "Q",   # flake8-quotes
+    "RSE", # flake8-raise
+    "RET", # flake8-return
+    "SLF", # flake8-self
+    "SIM", # flake8-simplify
+    "TID", # flake8-tidy-imports
+    "PTH", # flake8-use-pathlib
+    "ERA", # eradicate
+    # "PD",   # pandas-vet
+    "PGH", # pygrep-hooks
+    "PL",  # pylint
+    # "TRY",  # tryceratops
+    # "NPY",  # NumPy-specific rules
+    "RUF", # Ruff-specific rules
+]
+lint.ignore = [
+    "RET505",  # allow else after return
+    "SIM108",  # allow if-else in place of ternary
+    "PLR2004", # magic values... can't configure to ignore simple low value ints like 2
+    # To avoid conflict with ruff formatter. More details on https://docs.astral.sh/ruff/formatter/#conflicting-lint-rules
+    "E111",   # indentation is not a multiple of four
+    "E117",   # over-indented
+    "ISC001", # single line implicit string concatenation
+    "ISC002", # multi line implicit string concatenation
+    "Q000",   # bad quotes inline string
+    "Q001",   # bad quotes multiline string
+    "Q002",   # bad quotes docstring
+    "Q003",   # avoidable escaped quotes
+    "W191",   # indentation contains tabs
+    "B018",   # found useless expression
+    "N815",   # mixed case variable in class scope
+    "N801",   # invalid class name
+    "PGH004", # blanket noqa
+]
+# Exclude a variety of commonly ignored directories.
+extend-exclude = ["docs"]
+# Assume Python 3.10.
+target-version = "py310"
+
+[tool.ruff.lint.per-file-ignores]
+"src/algokit_client_generator/generator.py" = ["ARG001"]
+
+[tool.ruff.lint.flake8-annotations]
+allow-star-arg-any = true
+suppress-none-returning = true
+
+[tool.poe.tasks]
+update-approvals = "uv run python -m scripts.update_approvals"
+
+[tool.poe.tasks.release-preview]
+sequence = [
+    # `git describe` only sees tags in the history of HEAD; `--print-last-released-tag` also reports the v3 line tags
+    { cmd = "git describe --tags --abbrev=0" },
+    { cmd = "uv run semantic-release version --print-tag --as-prerelease" },
+]
+help = "Preview current and next prerelease version"
+
+[tool.poe.tasks.release-dry-run-beta]
+shell = "uv run semantic-release --noop -vv version --as-prerelease --prerelease-token beta --print-tag"
+help = "Dry-run beta release (no changes made)"
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "tests"]
+
+[tool.mypy]
+files = ["src", "tests"]
+exclude = ["dist"]
+python_version = "3.10"
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unused_configs = true
+warn_unreachable = true
+warn_return_any = true
+strict = true
+disallow_untyped_decorators = true
+disallow_any_generics = false
+implicit_reexport = false
+show_error_codes = true
+disable_error_code = ['return']
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+build_command = "uv build"
+major_on_zero = true
+commit_message = "{version}\n\nskip-checks: true"
+tag_format = "v{version}"
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease_token = "beta"
+prerelease = false
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = [
+    "build",
+    "chore",
+    "ci",
+    "docs",
+    "feat",
+    "fix",
+    "perf",
+    "style",
+    "refactor",
+    "test",
+]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf", "build", "chore", "refactor"]
+
+[tool.semantic_release.remote]
+type = "github"
+token = { env = "GH_TOKEN" }

algokit_client_generator-2.2.1b3/src/algokit_client_generator/__init__.py

@@ -0,0 +1,3 @@
+from algokit_client_generator.writer import generate_client
+
+__all__ = ["generate_client"]

algokit_client_generator-2.2.1b3/src/algokit_client_generator/__main__.py

@@ -0,0 +1,3 @@
+from algokit_client_generator.cli import main
+
+main()