feat: add compile py command

src/algokit/cli/__init__.py

@@ -1,6 +1,7 @@
 import click
 
 from algokit.cli.bootstrap import bootstrap_group
+from algokit.cli.compile import compile_group
 from algokit.cli.completions import completions_group
 from algokit.cli.config import config_group
 from algokit.cli.deploy import deploy_command
@@ -49,3 +50,4 @@ def algokit(*, skip_version_check: bool) -> None:
 algokit.add_command(deploy_command)
 algokit.add_command(dispenser_group)
 algokit.add_command(task_group)
+algokit.add_command(compile_group)

src/algokit/cli/compile.py

@@ -0,0 +1,61 @@
+import logging
+
+import click
+
+from algokit.core.compile import find_valid_puyapy_command
+from algokit.core.proc import run
+
+logger = logging.getLogger(__name__)
+
+
+@click.group("compile", hidden=True)
+@click.option(
+    "-v",
+    "--version",
+    "version",
+    required=False,
+    default=None,
+    help=(
+        "Compiler version, for example, 1.0.0. "
+        "If the version isn't specified, AlgoKit will check if the compiler is installed locally, and execute that. "
+        "If the compiler is not found, it will install the latest version. "
+        "If the version is specified, AlgoKit will check if the local compiler's version satisfies, and execute that. "
+        "Otherwise, AlgoKit will install the specifed compiler version."
+    ),
+)
+@click.pass_context
+def compile_group(context: click.Context, version: str | None) -> None:
+    """Compile high level language smart contracts to TEAL"""
+    context.ensure_object(dict)
+    context.obj["version"] = version
+
+
+@compile_group.command(
+    "py",
+    short_help="Compile Python to TEAL with PuyaPy",
+    help="Compile Python to TEAL with PuyaPy, review https://github.com/algorandfoundation/puya for usage",
+    context_settings={
+        "ignore_unknown_options": True,
+    },
+    add_help_option=False,
+)
+@click.argument("puya_args", nargs=-1, type=click.UNPROCESSED)
+@click.pass_context
+def compile_py_command(context: click.Context, puya_args: list[str]) -> None:
+    """
+    Compile Python contract(s) to TEAL with PuyaPy
+    """
+    version = str(context.obj["version"]) if context.obj["version"] else None
+
+    puya_command = find_valid_puyapy_command(version)
+
+    run_result = run(
+        [
+            *puya_command,
+            *puya_args,
+        ],
+    )
+    click.echo(run_result.output)
+
+    if run_result.exit_code != 0:
+        raise click.exceptions.Exit(run_result.exit_code)

src/algokit/core/compile.py

@@ -0,0 +1,80 @@
+from collections.abc import Iterator
+
+from algokit.core.proc import run
+from algokit.core.utils import extract_version_triple, find_valid_pipx_command
+
+
+def find_valid_puyapy_command(version: str | None) -> list[str]:
+    return _find_puya_command_at_version(version) if version is not None else _find_puya_command()
+
+
+def _find_puya_command_at_version(version: str) -> list[str]:
+    """
+    Find puya command with a specific version.
+    If the puya version isn't installed, install it with pipx run.
+    """
+    for puyapy_command in _get_candidates_puyapy_commands():
+        try:
+            puyapy_version_result = run([*puyapy_command, "--version"])
+        except OSError:
+            pass  # in case of path/permission issues, go to next candidate
+        else:
+            if puyapy_version_result.exit_code == 0 and (
+                extract_version_triple(version) == extract_version_triple(puyapy_version_result.output)
+            ):
+                return puyapy_command
+
+    pipx_command = find_valid_pipx_command(
+        "Unable to find pipx install so that `PuyaPy` compiler can be installed; "
+        "please install pipx via https://pypa.github.io/pipx/ "
+        "and then try `algokit compile py ...` again."
+    )
+
+    return [
+        *pipx_command,
+        "run",
+        f"puya=={version}",
+    ]
+
+
+def _find_puya_command() -> list[str]:
+    """
+    Find puya command.
+    If puya isn't installed, install the latest version with pipx.
+    """
+    for puyapy_command in _get_candidates_puyapy_commands():
+        try:
+            puyapy_help_result = run([*puyapy_command, "-h"])
+        except OSError:
+            pass  # in case of path/permission issues, go to next candidate
+        else:
+            if puyapy_help_result.exit_code == 0:
+                return puyapy_command
+
+    pipx_command = find_valid_pipx_command(
+        "Unable to find pipx install so that `PuyaPy` compiler can be installed; "
+        "please install pipx via https://pypa.github.io/pipx/ "
+        "and then try `algokit compile py ...` again."
+    )
+    _install_puyapy_with_pipx(pipx_command)
+    return ["puyapy"]
+
+
+def _install_puyapy_with_pipx(pipx_command: list[str]) -> None:
+    run(
+        [
+            *pipx_command,
+            "install",
+            "puya",
+        ],
+        bad_return_code_error_message=(
+            "Unable to install puya via pipx; please install puya manually and try `algokit compile py ...` again."
+        ),
+    )
+
+
+def _get_candidates_puyapy_commands() -> Iterator[list[str]]:
+    # when puya is installed at the project level
+    yield ["poetry", "run", "puyapy"]
+    # when puya is installed at the global level
+    yield ["puyapy"]

