From f57b6e679f2a70632a68213918ede9ef2e9462a7 Mon Sep 17 00:00:00 2001 From: Altynbek Orumbayev Date: Fri, 23 Feb 2024 14:16:35 +0100 Subject: [PATCH] chore: minor polishing; adding code tours --- .../.algokit.toml | 2 +- ...ing-started-with-your-algokit-project.tour | 56 +++++++++++++++++++ .../.vscode/extensions.json | 1 + .../.algokit.toml | 2 +- ...ing-started-with-your-algokit-project.tour | 56 +++++++++++++++++++ .../.vscode/extensions.json | 1 + .../.algokit.toml | 2 +- ...ing-started-with-your-algokit-project.tour | 56 +++++++++++++++++++ .../.vscode/extensions.json | 1 + .../.algokit.toml | 2 +- ...ing-started-with-your-algokit-project.tour | 56 +++++++++++++++++++ .../.vscode/extensions.json | 1 + examples/production_puya/.algokit.toml | 2 +- .../.github/workflows/checks.yaml | 6 ++ ...ing-started-with-your-algokit-project.tour | 56 +++++++++++++++++++ .../production_puya/.vscode/extensions.json | 1 + .../production_puya/.vscode/settings.json | 1 + examples/production_puya/README.md | 2 + examples/production_puya/pyproject.toml | 5 ++ examples/production_puya/tests/__init__.py | 0 examples/production_puya/tests/conftest.py | 32 +++++++++++ .../production_puya/tests/hello_world_test.py | 48 ++++++++++++++++ examples/starter_puya/.algokit.toml | 2 +- ...ing-started-with-your-algokit-project.tour | 56 +++++++++++++++++++ examples/starter_puya/.vscode/extensions.json | 1 + template_content/.algokit.toml.jinja | 2 +- ...arted-with-your-algokit-project.tour.jinja | 56 +++++++++++++++++++ .../extensions.json.jinja | 1 + tests/test_templates.py | 25 +-------- 29 files changed, 501 insertions(+), 31 deletions(-) create mode 100644 examples/generators/production_puya_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour create mode 100644 examples/generators/production_puya_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour create mode 100644 examples/generators/starter_puya_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour create mode 100644 examples/generators/starter_puya_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour create mode 100644 examples/production_puya/.tours/getting-started-with-your-algokit-project.tour create mode 100644 examples/production_puya/tests/__init__.py create mode 100644 examples/production_puya/tests/conftest.py create mode 100644 examples/production_puya/tests/hello_world_test.py create mode 100644 examples/starter_puya/.tours/getting-started-with-your-algokit-project.tour create mode 100644 template_content/{% if ide_vscode %}.tours{% endif %}/getting-started-with-your-algokit-project.tour.jinja diff --git a/examples/generators/production_puya_smart_contract_python/.algokit.toml b/examples/generators/production_puya_smart_contract_python/.algokit.toml index bbac8e4..40742c4 100644 --- a/examples/generators/production_puya_smart_contract_python/.algokit.toml +++ b/examples/generators/production_puya_smart_contract_python/.algokit.toml @@ -15,5 +15,5 @@ description = "Adds new smart contract to existing project" path = ".algokit/generators/create_contract" [project] -type = 'backend' +type = 'contract' name = 'production_puya_smart_contract_python' diff --git a/examples/generators/production_puya_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour b/examples/generators/production_puya_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour new file mode 100644 index 0000000..c1309a6 --- /dev/null +++ b/examples/generators/production_puya_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour @@ -0,0 +1,56 @@ +{ + "$schema": "https://aka.ms/codetour-schema", + "title": "Getting Started with Your AlgoKit Project", + "steps": [ + { + "file": "README.md", + "description": "Welcome to your brand new AlgoKit template-based project. In this tour, we will guide you through the main features and capabilities included in the template.", + "line": 3 + }, + { + "file": "README.md", + "description": "Start by ensuring you have followed the setup of pre-requisites.", + "line": 9 + }, + { + "file": "smart_contracts/__main__.py", + "description": "This is the main entry point for building your smart contracts. The default template includes a starter 'Hello World' contract that is deployed via the `algokit-utils` package (either `ts` or `py`, depending on your choice). To create a new smart contract, you can use the [`algokit generate`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md) command and invoke a pre-bundled generator template by running `algokit generate smart-contract`. This action will create a new folder in the `smart_contracts` directory, named after your project. Each folder contains a `contract.py` file, which is the entry point for your contract implementation, and `deploy_config.py` | `deployConfig.ts` files (depending on the language chosen for the template), that perform the deployment of the contract.", + "line": 26 + }, + { + "file": "smart_contracts/hello_world/deploy_config.py", + "description": "The default deployment scripts invoke a sample method on the starter contract that demonstrates how to interact with your deployed Algorand on-chain applications using the [`AlgoKit Typed Clients`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) feature.", + "line": 32 + }, + { + "file": "tests/hello_world_test.py", + "description": "If you opted to include unit tests, the default tests provided demonstrate an example of mocking, setting up fixtures, and testing smart contract calls on an AlgoKit typed client.", + "line": 36 + }, + { + "file": ".env.localnet.template", + "description": "Environment files are a crucial mechanism that allows you to set up the [`algokit deploy`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/deploy.md) feature to simplify deploying your contracts in CI/CD environments (please note we still recommend careful evaluation when it comes to deployment to MainNet). Clone the file and remove the `.template` suffix to apply the changes to deployment scripts and launch configurations. The network prefix `localnet|testnet|mainnet` is primarily optimized for `algokit deploy`. The order of loading the variables is `.env.{network}` < `.env`.", + "line": 2 + }, + { + "file": ".algokit.toml", + "description": "This is the configuration file used by AlgoKit to determine version requirements, `algokit deploy` settings, and references to custom generators.", + "line": 5 + }, + { + "file": ".vscode/launch.json", + "description": "Refer to the pre-bundled Visual Studio launch configurations, offering various options on how to execute the build and deployment of your smart contracts.", + "line": 5 + }, + { + "file": ".vscode/extensions.json", + "description": "We highly recommend installing the recommended extensions to get the most out of this template starter project in your VSCode IDE.", + "line": 3 + }, + { + "file": "smart_contracts/__main__.py", + "description": "Uncomment the following lines to enable complementary utilities that will generate artifacts required for the [AlgoKit AVM Debugger](https://github.com/algorandfoundation/algokit-avm-vscode-debugger) VSCode plugin available on the [VSCode Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger). A new folder will be automatically created in the `.algokit` directory with source maps of all TEAL contracts in this workspace, as well as traces that will appear in a folder at the root of the workspace. You can then use the traces as entry points to trigger the debug extension. Make sure to have the `.algokit.toml` file available at the root of the workspace.", + "line": 13 + } + ] +} diff --git a/examples/generators/production_puya_smart_contract_python/.vscode/extensions.json b/examples/generators/production_puya_smart_contract_python/.vscode/extensions.json index ee83617..1d2e7cf 100644 --- a/examples/generators/production_puya_smart_contract_python/.vscode/extensions.json +++ b/examples/generators/production_puya_smart_contract_python/.vscode/extensions.json @@ -6,6 +6,7 @@ "ms-python.black-formatter", "tamasfe.even-better-toml", "editorconfig.editorconfig", + "vsls-contrib.codetour", "algorandfoundation.algokit-avm-vscode-debugger" ] } diff --git a/examples/generators/production_puya_smart_contract_typescript/.algokit.toml b/examples/generators/production_puya_smart_contract_typescript/.algokit.toml index e01d957..736d491 100644 --- a/examples/generators/production_puya_smart_contract_typescript/.algokit.toml +++ b/examples/generators/production_puya_smart_contract_typescript/.algokit.toml @@ -15,5 +15,5 @@ description = "Adds new smart contract to existing project" path = ".algokit/generators/create_contract" [project] -type = 'backend' +type = 'contract' name = 'production_puya_smart_contract_typescript' diff --git a/examples/generators/production_puya_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour b/examples/generators/production_puya_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour new file mode 100644 index 0000000..30f150f --- /dev/null +++ b/examples/generators/production_puya_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour @@ -0,0 +1,56 @@ +{ + "$schema": "https://aka.ms/codetour-schema", + "title": "Getting Started with Your AlgoKit Project", + "steps": [ + { + "file": "README.md", + "description": "Welcome to your brand new AlgoKit template-based project. In this tour, we will guide you through the main features and capabilities included in the template.", + "line": 3 + }, + { + "file": "README.md", + "description": "Start by ensuring you have followed the setup of pre-requisites.", + "line": 9 + }, + { + "file": "smart_contracts/__main__.py", + "description": "This is the main entry point for building your smart contracts. The default template includes a starter 'Hello World' contract that is deployed via the `algokit-utils` package (either `ts` or `py`, depending on your choice). To create a new smart contract, you can use the [`algokit generate`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md) command and invoke a pre-bundled generator template by running `algokit generate smart-contract`. This action will create a new folder in the `smart_contracts` directory, named after your project. Each folder contains a `contract.py` file, which is the entry point for your contract implementation, and `deploy_config.py` | `deployConfig.ts` files (depending on the language chosen for the template), that perform the deployment of the contract.", + "line": 26 + }, + { + "file": "smart_contracts/hello_world/deploy-config.ts", + "description": "The default deployment scripts invoke a sample method on the starter contract that demonstrates how to interact with your deployed Algorand on-chain applications using the [`AlgoKit Typed Clients`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) feature.", + "line": 32 + }, + { + "file": "tests/hello-world.spec.ts", + "description": "If you opted to include unit tests, the default tests provided demonstrate an example of mocking, setting up fixtures, and testing smart contract calls on an AlgoKit typed client.", + "line": 39 + }, + { + "file": ".env.localnet.template", + "description": "Environment files are a crucial mechanism that allows you to set up the [`algokit deploy`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/deploy.md) feature to simplify deploying your contracts in CI/CD environments (please note we still recommend careful evaluation when it comes to deployment to MainNet). Clone the file and remove the `.template` suffix to apply the changes to deployment scripts and launch configurations. The network prefix `localnet|testnet|mainnet` is primarily optimized for `algokit deploy`. The order of loading the variables is `.env.{network}` < `.env`.", + "line": 2 + }, + { + "file": ".algokit.toml", + "description": "This is the configuration file used by AlgoKit to determine version requirements, `algokit deploy` settings, and references to custom generators.", + "line": 5 + }, + { + "file": ".vscode/launch.json", + "description": "Refer to the pre-bundled Visual Studio launch configurations, offering various options on how to execute the build and deployment of your smart contracts.", + "line": 5 + }, + { + "file": ".vscode/extensions.json", + "description": "We highly recommend installing the recommended extensions to get the most out of this template starter project in your VSCode IDE.", + "line": 3 + }, + { + "file": "smart_contracts/index.ts", + "description": "Uncomment the following lines to enable complementary utilities that will generate artifacts required for the [AlgoKit AVM Debugger](https://github.com/algorandfoundation/algokit-avm-vscode-debugger) VSCode plugin available on the [VSCode Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger). A new folder will be automatically created in the `.algokit` directory with source maps of all TEAL contracts in this workspace, as well as traces that will appear in a folder at the root of the workspace. You can then use the traces as entry points to trigger the debug extension. Make sure to have the `.algokit.toml` file available at the root of the workspace.", + "line": 13 + } + ] +} diff --git a/examples/generators/production_puya_smart_contract_typescript/.vscode/extensions.json b/examples/generators/production_puya_smart_contract_typescript/.vscode/extensions.json index 47b2649..684e4dd 100644 --- a/examples/generators/production_puya_smart_contract_typescript/.vscode/extensions.json +++ b/examples/generators/production_puya_smart_contract_typescript/.vscode/extensions.json @@ -7,6 +7,7 @@ "esbenp.prettier-vscode", "tamasfe.even-better-toml", "editorconfig.editorconfig", + "vsls-contrib.codetour", "algorandfoundation.algokit-avm-vscode-debugger" ] } diff --git a/examples/generators/starter_puya_smart_contract_python/.algokit.toml b/examples/generators/starter_puya_smart_contract_python/.algokit.toml index d96edee..cdcf495 100644 --- a/examples/generators/starter_puya_smart_contract_python/.algokit.toml +++ b/examples/generators/starter_puya_smart_contract_python/.algokit.toml @@ -15,5 +15,5 @@ description = "Adds new smart contract to existing project" path = ".algokit/generators/create_contract" [project] -type = 'backend' +type = 'contract' name = 'starter_puya_smart_contract_python' diff --git a/examples/generators/starter_puya_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour b/examples/generators/starter_puya_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour new file mode 100644 index 0000000..c1309a6 --- /dev/null +++ b/examples/generators/starter_puya_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour @@ -0,0 +1,56 @@ +{ + "$schema": "https://aka.ms/codetour-schema", + "title": "Getting Started with Your AlgoKit Project", + "steps": [ + { + "file": "README.md", + "description": "Welcome to your brand new AlgoKit template-based project. In this tour, we will guide you through the main features and capabilities included in the template.", + "line": 3 + }, + { + "file": "README.md", + "description": "Start by ensuring you have followed the setup of pre-requisites.", + "line": 9 + }, + { + "file": "smart_contracts/__main__.py", + "description": "This is the main entry point for building your smart contracts. The default template includes a starter 'Hello World' contract that is deployed via the `algokit-utils` package (either `ts` or `py`, depending on your choice). To create a new smart contract, you can use the [`algokit generate`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md) command and invoke a pre-bundled generator template by running `algokit generate smart-contract`. This action will create a new folder in the `smart_contracts` directory, named after your project. Each folder contains a `contract.py` file, which is the entry point for your contract implementation, and `deploy_config.py` | `deployConfig.ts` files (depending on the language chosen for the template), that perform the deployment of the contract.", + "line": 26 + }, + { + "file": "smart_contracts/hello_world/deploy_config.py", + "description": "The default deployment scripts invoke a sample method on the starter contract that demonstrates how to interact with your deployed Algorand on-chain applications using the [`AlgoKit Typed Clients`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) feature.", + "line": 32 + }, + { + "file": "tests/hello_world_test.py", + "description": "If you opted to include unit tests, the default tests provided demonstrate an example of mocking, setting up fixtures, and testing smart contract calls on an AlgoKit typed client.", + "line": 36 + }, + { + "file": ".env.localnet.template", + "description": "Environment files are a crucial mechanism that allows you to set up the [`algokit deploy`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/deploy.md) feature to simplify deploying your contracts in CI/CD environments (please note we still recommend careful evaluation when it comes to deployment to MainNet). Clone the file and remove the `.template` suffix to apply the changes to deployment scripts and launch configurations. The network prefix `localnet|testnet|mainnet` is primarily optimized for `algokit deploy`. The order of loading the variables is `.env.{network}` < `.env`.", + "line": 2 + }, + { + "file": ".algokit.toml", + "description": "This is the configuration file used by AlgoKit to determine version requirements, `algokit deploy` settings, and references to custom generators.", + "line": 5 + }, + { + "file": ".vscode/launch.json", + "description": "Refer to the pre-bundled Visual Studio launch configurations, offering various options on how to execute the build and deployment of your smart contracts.", + "line": 5 + }, + { + "file": ".vscode/extensions.json", + "description": "We highly recommend installing the recommended extensions to get the most out of this template starter project in your VSCode IDE.", + "line": 3 + }, + { + "file": "smart_contracts/__main__.py", + "description": "Uncomment the following lines to enable complementary utilities that will generate artifacts required for the [AlgoKit AVM Debugger](https://github.com/algorandfoundation/algokit-avm-vscode-debugger) VSCode plugin available on the [VSCode Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger). A new folder will be automatically created in the `.algokit` directory with source maps of all TEAL contracts in this workspace, as well as traces that will appear in a folder at the root of the workspace. You can then use the traces as entry points to trigger the debug extension. Make sure to have the `.algokit.toml` file available at the root of the workspace.", + "line": 13 + } + ] +} diff --git a/examples/generators/starter_puya_smart_contract_python/.vscode/extensions.json b/examples/generators/starter_puya_smart_contract_python/.vscode/extensions.json index ee83617..1d2e7cf 100644 --- a/examples/generators/starter_puya_smart_contract_python/.vscode/extensions.json +++ b/examples/generators/starter_puya_smart_contract_python/.vscode/extensions.json @@ -6,6 +6,7 @@ "ms-python.black-formatter", "tamasfe.even-better-toml", "editorconfig.editorconfig", + "vsls-contrib.codetour", "algorandfoundation.algokit-avm-vscode-debugger" ] } diff --git a/examples/generators/starter_puya_smart_contract_typescript/.algokit.toml b/examples/generators/starter_puya_smart_contract_typescript/.algokit.toml index e46fb3e..9ef71d2 100644 --- a/examples/generators/starter_puya_smart_contract_typescript/.algokit.toml +++ b/examples/generators/starter_puya_smart_contract_typescript/.algokit.toml @@ -15,5 +15,5 @@ description = "Adds new smart contract to existing project" path = ".algokit/generators/create_contract" [project] -type = 'backend' +type = 'contract' name = 'starter_puya_smart_contract_typescript' diff --git a/examples/generators/starter_puya_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour b/examples/generators/starter_puya_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour new file mode 100644 index 0000000..30f150f --- /dev/null +++ b/examples/generators/starter_puya_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour @@ -0,0 +1,56 @@ +{ + "$schema": "https://aka.ms/codetour-schema", + "title": "Getting Started with Your AlgoKit Project", + "steps": [ + { + "file": "README.md", + "description": "Welcome to your brand new AlgoKit template-based project. In this tour, we will guide you through the main features and capabilities included in the template.", + "line": 3 + }, + { + "file": "README.md", + "description": "Start by ensuring you have followed the setup of pre-requisites.", + "line": 9 + }, + { + "file": "smart_contracts/__main__.py", + "description": "This is the main entry point for building your smart contracts. The default template includes a starter 'Hello World' contract that is deployed via the `algokit-utils` package (either `ts` or `py`, depending on your choice). To create a new smart contract, you can use the [`algokit generate`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md) command and invoke a pre-bundled generator template by running `algokit generate smart-contract`. This action will create a new folder in the `smart_contracts` directory, named after your project. Each folder contains a `contract.py` file, which is the entry point for your contract implementation, and `deploy_config.py` | `deployConfig.ts` files (depending on the language chosen for the template), that perform the deployment of the contract.", + "line": 26 + }, + { + "file": "smart_contracts/hello_world/deploy-config.ts", + "description": "The default deployment scripts invoke a sample method on the starter contract that demonstrates how to interact with your deployed Algorand on-chain applications using the [`AlgoKit Typed Clients`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) feature.", + "line": 32 + }, + { + "file": "tests/hello-world.spec.ts", + "description": "If you opted to include unit tests, the default tests provided demonstrate an example of mocking, setting up fixtures, and testing smart contract calls on an AlgoKit typed client.", + "line": 39 + }, + { + "file": ".env.localnet.template", + "description": "Environment files are a crucial mechanism that allows you to set up the [`algokit deploy`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/deploy.md) feature to simplify deploying your contracts in CI/CD environments (please note we still recommend careful evaluation when it comes to deployment to MainNet). Clone the file and remove the `.template` suffix to apply the changes to deployment scripts and launch configurations. The network prefix `localnet|testnet|mainnet` is primarily optimized for `algokit deploy`. The order of loading the variables is `.env.{network}` < `.env`.", + "line": 2 + }, + { + "file": ".algokit.toml", + "description": "This is the configuration file used by AlgoKit to determine version requirements, `algokit deploy` settings, and references to custom generators.", + "line": 5 + }, + { + "file": ".vscode/launch.json", + "description": "Refer to the pre-bundled Visual Studio launch configurations, offering various options on how to execute the build and deployment of your smart contracts.", + "line": 5 + }, + { + "file": ".vscode/extensions.json", + "description": "We highly recommend installing the recommended extensions to get the most out of this template starter project in your VSCode IDE.", + "line": 3 + }, + { + "file": "smart_contracts/index.ts", + "description": "Uncomment the following lines to enable complementary utilities that will generate artifacts required for the [AlgoKit AVM Debugger](https://github.com/algorandfoundation/algokit-avm-vscode-debugger) VSCode plugin available on the [VSCode Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger). A new folder will be automatically created in the `.algokit` directory with source maps of all TEAL contracts in this workspace, as well as traces that will appear in a folder at the root of the workspace. You can then use the traces as entry points to trigger the debug extension. Make sure to have the `.algokit.toml` file available at the root of the workspace.", + "line": 13 + } + ] +} diff --git a/examples/generators/starter_puya_smart_contract_typescript/.vscode/extensions.json b/examples/generators/starter_puya_smart_contract_typescript/.vscode/extensions.json index 47b2649..684e4dd 100644 --- a/examples/generators/starter_puya_smart_contract_typescript/.vscode/extensions.json +++ b/examples/generators/starter_puya_smart_contract_typescript/.vscode/extensions.json @@ -7,6 +7,7 @@ "esbenp.prettier-vscode", "tamasfe.even-better-toml", "editorconfig.editorconfig", + "vsls-contrib.codetour", "algorandfoundation.algokit-avm-vscode-debugger" ] } diff --git a/examples/production_puya/.algokit.toml b/examples/production_puya/.algokit.toml index b693068..3965d2d 100644 --- a/examples/production_puya/.algokit.toml +++ b/examples/production_puya/.algokit.toml @@ -15,5 +15,5 @@ description = "Adds new smart contract to existing project" path = ".algokit/generators/create_contract" [project] -type = 'backend' +type = 'contract' name = 'production_puya' diff --git a/examples/production_puya/.github/workflows/checks.yaml b/examples/production_puya/.github/workflows/checks.yaml index 6d01651..d5550b5 100644 --- a/examples/production_puya/.github/workflows/checks.yaml +++ b/examples/production_puya/.github/workflows/checks.yaml @@ -58,6 +58,12 @@ jobs: - name: Check types with mypy run: poetry run mypy + - name: Run tests + shell: bash + run: | + set -o pipefail + poetry run pytest --junitxml=pytest-junit.xml + - name: Build smart contracts run: poetry run python -m smart_contracts build diff --git a/examples/production_puya/.tours/getting-started-with-your-algokit-project.tour b/examples/production_puya/.tours/getting-started-with-your-algokit-project.tour new file mode 100644 index 0000000..c1309a6 --- /dev/null +++ b/examples/production_puya/.tours/getting-started-with-your-algokit-project.tour @@ -0,0 +1,56 @@ +{ + "$schema": "https://aka.ms/codetour-schema", + "title": "Getting Started with Your AlgoKit Project", + "steps": [ + { + "file": "README.md", + "description": "Welcome to your brand new AlgoKit template-based project. In this tour, we will guide you through the main features and capabilities included in the template.", + "line": 3 + }, + { + "file": "README.md", + "description": "Start by ensuring you have followed the setup of pre-requisites.", + "line": 9 + }, + { + "file": "smart_contracts/__main__.py", + "description": "This is the main entry point for building your smart contracts. The default template includes a starter 'Hello World' contract that is deployed via the `algokit-utils` package (either `ts` or `py`, depending on your choice). To create a new smart contract, you can use the [`algokit generate`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md) command and invoke a pre-bundled generator template by running `algokit generate smart-contract`. This action will create a new folder in the `smart_contracts` directory, named after your project. Each folder contains a `contract.py` file, which is the entry point for your contract implementation, and `deploy_config.py` | `deployConfig.ts` files (depending on the language chosen for the template), that perform the deployment of the contract.", + "line": 26 + }, + { + "file": "smart_contracts/hello_world/deploy_config.py", + "description": "The default deployment scripts invoke a sample method on the starter contract that demonstrates how to interact with your deployed Algorand on-chain applications using the [`AlgoKit Typed Clients`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) feature.", + "line": 32 + }, + { + "file": "tests/hello_world_test.py", + "description": "If you opted to include unit tests, the default tests provided demonstrate an example of mocking, setting up fixtures, and testing smart contract calls on an AlgoKit typed client.", + "line": 36 + }, + { + "file": ".env.localnet.template", + "description": "Environment files are a crucial mechanism that allows you to set up the [`algokit deploy`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/deploy.md) feature to simplify deploying your contracts in CI/CD environments (please note we still recommend careful evaluation when it comes to deployment to MainNet). Clone the file and remove the `.template` suffix to apply the changes to deployment scripts and launch configurations. The network prefix `localnet|testnet|mainnet` is primarily optimized for `algokit deploy`. The order of loading the variables is `.env.{network}` < `.env`.", + "line": 2 + }, + { + "file": ".algokit.toml", + "description": "This is the configuration file used by AlgoKit to determine version requirements, `algokit deploy` settings, and references to custom generators.", + "line": 5 + }, + { + "file": ".vscode/launch.json", + "description": "Refer to the pre-bundled Visual Studio launch configurations, offering various options on how to execute the build and deployment of your smart contracts.", + "line": 5 + }, + { + "file": ".vscode/extensions.json", + "description": "We highly recommend installing the recommended extensions to get the most out of this template starter project in your VSCode IDE.", + "line": 3 + }, + { + "file": "smart_contracts/__main__.py", + "description": "Uncomment the following lines to enable complementary utilities that will generate artifacts required for the [AlgoKit AVM Debugger](https://github.com/algorandfoundation/algokit-avm-vscode-debugger) VSCode plugin available on the [VSCode Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger). A new folder will be automatically created in the `.algokit` directory with source maps of all TEAL contracts in this workspace, as well as traces that will appear in a folder at the root of the workspace. You can then use the traces as entry points to trigger the debug extension. Make sure to have the `.algokit.toml` file available at the root of the workspace.", + "line": 13 + } + ] +} diff --git a/examples/production_puya/.vscode/extensions.json b/examples/production_puya/.vscode/extensions.json index ee83617..1d2e7cf 100644 --- a/examples/production_puya/.vscode/extensions.json +++ b/examples/production_puya/.vscode/extensions.json @@ -6,6 +6,7 @@ "ms-python.black-formatter", "tamasfe.even-better-toml", "editorconfig.editorconfig", + "vsls-contrib.codetour", "algorandfoundation.algokit-avm-vscode-debugger" ] } diff --git a/examples/production_puya/.vscode/settings.json b/examples/production_puya/.vscode/settings.json index a7b97d0..0c2dfec 100644 --- a/examples/production_puya/.vscode/settings.json +++ b/examples/production_puya/.vscode/settings.json @@ -24,6 +24,7 @@ "editor.defaultFormatter": "ms-python.black-formatter", }, "black-formatter.args": ["--config=pyproject.toml"], + "python.testing.pytestEnabled": true, "ruff.enable": true, "ruff.lint.run": "onSave", "ruff.lint.args": ["--config=pyproject.toml"], diff --git a/examples/production_puya/README.md b/examples/production_puya/README.md index b6eb24e..30f1681 100644 --- a/examples/production_puya/README.md +++ b/examples/production_puya/README.md @@ -84,6 +84,7 @@ For pull requests and pushes to `main` branch against this repository the follow - Code formatting is checked using [Black](https://github.com/psf/black) - Linting is checked using [Ruff](https://github.com/charliermarsh/ruff) - Types are checked using [mypy](https://mypy-lang.org/) + - Python tests are executed using [pytest](https://docs.pytest.org/) - Smart contract artifacts are built - Smart contract artifacts are checked for [output stability](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/articles/output_stability.md) - Smart contract is deployed to a AlgoKit LocalNet instance @@ -107,6 +108,7 @@ This project makes use of Python to build Algorand smart contracts. The followin - [Poetry](https://python-poetry.org/): Python packaging and dependency management.- [Black](https://github.com/psf/black): A Python code formatter.- [Ruff](https://github.com/charliermarsh/ruff): An extremely fast Python linter. - [mypy](https://mypy-lang.org/): Static type checker. +- [pytest](https://docs.pytest.org/): Automated testing. - [pip-audit](https://pypi.org/project/pip-audit/): Tool for scanning Python environments for packages with known vulnerabilities. - [pre-commit](https://pre-commit.com/): A framework for managing and maintaining multi-language pre-commit hooks, to enable pre-commit you need to run `pre-commit install` in the root of the repository. This will install the pre-commit hooks and run them against modified files when committing. If any of the hooks fail, the commit will be aborted. To run the hooks on all files, use `pre-commit run --all-files`. It has also been configured to have a productive dev experience out of the box in [VS Code](https://code.visualstudio.com/), see the [.vscode](./.vscode) folder. diff --git a/examples/production_puya/pyproject.toml b/examples/production_puya/pyproject.toml index bfccdff..5242a69 100644 --- a/examples/production_puya/pyproject.toml +++ b/examples/production_puya/pyproject.toml @@ -15,6 +15,8 @@ puya = "^0" black = {extras = ["d"], version = "*"} ruff = "^0.1.6" mypy = "*" +pytest = "*" +pytest-cov = "*" pip-audit = "*" pre-commit = "*" @@ -35,6 +37,9 @@ unfixable = ["B", "RUF"] allow-star-arg-any = true suppress-none-returning = true +[tool.pytest.ini_options] +pythonpath = ["smart_contracts", "tests"] + [tool.mypy] files = "smart_contracts/" python_version = "3.12" diff --git a/examples/production_puya/tests/__init__.py b/examples/production_puya/tests/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/examples/production_puya/tests/conftest.py b/examples/production_puya/tests/conftest.py new file mode 100644 index 0000000..b0622e7 --- /dev/null +++ b/examples/production_puya/tests/conftest.py @@ -0,0 +1,32 @@ +from pathlib import Path + +import pytest +from algokit_utils import ( + get_algod_client, + get_indexer_client, + is_localnet, +) +from algosdk.v2client.algod import AlgodClient +from algosdk.v2client.indexer import IndexerClient +from dotenv import load_dotenv + + +@pytest.fixture(autouse=True, scope="session") +def environment_fixture() -> None: + env_path = Path(__file__).parent.parent / ".env.localnet" + load_dotenv(env_path) + + +@pytest.fixture(scope="session") +def algod_client() -> AlgodClient: + client = get_algod_client() + + # you can remove this assertion to test on other networks, + # included here to prevent accidentally running against other networks + assert is_localnet(client) + return client + + +@pytest.fixture(scope="session") +def indexer_client() -> IndexerClient: + return get_indexer_client() diff --git a/examples/production_puya/tests/hello_world_test.py b/examples/production_puya/tests/hello_world_test.py new file mode 100644 index 0000000..bb13a43 --- /dev/null +++ b/examples/production_puya/tests/hello_world_test.py @@ -0,0 +1,48 @@ +import algokit_utils +import pytest +from algokit_utils import get_localnet_default_account +from algokit_utils.config import config +from algosdk.v2client.algod import AlgodClient +from algosdk.v2client.indexer import IndexerClient + +from smart_contracts.artifacts.hello_world.client import HelloWorldClient + + +@pytest.fixture(scope="session") +def hello_world_client( + algod_client: AlgodClient, indexer_client: IndexerClient +) -> HelloWorldClient: + config.configure( + debug=True, + # trace_all=True, + ) + + client = HelloWorldClient( + algod_client, + creator=get_localnet_default_account(algod_client), + indexer_client=indexer_client, + ) + + client.deploy( + on_schema_break=algokit_utils.OnSchemaBreak.AppendApp, + on_update=algokit_utils.OnUpdate.AppendApp, + ) + return client + + +def test_says_hello(hello_world_client: HelloWorldClient) -> None: + result = hello_world_client.hello(name="World") + + assert result.return_value == "Hello, World" + + +def test_simulate_says_hello_with_correct_budget_consumed( + hello_world_client: HelloWorldClient, algod_client: AlgodClient +) -> None: + result = ( + hello_world_client.compose().hello(name="World").hello(name="Jane").simulate() + ) + + assert result.abi_results[0].return_value == "Hello, World" + assert result.abi_results[1].return_value == "Hello, Jane" + assert result.simulate_response["txn-groups"][0]["app-budget-consumed"] < 100 diff --git a/examples/starter_puya/.algokit.toml b/examples/starter_puya/.algokit.toml index 3d33ebb..2cbed35 100644 --- a/examples/starter_puya/.algokit.toml +++ b/examples/starter_puya/.algokit.toml @@ -15,5 +15,5 @@ description = "Adds new smart contract to existing project" path = ".algokit/generators/create_contract" [project] -type = 'backend' +type = 'contract' name = 'starter_puya' diff --git a/examples/starter_puya/.tours/getting-started-with-your-algokit-project.tour b/examples/starter_puya/.tours/getting-started-with-your-algokit-project.tour new file mode 100644 index 0000000..c1309a6 --- /dev/null +++ b/examples/starter_puya/.tours/getting-started-with-your-algokit-project.tour @@ -0,0 +1,56 @@ +{ + "$schema": "https://aka.ms/codetour-schema", + "title": "Getting Started with Your AlgoKit Project", + "steps": [ + { + "file": "README.md", + "description": "Welcome to your brand new AlgoKit template-based project. In this tour, we will guide you through the main features and capabilities included in the template.", + "line": 3 + }, + { + "file": "README.md", + "description": "Start by ensuring you have followed the setup of pre-requisites.", + "line": 9 + }, + { + "file": "smart_contracts/__main__.py", + "description": "This is the main entry point for building your smart contracts. The default template includes a starter 'Hello World' contract that is deployed via the `algokit-utils` package (either `ts` or `py`, depending on your choice). To create a new smart contract, you can use the [`algokit generate`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md) command and invoke a pre-bundled generator template by running `algokit generate smart-contract`. This action will create a new folder in the `smart_contracts` directory, named after your project. Each folder contains a `contract.py` file, which is the entry point for your contract implementation, and `deploy_config.py` | `deployConfig.ts` files (depending on the language chosen for the template), that perform the deployment of the contract.", + "line": 26 + }, + { + "file": "smart_contracts/hello_world/deploy_config.py", + "description": "The default deployment scripts invoke a sample method on the starter contract that demonstrates how to interact with your deployed Algorand on-chain applications using the [`AlgoKit Typed Clients`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) feature.", + "line": 32 + }, + { + "file": "tests/hello_world_test.py", + "description": "If you opted to include unit tests, the default tests provided demonstrate an example of mocking, setting up fixtures, and testing smart contract calls on an AlgoKit typed client.", + "line": 36 + }, + { + "file": ".env.localnet.template", + "description": "Environment files are a crucial mechanism that allows you to set up the [`algokit deploy`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/deploy.md) feature to simplify deploying your contracts in CI/CD environments (please note we still recommend careful evaluation when it comes to deployment to MainNet). Clone the file and remove the `.template` suffix to apply the changes to deployment scripts and launch configurations. The network prefix `localnet|testnet|mainnet` is primarily optimized for `algokit deploy`. The order of loading the variables is `.env.{network}` < `.env`.", + "line": 2 + }, + { + "file": ".algokit.toml", + "description": "This is the configuration file used by AlgoKit to determine version requirements, `algokit deploy` settings, and references to custom generators.", + "line": 5 + }, + { + "file": ".vscode/launch.json", + "description": "Refer to the pre-bundled Visual Studio launch configurations, offering various options on how to execute the build and deployment of your smart contracts.", + "line": 5 + }, + { + "file": ".vscode/extensions.json", + "description": "We highly recommend installing the recommended extensions to get the most out of this template starter project in your VSCode IDE.", + "line": 3 + }, + { + "file": "smart_contracts/__main__.py", + "description": "Uncomment the following lines to enable complementary utilities that will generate artifacts required for the [AlgoKit AVM Debugger](https://github.com/algorandfoundation/algokit-avm-vscode-debugger) VSCode plugin available on the [VSCode Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger). A new folder will be automatically created in the `.algokit` directory with source maps of all TEAL contracts in this workspace, as well as traces that will appear in a folder at the root of the workspace. You can then use the traces as entry points to trigger the debug extension. Make sure to have the `.algokit.toml` file available at the root of the workspace.", + "line": 13 + } + ] +} diff --git a/examples/starter_puya/.vscode/extensions.json b/examples/starter_puya/.vscode/extensions.json index ee83617..1d2e7cf 100644 --- a/examples/starter_puya/.vscode/extensions.json +++ b/examples/starter_puya/.vscode/extensions.json @@ -6,6 +6,7 @@ "ms-python.black-formatter", "tamasfe.even-better-toml", "editorconfig.editorconfig", + "vsls-contrib.codetour", "algorandfoundation.algokit-avm-vscode-debugger" ] } diff --git a/template_content/.algokit.toml.jinja b/template_content/.algokit.toml.jinja index bd1942e..8f41d0f 100644 --- a/template_content/.algokit.toml.jinja +++ b/template_content/.algokit.toml.jinja @@ -22,5 +22,5 @@ description = "Adds new smart contract to existing project" path = ".algokit/generators/create_contract" [project] -type = 'backend' +type = 'contract' name = '{{ project_name }}' diff --git a/template_content/{% if ide_vscode %}.tours{% endif %}/getting-started-with-your-algokit-project.tour.jinja b/template_content/{% if ide_vscode %}.tours{% endif %}/getting-started-with-your-algokit-project.tour.jinja new file mode 100644 index 0000000..ca507d4 --- /dev/null +++ b/template_content/{% if ide_vscode %}.tours{% endif %}/getting-started-with-your-algokit-project.tour.jinja @@ -0,0 +1,56 @@ +{ + "$schema": "https://aka.ms/codetour-schema", + "title": "Getting Started with Your AlgoKit Project", + "steps": [ + { + "file": "README.md", + "description": "Welcome to your brand new AlgoKit template-based project. In this tour, we will guide you through the main features and capabilities included in the template.", + "line": 3 + }, + { + "file": "README.md", + "description": "Start by ensuring you have followed the setup of pre-requisites.", + "line": 9 + }, + { + "file": "smart_contracts/__main__.py", + "description": "This is the main entry point for building your smart contracts. The default template includes a starter 'Hello World' contract that is deployed via the `algokit-utils` package (either `ts` or `py`, depending on your choice). To create a new smart contract, you can use the [`algokit generate`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md) command and invoke a pre-bundled generator template by running `algokit generate smart-contract`. This action will create a new folder in the `smart_contracts` directory, named after your project. Each folder contains a `contract.py` file, which is the entry point for your contract implementation, and `deploy_config.py` | `deployConfig.ts` files (depending on the language chosen for the template), that perform the deployment of the contract.", + "line": 26 + }, + { + "file": "smart_contracts/hello_world/{% if deployment_language == 'typescript' %}deploy-config.ts{% else %}deploy_config.py{% endif %}", + "description": "The default deployment scripts invoke a sample method on the starter contract that demonstrates how to interact with your deployed Algorand on-chain applications using the [`AlgoKit Typed Clients`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) feature.", + "line": 32 + }, + { + "file": "tests/{% if deployment_language == 'typescript' %}{% include pathjoin('includes', 'contract_name_kebab.jinja') %}.spec.ts{% else %}{{ contract_name }}_test.py{% endif %}", + "description": "If you opted to include unit tests, the default tests provided demonstrate an example of mocking, setting up fixtures, and testing smart contract calls on an AlgoKit typed client.", + "line": {% if deployment_language == 'typescript' %}39{% else %}36{% endif %} + }, + { + "file": ".env.localnet.template", + "description": "Environment files are a crucial mechanism that allows you to set up the [`algokit deploy`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/deploy.md) feature to simplify deploying your contracts in CI/CD environments (please note we still recommend careful evaluation when it comes to deployment to MainNet). Clone the file and remove the `.template` suffix to apply the changes to deployment scripts and launch configurations. The network prefix `localnet|testnet|mainnet` is primarily optimized for `algokit deploy`. The order of loading the variables is `.env.{network}` < `.env`.", + "line": 2 + }, + { + "file": ".algokit.toml", + "description": "This is the configuration file used by AlgoKit to determine version requirements, `algokit deploy` settings, and references to custom generators.", + "line": 5 + }, + { + "file": ".vscode/launch.json", + "description": "Refer to the pre-bundled Visual Studio launch configurations, offering various options on how to execute the build and deployment of your smart contracts.", + "line": 5 + }, + { + "file": ".vscode/extensions.json", + "description": "We highly recommend installing the recommended extensions to get the most out of this template starter project in your VSCode IDE.", + "line": 3 + }, + { + "file": "smart_contracts/{% if deployment_language == 'python' %}__main__.py{% else %}index.ts{% endif %}", + "description": "Uncomment the following lines to enable complementary utilities that will generate artifacts required for the [AlgoKit AVM Debugger](https://github.com/algorandfoundation/algokit-avm-vscode-debugger) VSCode plugin available on the [VSCode Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger). A new folder will be automatically created in the `.algokit` directory with source maps of all TEAL contracts in this workspace, as well as traces that will appear in a folder at the root of the workspace. You can then use the traces as entry points to trigger the debug extension. Make sure to have the `.algokit.toml` file available at the root of the workspace.", + "line": 13 + } + ] +} diff --git a/template_content/{% if ide_vscode %}.vscode{% endif %}/extensions.json.jinja b/template_content/{% if ide_vscode %}.vscode{% endif %}/extensions.json.jinja index 8a8c996..06d3c69 100644 --- a/template_content/{% if ide_vscode %}.vscode{% endif %}/extensions.json.jinja +++ b/template_content/{% if ide_vscode %}.vscode{% endif %}/extensions.json.jinja @@ -17,6 +17,7 @@ {% endif -%} "tamasfe.even-better-toml", "editorconfig.editorconfig", + "vsls-contrib.codetour", "algorandfoundation.algokit-avm-vscode-debugger" ] } diff --git a/tests/test_templates.py b/tests/test_templates.py index 5375a2c..f4e7d3d 100644 --- a/tests/test_templates.py +++ b/tests/test_templates.py @@ -92,6 +92,7 @@ def run_init( "--no-workspace", ] answers = {**DEFAULT_PARAMETERS, **(answers or {})} + answers["deployment_language"] = "python" for question, answer in answers.items(): init_args.extend(["-a", question, answer]) @@ -164,32 +165,8 @@ def get_questions_from_copier_yaml( allowed_questions: list[str] | None = None, ) -> Iterator[tuple[str, str | bool]]: copier_yaml = root / "copier.yaml" - ignored_keys = { - "_subdirectory", # copier setting - # the following are ignored as they are passed automatically by algokit - "project_name", - "algod_token", - "algod_server", - "algod_port", - "indexer_token", - "indexer_server", - "indexer_port", - "use_python_pip_audit", - "use_dispenser", - "use_pre_commit", - "python_linter", - "use_python_black", - "use_python_mypy", - "use_python_pytest", - "use_github_actions", - "ide_vscode", - } - ignored_keys.update(DEFAULT_PARAMETERS) - questions = _load_copier_yaml(copier_yaml) for question_name, details in questions.items(): - if question_name in ignored_keys: - continue if allowed_questions and question_name not in allowed_questions: continue if isinstance(details, dict):