From 226a32a999d7d7b14937619eb91a4acfeace491a Mon Sep 17 00:00:00 2001 From: Altynbek Orumbayev Date: Wed, 29 Jan 2025 18:45:46 +0100 Subject: [PATCH] docs: addressing pr comments --- .github/workflows/check-python.yaml | 3 ++- docs/markdown/capabilities/account.md | 4 ++-- docs/markdown/capabilities/algorand-client.md | 4 ++-- docs/markdown/capabilities/app-client.md | 2 +- docs/markdown/capabilities/app-deploy.md | 4 ++-- docs/markdown/capabilities/transaction-composer.md | 4 ++-- docs/source/capabilities/account.md | 4 ++-- docs/source/capabilities/algorand-client.md | 4 ++-- docs/source/capabilities/app-client.md | 2 +- docs/source/capabilities/app-deploy.md | 4 ++-- docs/source/capabilities/transaction-composer.md | 4 ++-- 11 files changed, 20 insertions(+), 19 deletions(-) diff --git a/.github/workflows/check-python.yaml b/.github/workflows/check-python.yaml index 0a473b53..58e3f358 100644 --- a/.github/workflows/check-python.yaml +++ b/.github/workflows/check-python.yaml @@ -48,4 +48,5 @@ jobs: - name: Check docs are up to date run: | poetry run poe docs-md-only - git diff --exit-code ':!docs/markdown/autoapi/index.md' docs + git diff --exit-code ':!docs/markdown/autoapi/index.md' ':!docs/markdown/autoapi/algokit_utils/applications/app_factory/index.md' docs + # TODO: Add back checks against html repo before prod release diff --git a/docs/markdown/capabilities/account.md b/docs/markdown/capabilities/account.md index a08b215b..cfbc2c71 100644 --- a/docs/markdown/capabilities/account.md +++ b/docs/markdown/capabilities/account.md @@ -188,7 +188,7 @@ default_dispenser_account = kmd_account_manager.get_wallet_account( lambda a: a["status"] != "Offline" and a["amount"] > 1_000_000_000 ) # Same as above, but dedicated method call for convenience -local_net_dispenser_account = kmd_account_manager.get_localnet_dispenser_account() +localnet_dispenser_account = kmd_account_manager.get_localnet_dispenser_account() # Idempotently get (if exists) or create (if it doesn't exist yet) an account by name using KMD # if creating it then fund it with 2 ALGO from the default dispenser account new_account = kmd_account_manager.get_or_create_wallet_account( @@ -205,7 +205,7 @@ Some of this functionality is directly exposed from [`AccountManager`](), which ```python # Get and register LocalNet dispenser -local_net_dispenser = algorand.account.localnet_dispenser() +localnet_dispenser = algorand.account.localnet_dispenser() # Get and register a dispenser by environment variable, or if not set then LocalNet dispenser via KMD dispenser = algorand.account.dispenser_from_environment() # Get / create and register account from KMD idempotently by name diff --git a/docs/markdown/capabilities/algorand-client.md b/docs/markdown/capabilities/algorand-client.md index a94de631..9404653e 100644 --- a/docs/markdown/capabilities/algorand-client.md +++ b/docs/markdown/capabilities/algorand-client.md @@ -177,7 +177,7 @@ All transaction parameters share the following common base parameters: - Round validity management - `validity_window: int | None` - How many rounds the transaction should be valid for, if not specified then the registered default validity window will be used. - `first_valid_round: int | None` - Set the first round this transaction is valid. If left undefined, the value from algod will be used. We recommend you only set this when you intentionally want this to be some time in the future. - - `last_valid_round: bigint | None` - The last round this transaction is valid. It is recommended to use `validity_window` instead. + - `last_valid_round: int | None` - The last round this transaction is valid. It is recommended to use `validity_window` instead. Then on top of that the base type gets extended for the specific type of transaction you are issuing. These are all defined as part of [`TransactionComposer`](transaction-composer.md) and we recommend reading these docs, especially when leveraging either `populate_app_call_resources` or `cover_app_call_inner_transaction_fees`. @@ -185,7 +185,7 @@ Then on top of that the base type gets extended for the specific type of transac AlgorandClient caches network provided transaction values for you automatically to reduce network traffic. It has a set of default configurations that control this behaviour, but you have the ability to override and change the configuration of this behaviour: -- `algorand.set_default_validity_window(validity_window)` - Set the default validity window (number of rounds from the current known round that the transaction will be valid to be accepted for), having a smallish value for this is usually ideal to avoid transactions that are valid for a long future period and may be submitted even after you think it failed to submit if waiting for a particular number of rounds for the transaction to be successfully submitted. The validity window defaults to 10, except in [automated testing](testing.md) where it’s set to 1000 when targeting LocalNet. +- `algorand.set_default_validity_window(validity_window)` - Set the default validity window (number of rounds from the current known round that the transaction will be valid to be accepted for), having a smallish value for this is usually ideal to avoid transactions that are valid for a long future period and may be submitted even after you think it failed to submit if waiting for a particular number of rounds for the transaction to be successfully submitted. The validity window defaults to `10`, except localnet environments where it’s set to `1000`. - `algorand.set_suggested_params(suggested_params, until?)` - Set the suggested network parameters to use (optionally until the given time) - `algorand.set_suggested_params_timeout(timeout)` - Set the timeout that is used to cache the suggested network parameters (by default 3 seconds) - `algorand.get_suggested_params()` - Get the current suggested network parameters object, either the cached value, or if the cache has expired a fresh value diff --git a/docs/markdown/capabilities/app-client.md b/docs/markdown/capabilities/app-client.md index c69ce15b..5953e5d2 100644 --- a/docs/markdown/capabilities/app-client.md +++ b/docs/markdown/capabilities/app-client.md @@ -158,7 +158,7 @@ result, app_client = factory.send.create( ## Updating and deleting an app -Deploy method aside, the ability to make update and delete calls happens after there is an instance of an app so are done via `AppClient`. The semantics of this are no different than other calls, with the caveat that the update call is a bit different since the code will be compiled when constructing the update params and the update calls thus optionally takes compilation parameters (`compilation_params`) for deploy-time parameter replacements and deploy-time immutability and permanence control. +Deploy method aside, the ability to make update and delete calls happens after there is an instance of an app created via `AppClient`. The semantics of this are no different than other calls, with the caveat that the update call is a bit different since the code will be compiled when constructing the update params and the update calls thus optionally takes compilation parameters (`compilation_params`) for deploy-time parameter replacements and deploy-time immutability and permanence control. ## Calling the app diff --git a/docs/markdown/capabilities/app-deploy.md b/docs/markdown/capabilities/app-deploy.md index 1db5a88c..ff7cb202 100644 --- a/docs/markdown/capabilities/app-deploy.md +++ b/docs/markdown/capabilities/app-deploy.md @@ -33,7 +33,7 @@ The App deployment capability provided by AlgoKit Utils helps implement **#2 Dep Furthermore, the implementation contains the following implementation characteristics per the original architecture design: - Deploy-time parameters can be provided and substituted into a TEAL Template by convention (by replacing `TMPL_{KEY}`) -- Contracts can be built by any smart contract framework that supports [ARC-56](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0056.md), [ARC-32](https://github.com/algorandfoundation/ARCs/pull/150) and [ARC-4](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0004.md) ([Beaker](https://beaker.algo.xyz/) or otherwise), which also means the deployment language can be different to the development language e.g. you can deploy a Python smart contract with TypeScript for instance +- Contracts can be built by any smart contract framework that supports [ARC-56](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0056.md) and [ARC-32](https://github.com/algorandfoundation/ARCs/pull/150), which also means the deployment language can be different to the development language e.g. you can deploy a Python smart contract with TypeScript for instance - There is explicit control of the immutability (updatability / upgradeability) and permanence (deletability) of the smart contract, which can be varied per environment to allow for easier development and testing in non-MainNet environments (by replacing `TMPL_UPDATABLE` and `TMPL_DELETABLE` at deploy-time by convention, if present) - Contracts are resolvable by a string “name” for a given creator to allow automated determination of whether that contract had been deployed previously or not, but can also be resolved by ID instead @@ -175,7 +175,7 @@ When compiling TEAL template code, the capabilities described in the [above desi In order for a smart contract to opt-in to use this functionality, it must have a TEAL Template that contains the following: -- `TMPL_{key}` - Which can be replaced with a number or a string / byte array which wil be automatically hexadecimal encoded (for any number of `{key}` => `{value}` pairs) +- `TMPL_{key}` - Which can be replaced with a number or a string / byte array which will be automatically hexadecimal encoded (for any number of `{key}` => `{value}` pairs) - `TMPL_UPDATABLE` - Which will be replaced with a `1` if an app should be updatable and `0` if it shouldn’t (immutable) - `TMPL_DELETABLE` - Which will be replaced with a `1` if an app should be deletable and `0` if it shouldn’t (permanent) diff --git a/docs/markdown/capabilities/transaction-composer.md b/docs/markdown/capabilities/transaction-composer.md index c859f81f..330b757b 100644 --- a/docs/markdown/capabilities/transaction-composer.md +++ b/docs/markdown/capabilities/transaction-composer.md @@ -191,7 +191,7 @@ result = ( args=[1, 2, 3] # Resources will be automatically populated! )) - .send(send_params=SendParams(populate_app_call_resources=True)) + .send(params=SendParams(populate_app_call_resources=True)) ) # Or disable automatic population @@ -208,7 +208,7 @@ result = ( asset_references=[789], box_references=[box_reference] )) - .send(send_params=SendParams(populate_app_call_resources=False)) + .send(params=SendParams(populate_app_call_resources=False)) ) ``` diff --git a/docs/source/capabilities/account.md b/docs/source/capabilities/account.md index 8db435d9..25d87437 100644 --- a/docs/source/capabilities/account.md +++ b/docs/source/capabilities/account.md @@ -188,7 +188,7 @@ default_dispenser_account = kmd_account_manager.get_wallet_account( lambda a: a["status"] != "Offline" and a["amount"] > 1_000_000_000 ) # Same as above, but dedicated method call for convenience -local_net_dispenser_account = kmd_account_manager.get_localnet_dispenser_account() +localnet_dispenser_account = kmd_account_manager.get_localnet_dispenser_account() # Idempotently get (if exists) or create (if it doesn't exist yet) an account by name using KMD # if creating it then fund it with 2 ALGO from the default dispenser account new_account = kmd_account_manager.get_or_create_wallet_account( @@ -205,7 +205,7 @@ Some of this functionality is directly exposed from [`AccountManager`](#accountm ```python # Get and register LocalNet dispenser -local_net_dispenser = algorand.account.localnet_dispenser() +localnet_dispenser = algorand.account.localnet_dispenser() # Get and register a dispenser by environment variable, or if not set then LocalNet dispenser via KMD dispenser = algorand.account.dispenser_from_environment() # Get / create and register account from KMD idempotently by name diff --git a/docs/source/capabilities/algorand-client.md b/docs/source/capabilities/algorand-client.md index 3cf93ee4..9ed7638c 100644 --- a/docs/source/capabilities/algorand-client.md +++ b/docs/source/capabilities/algorand-client.md @@ -177,7 +177,7 @@ All transaction parameters share the following common base parameters: - Round validity management - `validity_window: int | None` - How many rounds the transaction should be valid for, if not specified then the registered default validity window will be used. - `first_valid_round: int | None` - Set the first round this transaction is valid. If left undefined, the value from algod will be used. We recommend you only set this when you intentionally want this to be some time in the future. - - `last_valid_round: bigint | None` - The last round this transaction is valid. It is recommended to use `validity_window` instead. + - `last_valid_round: int | None` - The last round this transaction is valid. It is recommended to use `validity_window` instead. Then on top of that the base type gets extended for the specific type of transaction you are issuing. These are all defined as part of [`TransactionComposer`](./transaction-composer.md) and we recommend reading these docs, especially when leveraging either `populate_app_call_resources` or `cover_app_call_inner_transaction_fees`. @@ -185,7 +185,7 @@ Then on top of that the base type gets extended for the specific type of transac AlgorandClient caches network provided transaction values for you automatically to reduce network traffic. It has a set of default configurations that control this behaviour, but you have the ability to override and change the configuration of this behaviour: -- `algorand.set_default_validity_window(validity_window)` - Set the default validity window (number of rounds from the current known round that the transaction will be valid to be accepted for), having a smallish value for this is usually ideal to avoid transactions that are valid for a long future period and may be submitted even after you think it failed to submit if waiting for a particular number of rounds for the transaction to be successfully submitted. The validity window defaults to 10, except in [automated testing](./testing.md) where it's set to 1000 when targeting LocalNet. +- `algorand.set_default_validity_window(validity_window)` - Set the default validity window (number of rounds from the current known round that the transaction will be valid to be accepted for), having a smallish value for this is usually ideal to avoid transactions that are valid for a long future period and may be submitted even after you think it failed to submit if waiting for a particular number of rounds for the transaction to be successfully submitted. The validity window defaults to `10`, except localnet environments where it's set to `1000`. - `algorand.set_suggested_params(suggested_params, until?)` - Set the suggested network parameters to use (optionally until the given time) - `algorand.set_suggested_params_timeout(timeout)` - Set the timeout that is used to cache the suggested network parameters (by default 3 seconds) - `algorand.get_suggested_params()` - Get the current suggested network parameters object, either the cached value, or if the cache has expired a fresh value diff --git a/docs/source/capabilities/app-client.md b/docs/source/capabilities/app-client.md index fa202f7e..71357a46 100644 --- a/docs/source/capabilities/app-client.md +++ b/docs/source/capabilities/app-client.md @@ -158,7 +158,7 @@ result, app_client = factory.send.create( ## Updating and deleting an app -Deploy method aside, the ability to make update and delete calls happens after there is an instance of an app so are done via `AppClient`. The semantics of this are no different than other calls, with the caveat that the update call is a bit different since the code will be compiled when constructing the update params and the update calls thus optionally takes compilation parameters (`compilation_params`) for deploy-time parameter replacements and deploy-time immutability and permanence control. +Deploy method aside, the ability to make update and delete calls happens after there is an instance of an app created via `AppClient`. The semantics of this are no different than other calls, with the caveat that the update call is a bit different since the code will be compiled when constructing the update params and the update calls thus optionally takes compilation parameters (`compilation_params`) for deploy-time parameter replacements and deploy-time immutability and permanence control. ## Calling the app diff --git a/docs/source/capabilities/app-deploy.md b/docs/source/capabilities/app-deploy.md index 1028f32c..82fc97f4 100644 --- a/docs/source/capabilities/app-deploy.md +++ b/docs/source/capabilities/app-deploy.md @@ -33,7 +33,7 @@ The App deployment capability provided by AlgoKit Utils helps implement **#2 Dep Furthermore, the implementation contains the following implementation characteristics per the original architecture design: - Deploy-time parameters can be provided and substituted into a TEAL Template by convention (by replacing `TMPL_{KEY}`) -- Contracts can be built by any smart contract framework that supports [ARC-56](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0056.md), [ARC-32](https://github.com/algorandfoundation/ARCs/pull/150) and [ARC-4](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0004.md) ([Beaker](https://beaker.algo.xyz/) or otherwise), which also means the deployment language can be different to the development language e.g. you can deploy a Python smart contract with TypeScript for instance +- Contracts can be built by any smart contract framework that supports [ARC-56](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0056.md) and [ARC-32](https://github.com/algorandfoundation/ARCs/pull/150), which also means the deployment language can be different to the development language e.g. you can deploy a Python smart contract with TypeScript for instance - There is explicit control of the immutability (updatability / upgradeability) and permanence (deletability) of the smart contract, which can be varied per environment to allow for easier development and testing in non-MainNet environments (by replacing `TMPL_UPDATABLE` and `TMPL_DELETABLE` at deploy-time by convention, if present) - Contracts are resolvable by a string "name" for a given creator to allow automated determination of whether that contract had been deployed previously or not, but can also be resolved by ID instead @@ -175,7 +175,7 @@ When compiling TEAL template code, the capabilities described in the [above desi In order for a smart contract to opt-in to use this functionality, it must have a TEAL Template that contains the following: -- `TMPL_{key}` - Which can be replaced with a number or a string / byte array which wil be automatically hexadecimal encoded (for any number of `{key}` => `{value}` pairs) +- `TMPL_{key}` - Which can be replaced with a number or a string / byte array which will be automatically hexadecimal encoded (for any number of `{key}` => `{value}` pairs) - `TMPL_UPDATABLE` - Which will be replaced with a `1` if an app should be updatable and `0` if it shouldn't (immutable) - `TMPL_DELETABLE` - Which will be replaced with a `1` if an app should be deletable and `0` if it shouldn't (permanent) diff --git a/docs/source/capabilities/transaction-composer.md b/docs/source/capabilities/transaction-composer.md index baba7dd3..f3c5df0e 100644 --- a/docs/source/capabilities/transaction-composer.md +++ b/docs/source/capabilities/transaction-composer.md @@ -191,7 +191,7 @@ result = ( args=[1, 2, 3] # Resources will be automatically populated! )) - .send(send_params=SendParams(populate_app_call_resources=True)) + .send(params=SendParams(populate_app_call_resources=True)) ) # Or disable automatic population @@ -208,7 +208,7 @@ result = ( asset_references=[789], box_references=[box_reference] )) - .send(send_params=SendParams(populate_app_call_resources=False)) + .send(params=SendParams(populate_app_call_resources=False)) ) ```