tests/compile/test_py.py

@@ -0,0 +1,93 @@
+from pathlib import Path
+
+import pytest
+from pytest_mock import MockerFixture
+
+from tests.utils.approvals import verify
+from tests.utils.click_invoker import invoke
+from tests.utils.proc_mock import ProcMock
+
+
+def _normalize_path(path: Path) -> str:
+    return str(path.absolute()).replace("\\", r"\\")
+
+
+@pytest.fixture()
+def hello_world_contract_path() -> Path:
+    return Path(__file__).parent / "hello_world_contract.py"
+
+
+def test_compile_py_help(mocker: MockerFixture) -> None:
+    proc_mock = ProcMock()
+    proc_mock.set_output(["poetry", "run", "puyapy", "-h"], output=["Puyapy help"])
+
+    mocker.patch("algokit.core.proc.Popen").side_effect = proc_mock.popen
+    result = invoke("compile py -h")
+
+    assert result.exit_code == 0
+    verify(result.output)
+
+
+def test_puyapy_is_not_installed_anywhere(hello_world_contract_path: Path, mocker: MockerFixture) -> None:
+    proc_mock = ProcMock()
+    proc_mock.should_bad_exit_on(["poetry", "run", "puyapy", "-h"], exit_code=1, output=["Puyapy not found"])
+    proc_mock.should_bad_exit_on(["puyapy", "-h"], exit_code=1, output=["Puyapy not found"])
+
+    proc_mock.set_output(["pipx", "--version"], ["1.0.0"])
+
+    proc_mock.set_output(["pipx", "install", "puya"], ["Puyapy is installed"])
+    proc_mock.set_output(["puyapy", str(hello_world_contract_path)], ["Done"])
+
+    mocker.patch("algokit.core.proc.Popen").side_effect = proc_mock.popen
+
+    result = invoke(f"compile py {_normalize_path(hello_world_contract_path)}")
+
+    assert result.exit_code == 0
+    verify(result.output)
+
+
+def test_specificed_puyapy_version_is_not_installed(hello_world_contract_path: Path, mocker: MockerFixture) -> None:
+    current_version = "1.0.0"
+    target_version = "1.1.0"
+
+    proc_mock = ProcMock()
+    proc_mock.set_output(["poetry", "run", "puyapy", "--version"], output=[current_version])
+    proc_mock.should_bad_exit_on(["puyapy", "--version"], exit_code=1, output=["Puyapy not found"])
+
+    proc_mock.set_output(["pipx", "--version"], ["1.0.0"])
+    proc_mock.set_output(["pipx", "run", f"puya=={target_version}", str(hello_world_contract_path)], ["Done"])
+
+    mocker.patch("algokit.core.proc.Popen").side_effect = proc_mock.popen
+
+    result = invoke(f"compile --version {target_version} py {_normalize_path(hello_world_contract_path)}")
+
+    assert result.exit_code == 0
+    verify(result.output)
+
+
+def test_puyapy_is_installed_in_project(hello_world_contract_path: Path, mocker: MockerFixture) -> None:
+    proc_mock = ProcMock()
+    proc_mock.set_output(["poetry", "run", "puyapy", "-h"], output=["Puyapy help"])
+    proc_mock.set_output(["poetry", "run", "puyapy", str(hello_world_contract_path)], ["Done"])
+
+    mocker.patch("algokit.core.proc.Popen").side_effect = proc_mock.popen
+
+    result = invoke(f"compile py {_normalize_path(hello_world_contract_path)}")
+
+    assert result.exit_code == 0
+    verify(result.output)
+
+
+def test_puyapy_is_installed_globally(hello_world_contract_path: Path, mocker: MockerFixture) -> None:
+    proc_mock = ProcMock()
+    proc_mock.should_bad_exit_on(["poetry", "run", "puyapy", "-h"], exit_code=1, output=["Puyapy not found"])
+
+    proc_mock.set_output(["puyapy", "-h"], output=["Puyapy help"])
+    proc_mock.set_output(["puyapy", str(hello_world_contract_path)], ["Done"])
+
+    mocker.patch("algokit.core.proc.Popen").side_effect = proc_mock.popen
+
+    result = invoke(f"compile py {_normalize_path(hello_world_contract_path)}")
+
+    assert result.exit_code == 0
+    verify(result.output)

