diff --git a/.github/workflows/check-python.yaml b/.github/workflows/check-python.yaml index 1f7982f..cc493db 100644 --- a/.github/workflows/check-python.yaml +++ b/.github/workflows/check-python.yaml @@ -48,7 +48,7 @@ jobs: shell: bash run: | set -o pipefail - poetry run pytest --junitxml=pytest-junit.xml -n auto + poetry run pytest --junitxml=pytest-junit.xml - name: Check generated templates have been reviewed shell: bash diff --git a/.gitignore b/.gitignore index b0da2ea..2679426 100644 --- a/.gitignore +++ b/.gitignore @@ -175,7 +175,7 @@ examples/**/package-lock.json examples/**/poetry.lock # playground folder for previewing templates -.playground/* +playground # Misc examples/**/smart_contracts/artifacts diff --git a/.vscode/clear.ps1 b/.vscode/clear.ps1 index cff941d..4a7abea 100644 --- a/.vscode/clear.ps1 +++ b/.vscode/clear.ps1 @@ -1 +1 @@ -Remove-Item -Recurse -Force .playground -ErrorAction Ignore +Remove-Item -Recurse -Force playground -ErrorAction Ignore diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 45c8a64..b4a674e 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -8,7 +8,7 @@ "-v", "init", "--name", - ".playground", + "playground", "--no-git", "--defaults", "--UNSAFE-SECURITY-accept-template-url", @@ -23,7 +23,7 @@ "kind": "build", "isDefault": true }, - "dependsOn": ["Cleanup .playground folder"], + "dependsOn": ["Cleanup playground folder"], "problemMatcher": [] }, { @@ -33,7 +33,7 @@ "-v", "init", "--name", - ".playground", + "playground", "--no-git", "--defaults", "--UNSAFE-SECURITY-accept-template-url", @@ -51,7 +51,7 @@ "kind": "build", "isDefault": true }, - "dependsOn": ["Cleanup .playground folder"], + "dependsOn": ["Cleanup playground folder"], "problemMatcher": [] }, { @@ -61,7 +61,7 @@ "-v", "init", "--name", - ".playground", + "playground", "--no-git", "--UNSAFE-SECURITY-accept-template-url", "--template-url", @@ -71,13 +71,13 @@ "--no-bootstrap" ], "type": "shell", - "dependsOn": ["Cleanup .playground folder"], + "dependsOn": ["Cleanup playground folder"], "problemMatcher": [] }, { - "label": "Cleanup .playground folder", + "label": "Cleanup playground folder", "command": "rm", - "args": ["-rf", ".playground"], + "args": ["-rf", "playground"], "type": "shell", "windows": { "command": "./.vscode/clear.ps1" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e5bbfae..08890d8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ This repository is a template for creating new AlgoKit projects. It includes a b Ensure localnet is running by executing `algokit localnet reset`. ```bash -poetry run pytest -n auto +poetry run pytest ``` This will regenerate the tests for default `starter` and `production` presets as well as default tests for `generators` available on the template. @@ -22,10 +22,10 @@ This will regenerate the tests for default `starter` and `production` presets as ### Manual ```bash -poetry run copier copy . .playground --vcs-ref=HEAD --trust +poetry run copier copy . playground --vcs-ref=HEAD --trust ``` -To generate a dummy project into the `.playground` folder. This is useful for testing the template to quickly preview the output of the template before testing via `pytest`. +To generate a dummy project into the `playground` folder. This is useful for testing the template to quickly preview the output of the template before testing via `pytest`. ### Using VSCode Tasks @@ -33,9 +33,9 @@ In VSCode IDE, you can find the tasks in the `.vscode/tasks.json` file. To run t 1. Open the command palette (`Cmd+Shift+P` on macOS, `Ctrl+Shift+P` on Windows/Linux) and type `> Run Task` 2. Select the task you want to run -3. It will be generated for you under the .playground folder +3. It will be generated for you under the playground folder -To cleanup the .playground folder run dedicated cleanup task. +To cleanup the playground folder run dedicated cleanup task. ## Contributing diff --git a/examples/generators/production_python_smart_contract_python/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 b/examples/generators/production_python_smart_contract_python/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 index 9828347..0fb0bc7 100644 --- a/examples/generators/production_python_smart_contract_python/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 +++ b/examples/generators/production_python_smart_contract_python/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 @@ -1,3 +1,4 @@ +# pyright: reportMissingModuleSource=false from algopy import ARC4Contract, arc4 diff --git a/examples/generators/production_python_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour b/examples/generators/production_python_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour index 6b593eb..2c210ee 100644 --- a/examples/generators/production_python_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour +++ b/examples/generators/production_python_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour @@ -13,13 +13,13 @@ "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": ".algokit.toml", + "description": "This is the main configuration file used by algokit-cli to manage the project. 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` (see how it is defined in the `.algokit.toml`, you can create your own generators if needed). 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. Additionally you can define custom commands to run (similar to `npm` scripts), see definitions under `[project]` section in `.algokit.toml`.", + "line": 1 }, { "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.", + "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. The invocation if deploy is aliased in `.algokit.toml` file, allowing simple deployments via `algokit project deploy` command.", "line": 32 }, { @@ -32,14 +32,9 @@ "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.", + "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. Alternatively execute `algokit project run` to see list of available custom commands.", "line": 5 }, { diff --git a/examples/generators/production_python_smart_contract_python/README.md b/examples/generators/production_python_smart_contract_python/README.md index 0e37a0e..aded005 100644 --- a/examples/generators/production_python_smart_contract_python/README.md +++ b/examples/generators/production_python_smart_contract_python/README.md @@ -9,19 +9,25 @@ This project has been generated using AlgoKit. See below for default getting sta - [Python 3.12](https://www.python.org/downloads/) or later - [Docker](https://www.docker.com/) (only required for LocalNet) +> For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension. + ### Initial setup 1. Clone this repository locally 2. Install pre-requisites: - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine. - - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is `1.7.3`. Ensure you can execute `algokit --version` and get `1.7.1` or later. + - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later. - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will: - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+ - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies - Copy `.env.template` to `.env` - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. + - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`). 3. Open the project and start debugging / developing via: - - VS Code + - Terminal + 1. Run `algokit project run build` to build all contracts in the project + 2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network. + - VS Code (Launch Configurations) 1. Open the repository root in VS Code 2. Install recommended extensions 3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging. @@ -34,10 +40,6 @@ This project has been generated using AlgoKit. See below for default getting sta 1. Open the repository root in the IDE 2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment. 3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task). - - Other - 1. Open the repository root in your text editor of choice - 2. In a terminal run `poetry shell` - 3. Run `python -m smart_contracts` through your debugger of choice ### Subsequently @@ -50,6 +52,10 @@ This project uses [GitHub Actions](https://docs.github.com/en/actions/learn-gith > Please note, if you instantiated the project with --workspace flag in `algokit init` it will automatically attempt to move the contents of the `.github` folder to the root of the workspace. +### AlgoKit Workspaces + +To define custom `algokit project run` commands refer to [documentation](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md). This allows orchestration of commands spanning across multiple projects within an algokit workspace based project (monorepo). + ### Debugging Smart Contracts This project is optimized to work with AlgoKit AVM Debugger extension. To activate it: @@ -109,6 +115,6 @@ This project makes use of Algorand Python to build Algorand smart contracts. The - [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`. +- [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/generators/production_python_smart_contract_python/smart_contracts/__main__.py b/examples/generators/production_python_smart_contract_python/smart_contracts/__main__.py index aa936c9..7fab7c9 100644 --- a/examples/generators/production_python_smart_contract_python/smart_contracts/__main__.py +++ b/examples/generators/production_python_smart_contract_python/smart_contracts/__main__.py @@ -20,6 +20,7 @@ logger = logging.getLogger(__name__) logger.info("Loading .env") load_dotenv() +load_dotenv(".env.localnet") root_path = Path(__file__).parent diff --git a/examples/generators/production_python_smart_contract_python/smart_contracts/cool_contract/contract.py b/examples/generators/production_python_smart_contract_python/smart_contracts/cool_contract/contract.py index 4c00d34..d4aca2c 100644 --- a/examples/generators/production_python_smart_contract_python/smart_contracts/cool_contract/contract.py +++ b/examples/generators/production_python_smart_contract_python/smart_contracts/cool_contract/contract.py @@ -1,3 +1,4 @@ +# pyright: reportMissingModuleSource=false from algopy import ARC4Contract, arc4 diff --git a/examples/generators/production_python_smart_contract_typescript/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 b/examples/generators/production_python_smart_contract_typescript/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 index 9828347..0fb0bc7 100644 --- a/examples/generators/production_python_smart_contract_typescript/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 +++ b/examples/generators/production_python_smart_contract_typescript/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 @@ -1,3 +1,4 @@ +# pyright: reportMissingModuleSource=false from algopy import ARC4Contract, arc4 diff --git a/examples/generators/production_python_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour b/examples/generators/production_python_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour index bd27ad2..c166a39 100644 --- a/examples/generators/production_python_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour +++ b/examples/generators/production_python_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour @@ -13,33 +13,23 @@ "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": ".algokit.toml", + "description": "This is the main configuration file used by algokit-cli to manage the project. 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` (see how it is defined in the `.algokit.toml`, you can create your own generators if needed). 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. Additionally you can define custom commands to run (similar to `npm` scripts), see definitions under `[project]` section in `.algokit.toml`.", + "line": 1 }, { "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.", + "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. The invocation if deploy is aliased in `.algokit.toml` file, allowing simple deployments via `algokit project deploy` command.", "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.", + "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. Alternatively execute `algokit project run` to see list of available custom commands.", "line": 5 }, { diff --git a/examples/generators/production_python_smart_contract_typescript/README.md b/examples/generators/production_python_smart_contract_typescript/README.md index e79f831..99afa2e 100644 --- a/examples/generators/production_python_smart_contract_typescript/README.md +++ b/examples/generators/production_python_smart_contract_typescript/README.md @@ -9,20 +9,25 @@ This project has been generated using AlgoKit. See below for default getting sta - [Python 3.12](https://www.python.org/downloads/) or later - [Docker](https://www.docker.com/) (only required for LocalNet) +> For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension. + ### Initial setup 1. Clone this repository locally 2. Install pre-requisites: - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine. - - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is `1.7.3`. Ensure you can execute `algokit --version` and get `1.7.1` or later. + - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later. - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will: - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+ - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies - Copy `.env.template` to `.env` - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. - - Run `npm install` to install NPM packages + - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`). 3. Open the project and start debugging / developing via: - - VS Code + - Terminal + 1. Run `algokit project run build` to build all contracts in the project + 2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network. + - VS Code (Launch Configurations) 1. Open the repository root in VS Code 2. Install recommended extensions 3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging. @@ -35,10 +40,6 @@ This project has been generated using AlgoKit. See below for default getting sta 1. Open the repository root in the IDE 2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment. 3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task). - - Other - 1. Open the repository root in your text editor of choice - 2. In a terminal run `poetry shell` - 3. Run `python -m smart_contracts` through your debugger of choice ### Subsequently @@ -51,6 +52,10 @@ This project uses [GitHub Actions](https://docs.github.com/en/actions/learn-gith > Please note, if you instantiated the project with --workspace flag in `algokit init` it will automatically attempt to move the contents of the `.github` folder to the root of the workspace. +### AlgoKit Workspaces + +To define custom `algokit project run` commands refer to [documentation](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md). This allows orchestration of commands spanning across multiple projects within an algokit workspace based project (monorepo). + ### Debugging Smart Contracts This project is optimized to work with AlgoKit AVM Debugger extension. To activate it: @@ -108,7 +113,7 @@ This project makes use of Algorand Python to build Algorand smart contracts. The - [mypy](https://mypy-lang.org/): Static type checker. - [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`. +- [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`. - [npm](https://www.npmjs.com/): Node.js package manager - [TypeScript](https://www.typescriptlang.org/): Strongly typed programming language that builds on JavaScript - [ts-node-dev](https://github.com/wclr/ts-node-dev): TypeScript development execution environment diff --git a/examples/generators/production_python_smart_contract_typescript/smart_contracts/__main__.py b/examples/generators/production_python_smart_contract_typescript/smart_contracts/__main__.py index b91ab2e..b20300a 100644 --- a/examples/generators/production_python_smart_contract_typescript/smart_contracts/__main__.py +++ b/examples/generators/production_python_smart_contract_typescript/smart_contracts/__main__.py @@ -13,6 +13,7 @@ logger = logging.getLogger(__name__) logger.info("Loading .env") load_dotenv() +load_dotenv(".env.localnet") root_path = Path(__file__).parent diff --git a/examples/generators/production_python_smart_contract_typescript/smart_contracts/cool_contract/contract.py b/examples/generators/production_python_smart_contract_typescript/smart_contracts/cool_contract/contract.py index 4c00d34..d4aca2c 100644 --- a/examples/generators/production_python_smart_contract_typescript/smart_contracts/cool_contract/contract.py +++ b/examples/generators/production_python_smart_contract_typescript/smart_contracts/cool_contract/contract.py @@ -1,3 +1,4 @@ +# pyright: reportMissingModuleSource=false from algopy import ARC4Contract, arc4 diff --git a/examples/generators/starter_python_smart_contract_python/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 b/examples/generators/starter_python_smart_contract_python/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 index 9828347..0fb0bc7 100644 --- a/examples/generators/starter_python_smart_contract_python/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 +++ b/examples/generators/starter_python_smart_contract_python/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 @@ -1,3 +1,4 @@ +# pyright: reportMissingModuleSource=false from algopy import ARC4Contract, arc4 diff --git a/examples/generators/starter_python_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour b/examples/generators/starter_python_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour index 6b593eb..445db2a 100644 --- a/examples/generators/starter_python_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour +++ b/examples/generators/starter_python_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour @@ -13,33 +13,23 @@ "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": ".algokit.toml", + "description": "This is the main configuration file used by algokit-cli to manage the project. 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` (see how it is defined in the `.algokit.toml`, you can create your own generators if needed). 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. Additionally you can define custom commands to run (similar to `npm` scripts), see definitions under `[project]` section in `.algokit.toml`.", + "line": 1 }, { "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.", + "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. The invocation if deploy is aliased in `.algokit.toml` file, allowing simple deployments via `algokit project deploy` command.", "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.", + "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. Alternatively execute `algokit project run` to see list of available custom commands.", "line": 5 }, { diff --git a/examples/generators/starter_python_smart_contract_python/README.md b/examples/generators/starter_python_smart_contract_python/README.md index 8ea368c..d923b04 100644 --- a/examples/generators/starter_python_smart_contract_python/README.md +++ b/examples/generators/starter_python_smart_contract_python/README.md @@ -9,19 +9,25 @@ This project has been generated using AlgoKit. See below for default getting sta - [Python 3.12](https://www.python.org/downloads/) or later - [Docker](https://www.docker.com/) (only required for LocalNet) +> For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension. + ### Initial setup 1. Clone this repository locally 2. Install pre-requisites: - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine. - - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is `1.7.3`. Ensure you can execute `algokit --version` and get `1.7.1` or later. + - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later. - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will: - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+ - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies - Copy `.env.template` to `.env` - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. + - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`). 3. Open the project and start debugging / developing via: - - VS Code + - Terminal + 1. Run `algokit project run build` to build all contracts in the project + 2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network. + - VS Code (Launch Configurations) 1. Open the repository root in VS Code 2. Install recommended extensions 3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging. @@ -34,10 +40,6 @@ This project has been generated using AlgoKit. See below for default getting sta 1. Open the repository root in the IDE 2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment. 3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task). - - Other - 1. Open the repository root in your text editor of choice - 2. In a terminal run `poetry shell` - 3. Run `python -m smart_contracts` through your debugger of choice ### Subsequently diff --git a/examples/generators/starter_python_smart_contract_python/smart_contracts/__main__.py b/examples/generators/starter_python_smart_contract_python/smart_contracts/__main__.py index aa936c9..7fab7c9 100644 --- a/examples/generators/starter_python_smart_contract_python/smart_contracts/__main__.py +++ b/examples/generators/starter_python_smart_contract_python/smart_contracts/__main__.py @@ -20,6 +20,7 @@ logger = logging.getLogger(__name__) logger.info("Loading .env") load_dotenv() +load_dotenv(".env.localnet") root_path = Path(__file__).parent diff --git a/examples/generators/starter_python_smart_contract_python/smart_contracts/cool_contract/contract.py b/examples/generators/starter_python_smart_contract_python/smart_contracts/cool_contract/contract.py index 4c00d34..d4aca2c 100644 --- a/examples/generators/starter_python_smart_contract_python/smart_contracts/cool_contract/contract.py +++ b/examples/generators/starter_python_smart_contract_python/smart_contracts/cool_contract/contract.py @@ -1,3 +1,4 @@ +# pyright: reportMissingModuleSource=false from algopy import ARC4Contract, arc4 diff --git a/examples/generators/starter_python_smart_contract_typescript/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 b/examples/generators/starter_python_smart_contract_typescript/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 index 9828347..0fb0bc7 100644 --- a/examples/generators/starter_python_smart_contract_typescript/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 +++ b/examples/generators/starter_python_smart_contract_typescript/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2 @@ -1,3 +1,4 @@ +# pyright: reportMissingModuleSource=false from algopy import ARC4Contract, arc4 diff --git a/examples/generators/starter_python_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour b/examples/generators/starter_python_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour index bd27ad2..c166a39 100644 --- a/examples/generators/starter_python_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour +++ b/examples/generators/starter_python_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour @@ -13,33 +13,23 @@ "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": ".algokit.toml", + "description": "This is the main configuration file used by algokit-cli to manage the project. 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` (see how it is defined in the `.algokit.toml`, you can create your own generators if needed). 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. Additionally you can define custom commands to run (similar to `npm` scripts), see definitions under `[project]` section in `.algokit.toml`.", + "line": 1 }, { "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.", + "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. The invocation if deploy is aliased in `.algokit.toml` file, allowing simple deployments via `algokit project deploy` command.", "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.", + "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. Alternatively execute `algokit project run` to see list of available custom commands.", "line": 5 }, { diff --git a/examples/generators/starter_python_smart_contract_typescript/README.md b/examples/generators/starter_python_smart_contract_typescript/README.md index 1107a2d..013fed3 100644 --- a/examples/generators/starter_python_smart_contract_typescript/README.md +++ b/examples/generators/starter_python_smart_contract_typescript/README.md @@ -9,20 +9,25 @@ This project has been generated using AlgoKit. See below for default getting sta - [Python 3.12](https://www.python.org/downloads/) or later - [Docker](https://www.docker.com/) (only required for LocalNet) +> For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension. + ### Initial setup 1. Clone this repository locally 2. Install pre-requisites: - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine. - - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is `1.7.3`. Ensure you can execute `algokit --version` and get `1.7.1` or later. + - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later. - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will: - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+ - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies - Copy `.env.template` to `.env` - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. - - Run `npm install` to install NPM packages + - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`). 3. Open the project and start debugging / developing via: - - VS Code + - Terminal + 1. Run `algokit project run build` to build all contracts in the project + 2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network. + - VS Code (Launch Configurations) 1. Open the repository root in VS Code 2. Install recommended extensions 3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging. @@ -35,10 +40,6 @@ This project has been generated using AlgoKit. See below for default getting sta 1. Open the repository root in the IDE 2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment. 3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task). - - Other - 1. Open the repository root in your text editor of choice - 2. In a terminal run `poetry shell` - 3. Run `python -m smart_contracts` through your debugger of choice ### Subsequently diff --git a/examples/generators/starter_python_smart_contract_typescript/smart_contracts/__main__.py b/examples/generators/starter_python_smart_contract_typescript/smart_contracts/__main__.py index b91ab2e..b20300a 100644 --- a/examples/generators/starter_python_smart_contract_typescript/smart_contracts/__main__.py +++ b/examples/generators/starter_python_smart_contract_typescript/smart_contracts/__main__.py @@ -13,6 +13,7 @@ logger = logging.getLogger(__name__) logger.info("Loading .env") load_dotenv() +load_dotenv(".env.localnet") root_path = Path(__file__).parent diff --git a/examples/generators/starter_python_smart_contract_typescript/smart_contracts/cool_contract/contract.py b/examples/generators/starter_python_smart_contract_typescript/smart_contracts/cool_contract/contract.py index 4c00d34..d4aca2c 100644 --- a/examples/generators/starter_python_smart_contract_typescript/smart_contracts/cool_contract/contract.py +++ b/examples/generators/starter_python_smart_contract_typescript/smart_contracts/cool_contract/contract.py @@ -1,3 +1,4 @@ +# pyright: reportMissingModuleSource=false from algopy import ARC4Contract, arc4 diff --git a/examples/production_python/.tours/getting-started-with-your-algokit-project.tour b/examples/production_python/.tours/getting-started-with-your-algokit-project.tour index 6b593eb..2c210ee 100644 --- a/examples/production_python/.tours/getting-started-with-your-algokit-project.tour +++ b/examples/production_python/.tours/getting-started-with-your-algokit-project.tour @@ -13,13 +13,13 @@ "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": ".algokit.toml", + "description": "This is the main configuration file used by algokit-cli to manage the project. 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` (see how it is defined in the `.algokit.toml`, you can create your own generators if needed). 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. Additionally you can define custom commands to run (similar to `npm` scripts), see definitions under `[project]` section in `.algokit.toml`.", + "line": 1 }, { "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.", + "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. The invocation if deploy is aliased in `.algokit.toml` file, allowing simple deployments via `algokit project deploy` command.", "line": 32 }, { @@ -32,14 +32,9 @@ "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.", + "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. Alternatively execute `algokit project run` to see list of available custom commands.", "line": 5 }, { diff --git a/examples/production_python/README.md b/examples/production_python/README.md index ab58bdc..4ab1c42 100644 --- a/examples/production_python/README.md +++ b/examples/production_python/README.md @@ -9,19 +9,25 @@ This project has been generated using AlgoKit. See below for default getting sta - [Python 3.12](https://www.python.org/downloads/) or later - [Docker](https://www.docker.com/) (only required for LocalNet) +> For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension. + ### Initial setup 1. Clone this repository locally 2. Install pre-requisites: - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine. - - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is `1.7.3`. Ensure you can execute `algokit --version` and get `1.7.1` or later. + - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later. - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will: - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+ - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies - Copy `.env.template` to `.env` - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. + - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`). 3. Open the project and start debugging / developing via: - - VS Code + - Terminal + 1. Run `algokit project run build` to build all contracts in the project + 2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network. + - VS Code (Launch Configurations) 1. Open the repository root in VS Code 2. Install recommended extensions 3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging. @@ -34,10 +40,6 @@ This project has been generated using AlgoKit. See below for default getting sta 1. Open the repository root in the IDE 2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment. 3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task). - - Other - 1. Open the repository root in your text editor of choice - 2. In a terminal run `poetry shell` - 3. Run `python -m smart_contracts` through your debugger of choice ### Subsequently @@ -50,6 +52,10 @@ This project uses [GitHub Actions](https://docs.github.com/en/actions/learn-gith > Please note, if you instantiated the project with --workspace flag in `algokit init` it will automatically attempt to move the contents of the `.github` folder to the root of the workspace. +### AlgoKit Workspaces + +To define custom `algokit project run` commands refer to [documentation](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md). This allows orchestration of commands spanning across multiple projects within an algokit workspace based project (monorepo). + ### Debugging Smart Contracts This project is optimized to work with AlgoKit AVM Debugger extension. To activate it: @@ -109,6 +115,6 @@ This project makes use of Algorand Python to build Algorand smart contracts. The - [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`. +- [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_python/smart_contracts/__main__.py b/examples/production_python/smart_contracts/__main__.py index aa936c9..7fab7c9 100644 --- a/examples/production_python/smart_contracts/__main__.py +++ b/examples/production_python/smart_contracts/__main__.py @@ -20,6 +20,7 @@ logger = logging.getLogger(__name__) logger.info("Loading .env") load_dotenv() +load_dotenv(".env.localnet") root_path = Path(__file__).parent diff --git a/examples/starter_python/.tours/getting-started-with-your-algokit-project.tour b/examples/starter_python/.tours/getting-started-with-your-algokit-project.tour index 6b593eb..445db2a 100644 --- a/examples/starter_python/.tours/getting-started-with-your-algokit-project.tour +++ b/examples/starter_python/.tours/getting-started-with-your-algokit-project.tour @@ -13,33 +13,23 @@ "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": ".algokit.toml", + "description": "This is the main configuration file used by algokit-cli to manage the project. 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` (see how it is defined in the `.algokit.toml`, you can create your own generators if needed). 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. Additionally you can define custom commands to run (similar to `npm` scripts), see definitions under `[project]` section in `.algokit.toml`.", + "line": 1 }, { "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.", + "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. The invocation if deploy is aliased in `.algokit.toml` file, allowing simple deployments via `algokit project deploy` command.", "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.", + "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. Alternatively execute `algokit project run` to see list of available custom commands.", "line": 5 }, { diff --git a/examples/starter_python/README.md b/examples/starter_python/README.md index a98b9a1..0f96b72 100644 --- a/examples/starter_python/README.md +++ b/examples/starter_python/README.md @@ -9,19 +9,25 @@ This project has been generated using AlgoKit. See below for default getting sta - [Python 3.12](https://www.python.org/downloads/) or later - [Docker](https://www.docker.com/) (only required for LocalNet) +> For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension. + ### Initial setup 1. Clone this repository locally 2. Install pre-requisites: - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine. - - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is `1.7.3`. Ensure you can execute `algokit --version` and get `1.7.1` or later. + - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later. - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will: - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+ - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies - Copy `.env.template` to `.env` - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. + - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`). 3. Open the project and start debugging / developing via: - - VS Code + - Terminal + 1. Run `algokit project run build` to build all contracts in the project + 2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network. + - VS Code (Launch Configurations) 1. Open the repository root in VS Code 2. Install recommended extensions 3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging. @@ -34,10 +40,6 @@ This project has been generated using AlgoKit. See below for default getting sta 1. Open the repository root in the IDE 2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment. 3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task). - - Other - 1. Open the repository root in your text editor of choice - 2. In a terminal run `poetry shell` - 3. Run `python -m smart_contracts` through your debugger of choice ### Subsequently diff --git a/examples/starter_python/smart_contracts/__main__.py b/examples/starter_python/smart_contracts/__main__.py index aa936c9..7fab7c9 100644 --- a/examples/starter_python/smart_contracts/__main__.py +++ b/examples/starter_python/smart_contracts/__main__.py @@ -20,6 +20,7 @@ logger = logging.getLogger(__name__) logger.info("Loading .env") load_dotenv() +load_dotenv(".env.localnet") root_path = Path(__file__).parent diff --git a/template_content/.algokit/generators/create_contract/smart_contracts/{% raw %}{{ contract_name }}{% endraw %}/contract.py.j2 b/template_content/.algokit/generators/create_contract/smart_contracts/{% raw %}{{ contract_name }}{% endraw %}/contract.py.j2 index 9828347..0fb0bc7 100644 --- a/template_content/.algokit/generators/create_contract/smart_contracts/{% raw %}{{ contract_name }}{% endraw %}/contract.py.j2 +++ b/template_content/.algokit/generators/create_contract/smart_contracts/{% raw %}{{ contract_name }}{% endraw %}/contract.py.j2 @@ -1,3 +1,4 @@ +# pyright: reportMissingModuleSource=false from algopy import ARC4Contract, arc4 diff --git a/template_content/README.md.jinja b/template_content/README.md.jinja index 4666a3b..85b5365 100644 --- a/template_content/README.md.jinja +++ b/template_content/README.md.jinja @@ -9,22 +9,25 @@ This project has been generated using AlgoKit. See below for default getting sta - [Python 3.12](https://www.python.org/downloads/) or later - [Docker](https://www.docker.com/) (only required for LocalNet) +> For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension. + ### Initial setup 1. Clone this repository locally 2. Install pre-requisites: - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine. - - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is `1.7.3`. Ensure you can execute `algokit --version` and get `1.7.1` or later. + - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later. - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will: - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+ - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies - Copy `.env.template` to `.env` - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. -{%- if deployment_language == "typescript" %} - - Run `npm install` to install NPM packages -{%- endif %} + - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`). 3. Open the project and start debugging / developing via: - - VS Code + - Terminal + 1. Run `algokit project run build` to build all contracts in the project + 2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network. + - VS Code (Launch Configurations) 1. Open the repository root in VS Code 2. Install recommended extensions 3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging. @@ -37,10 +40,6 @@ This project has been generated using AlgoKit. See below for default getting sta 1. Open the repository root in the IDE 2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment. 3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task). - - Other - 1. Open the repository root in your text editor of choice - 2. In a terminal run `poetry shell` - 3. Run `python -m smart_contracts` through your debugger of choice ### Subsequently @@ -56,6 +55,10 @@ This project uses [GitHub Actions](https://docs.github.com/en/actions/learn-gith > Please note, if you instantiated the project with --workspace flag in `algokit init` it will automatically attempt to move the contents of the `.github` folder to the root of the workspace. +### AlgoKit Workspaces + +To define custom `algokit project run` commands refer to [documentation](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md). This allows orchestration of commands spanning across multiple projects within an algokit workspace based project (monorepo). + ### Debugging Smart Contracts This project is optimized to work with AlgoKit AVM Debugger extension. To activate it: @@ -153,7 +156,7 @@ This project makes use of Algorand Python to build Algorand smart contracts. The - [pip-audit](https://pypi.org/project/pip-audit/): Tool for scanning Python environments for packages with known vulnerabilities. {%- endif %} {%- if use_pre_commit %} - - [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`. +- [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`. {%- endif %} {%- if deployment_language == "typescript" %} - [npm](https://www.npmjs.com/): Node.js package manager diff --git a/template_content/smart_contracts/__main__.py.jinja b/template_content/smart_contracts/__main__.py.jinja index 26e6b8a..7ceb007 100644 --- a/template_content/smart_contracts/__main__.py.jinja +++ b/template_content/smart_contracts/__main__.py.jinja @@ -22,6 +22,7 @@ logging.basicConfig( logger = logging.getLogger(__name__) logger.info("Loading .env") load_dotenv() +load_dotenv(".env.localnet") root_path = Path(__file__).parent 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 index e582960..2ba5c47 100644 --- 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 @@ -13,33 +13,30 @@ "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": ".algokit.toml", + "description": "This is the main configuration file used by algokit-cli to manage the project. 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` (see how it is defined in the `.algokit.toml`, you can create your own generators if needed). 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. Additionally you can define custom commands to run (similar to `npm` scripts), see definitions under `[project]` section in `.algokit.toml`.", + "line": 1 }, { "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.", + "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. The invocation if deploy is aliased in `.algokit.toml` file, allowing simple deployments via `algokit project deploy` command.", "line": 32 }, + {%- if use_python_pytest %} { "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 %} }, + {%- 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.", + "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. Alternatively execute `algokit project run` to see list of available custom commands.", "line": 5 }, {