tests/compile/test_py.test_compile_py_help.approved.txt

@@ -0,0 +1,5 @@
+DEBUG: Running 'poetry run puyapy -h' in '{current_working_directory}'
+DEBUG: poetry: Puyapy help
+DEBUG: Running 'poetry run puyapy -h' in '{current_working_directory}'
+DEBUG: poetry: Puyapy help
+Puyapy help

tests/compile/test_py.test_puyapy_is_installed_globally.approved.txt

@@ -0,0 +1,7 @@
+DEBUG: Running 'poetry run puyapy -h' in '{current_working_directory}'
+DEBUG: poetry: Puyapy not found
+DEBUG: Running 'puyapy -h' in '{current_working_directory}'
+DEBUG: puyapy: Puyapy help
+DEBUG: Running 'puyapy {current_working_directory}/tests/compile/hello_world_contract.py' in '{current_working_directory}'
+DEBUG: puyapy: Done
+Done

tests/compile/test_py.test_puyapy_is_installed_in_project.approved.txt

@@ -0,0 +1,5 @@
+DEBUG: Running 'poetry run puyapy -h' in '{current_working_directory}'
+DEBUG: poetry: Puyapy help
+DEBUG: Running 'poetry run puyapy {current_working_directory}/tests/compile/hello_world_contract.py' in '{current_working_directory}'
+DEBUG: poetry: Done
+Done

tests/compile/test_py.test_puyapy_is_not_installed_anywhere.approved.txt

@@ -0,0 +1,11 @@
+DEBUG: Running 'poetry run puyapy -h' in '{current_working_directory}'
+DEBUG: poetry: Puyapy not found
+DEBUG: Running 'puyapy -h' in '{current_working_directory}'
+DEBUG: puyapy: Puyapy not found
+DEBUG: Running 'pipx --version' in '{current_working_directory}'
+DEBUG: pipx: 1.0.0
+DEBUG: Running 'pipx install puya' in '{current_working_directory}'
+DEBUG: pipx: Puyapy is installed
+DEBUG: Running 'puyapy {current_working_directory}/tests/compile/hello_world_contract.py' in '{current_working_directory}'
+DEBUG: puyapy: Done
+Done

tests/compile/test_py.test_specificed_puyapy_version_is_not_installed.approved.txt

@@ -0,0 +1,9 @@
+DEBUG: Running 'poetry run puyapy --version' in '{current_working_directory}'
+DEBUG: poetry: 1.0.0
+DEBUG: Running 'puyapy --version' in '{current_working_directory}'
+DEBUG: puyapy: Puyapy not found
+DEBUG: Running 'pipx --version' in '{current_working_directory}'
+DEBUG: pipx: 1.0.0
+DEBUG: Running 'pipx run puya==1.1.0 {current_working_directory}/tests/compile/hello_world_contract.py' in '{current_working_directory}'
+DEBUG: pipx: Done
+Done