algorand-python-testing 0.2.0__tar.gz → 0.2.1__tar.gz

algorand_python_testing-0.2.1/.venv.cicd/lib/python3.12/site-packages/algokit/cli/common/utils.py

@@ -0,0 +1,103 @@
+# Cli/Click related helper functions and classes
+
+
+import typing as t
+
+import click
+
+from algokit.cli.common.constants import ExplorerEntityType
+
+
+class MutuallyExclusiveOption(click.Option):
+    """
+    A Click option that defines mutually exclusive command line options.
+
+    Args:
+        *args: Positional arguments passed to the parent class constructor.
+        **kwargs: Keyword arguments passed to the parent class constructor.
+            not_required_if (list): A list of options that the current option is mutually exclusive with.
+
+    Attributes:
+        not_required_if (list): A list of options that the current option is mutually exclusive with.
+
+    Raises:
+        AssertionError: If the `not_required_if` parameter is not provided.
+
+    Example:
+        ```python
+        @click.command()
+        @click.option('--option1', help='Option 1')
+        @click.option('--option2', help='Option 2')
+        @click.option('--option3', help='Option 3', cls=MutuallyExclusiveOption, not_required_if=['option1', 'option2'])
+        def my_command(option1, option2, option3):
+            # Command logic here
+            pass
+        ```
+
+        In the example above, the `MutuallyExclusiveOption` class is used to define the `option3` command line option.
+        This option is mutually exclusive with `option1` and `option2`,
+        meaning that if either `option1` or `option2` is provided, `option3` cannot be used.
+        If `option3` is provided along with `option1` or `option2`, a `click.UsageError` is raised.
+    """
+
+    def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
+        self.not_required_if: list = kwargs.pop("not_required_if")
+
+        assert self.not_required_if, "'not_required_if' parameter required"
+        kwargs["help"] = (
+            kwargs.get("help", "") + " Option is mutually exclusive with " + ", ".join(self.not_required_if) + "."
+        ).strip()
+        super().__init__(*args, **kwargs)
+
+    def handle_parse_result(
+        self, ctx: click.Context, opts: t.Mapping[str, t.Any], args: list[str]
+    ) -> tuple[t.Any, list[str]]:
+        """
+        Overrides the `handle_parse_result` method of the `click.Option` class.
+
+        This method checks if the current option is present in the provided options (`opts`)
+        and if any of the mutually exclusive options are also present.
+        If both the current option and a mutually exclusive option are present, it raises a `click.UsageError`.
+        Otherwise, it returns the result of the parent `handle_parse_result` method.
+
+        Args:
+            ctx (click.Context): The Click context object.
+            opts (dict): The dictionary of parsed options.
+            args (list): The list of remaining arguments.
+
+        Returns:
+            The result of the parent `handle_parse_result` method.
+
+        Raises:
+            click.UsageError: If the current option and a mutually exclusive option are both present.
+        """
+
+        current_opt: bool = self.name in opts
+        for mutex_opt in self.not_required_if:
+            if mutex_opt in opts:
+                if current_opt:
+                    raise click.UsageError(
+                        "Illegal usage: '" + str(self.name) + "' is mutually exclusive with " + str(mutex_opt) + "."
+                    )
+                self.prompt = None
+        return super().handle_parse_result(ctx, opts, args)
+
+
+def get_explorer_url(identifier: str | int, network: str, entity_type: ExplorerEntityType) -> str:
+    """
+    Returns a URL for exploring a specified type (transaction, asset, address) on the specified network.
+
+    Args:
+        identifier (str | int): The ID of the transaction, asset, or address to explore.
+        network (str): The name of the network (e.g., "localnet", "testnet", "mainnet").
+        entity_type (ExplorerEntityType): The type to explore (e.g., ExplorerEntityType.TRANSACTION,
+        ExplorerEntityType.ASSET, ExplorerEntityType.ADDRESS).
+
+    Returns:
+        str: The URL for exploring the specified type on the specified network.
+
+    Raises:
+        ValueError: If the network or explorer type is invalid.
+    """
+
+    return f"https://explore.algokit.io/{network}/{entity_type.value}/{identifier}"

algorand_python_testing-0.2.1/.venv.cicd/lib/python3.12/site-packages/algokit/cli/explore.py

@@ -0,0 +1,100 @@
+import logging
+import os
+from typing import TypedDict
+from urllib.parse import urlencode
+
+import click
+
+from algokit.core.sandbox import DEFAULT_ALGOD_PORT, DEFAULT_ALGOD_SERVER, DEFAULT_ALGOD_TOKEN, DEFAULT_INDEXER_PORT
+
+logger = logging.getLogger(__name__)
+
+
+class NetworkConfigurationRequired(TypedDict):
+    algod_url: str
+    indexer_url: str
+
+
+class NetworkConfiguration(NetworkConfigurationRequired, total=False):
+    algod_port: int
+    algod_token: str
+
+    indexer_port: int
+    indexer_token: str
+
+    kmd_token: str
+    kmd_url: str
+    kmd_port: int
+
+
+GITPOD_URL = os.environ.get("GITPOD_WORKSPACE_URL")
+CODESPACE_NAME = os.environ.get("CODESPACE_NAME")
+
+if GITPOD_URL:
+    algod_url = GITPOD_URL.replace("https://", "https://4001-")
+    indexer_url = GITPOD_URL.replace("https://", "https://8980-")
+    kmd_url = GITPOD_URL.replace("https://", "https://4002-")
+    algod_port = 443
+    indexer_port = 443
+    kmd_port = 443
+elif CODESPACE_NAME:
+    algod_url = f"https://{CODESPACE_NAME}-4001.app.github.dev"
+    indexer_url = f"https://{CODESPACE_NAME}-8980.app.github.dev"
+    kmd_url = f"https://{CODESPACE_NAME}-4002.app.github.dev"
+    algod_port = 443
+    indexer_port = 443
+    kmd_port = 443
+else:
+    algod_url = DEFAULT_ALGOD_SERVER
+    indexer_url = DEFAULT_ALGOD_SERVER
+    kmd_url = DEFAULT_ALGOD_SERVER
+    algod_port = DEFAULT_ALGOD_PORT
+    indexer_port = DEFAULT_INDEXER_PORT
+    kmd_port = DEFAULT_ALGOD_PORT + 1
+
+NETWORKS: dict[str, NetworkConfiguration] = {
+    "localnet": {
+        "algod_url": algod_url,
+        "indexer_url": indexer_url,
+        "algod_port": algod_port,
+        "algod_token": DEFAULT_ALGOD_TOKEN,
+        "indexer_port": indexer_port,
+        "indexer_token": DEFAULT_ALGOD_TOKEN,
+        "kmd_token": DEFAULT_ALGOD_TOKEN,
+        "kmd_port": kmd_port,
+        "kmd_url": kmd_url,
+    },  # TODO: query these instead of using constants
+    "testnet": {
+        "algod_url": "https://testnet-api.algonode.cloud",
+        "indexer_url": "https://testnet-idx.algonode.cloud",
+    },
+    "mainnet": {
+        "algod_url": "https://mainnet-api.algonode.cloud",
+        "indexer_url": "https://mainnet-idx.algonode.cloud",
+    },
+}
+
+
+# lora doesn't currently support custom networks, so use Dappflow for now.
+def get_dappflow_url(network: NetworkConfiguration) -> str:
+    query_string = urlencode(network)
+    return f"https://app.dappflow.org/setup-config?{query_string}"
+
+
+def get_algokit_url(network: str) -> str:
+    return f"https://explore.algokit.io/{network}"
+
+
+def get_explore_url(network: str) -> str:
+    if network == "localnet" and NETWORKS[network].get("algod_url") != DEFAULT_ALGOD_SERVER:
+        return get_dappflow_url(NETWORKS[network])
+
+    return get_algokit_url(network)
+
+
+@click.command("explore", help="Explore the specified network using lora.")
+@click.argument("network", type=click.Choice(list(NETWORKS)), default="localnet", required=False)
+def explore_command(network: str) -> None:
+    url = get_explore_url(network)
+    logger.info(f"Opening {network} explorer in your default browser")
+    click.launch(url)

algorand_python_testing-0.2.1/.venv.cicd/lib/python3.12/site-packages/algokit/cli/localnet.py

@@ -0,0 +1,296 @@
+import logging
+
+import click
+import questionary
+
+from algokit.cli.codespace import codespace_command
+from algokit.cli.explore import explore_command
+from algokit.cli.goal import goal_command
+from algokit.core import proc
+from algokit.core.config_commands.container_engine import get_container_engine, save_container_engine
+from algokit.core.sandbox import (
+    COMPOSE_VERSION_COMMAND,
+    SANDBOX_BASE_NAME,
+    ComposeFileStatus,
+    ComposeSandbox,
+    ContainerEngine,
+    fetch_algod_status_data,
+    fetch_indexer_status_data,
+    get_min_compose_version,
+)
+from algokit.core.utils import extract_version_triple, is_minimum_version
+
+logger = logging.getLogger(__name__)
+
+
+@click.group("localnet", short_help="Manage the AlgoKit LocalNet.")
+@click.pass_context
+def localnet_group(ctx: click.Context) -> None:
+    if ctx.invoked_subcommand and "codespace" in ctx.invoked_subcommand or not ctx.invoked_subcommand:
+        return
+
+    try:
+        compose_version_result = proc.run(COMPOSE_VERSION_COMMAND)
+    except OSError as ex:
+        # an IOError (such as PermissionError or FileNotFoundError) will only occur if "docker"
+        # isn't an executable in the user's path, which means docker isn't installed
+        raise click.ClickException(
+            "Container engine not found; please install Docker or Podman and add to path."
+        ) from ex
+    if compose_version_result.exit_code != 0:
+        raise click.ClickException(
+            "Container engine compose not found; please install Docker Compose or Podman Compose and add to path."
+        )
+
+    compose_minimum_version = get_min_compose_version()
+    try:
+        compose_version_str = extract_version_triple(compose_version_result.output)
+        compose_version_ok = is_minimum_version(compose_version_str, compose_minimum_version)
+    except Exception:
+        logger.warning(
+            "Unable to extract compose version from output: \n"
+            + compose_version_result.output
+            + f"\nPlease ensure a minimum of compose v{compose_minimum_version} is used",
+            exc_info=True,
+        )
+    else:
+        if not compose_version_ok:
+            raise click.ClickException(
+                f"Minimum compose version supported: v{compose_minimum_version}, "
+                f"installed = v{compose_version_str}\n"
+                "Please update your compose install"
+            )
+
+    if ctx.invoked_subcommand and ctx.invoked_subcommand == "config":
+        return
+
+    proc.run(
+        [get_container_engine(), "version"],
+        bad_return_code_error_message="Container engine isn't running; please start it.",
+    )
+
+
+@localnet_group.command("config", short_help="Configure the container engine for AlgoKit LocalNet.")
+@click.argument("engine", required=False, type=click.Choice(["docker", "podman"]))
+@click.option(
+    "--force",
+    "-f",
+    is_flag=True,
+    required=False,
+    default=False,
+    type=click.BOOL,
+    help=("Skip confirmation prompts. " "Defaults to 'yes' to all prompts."),
+)
+def config_command(*, engine: str | None, force: bool) -> None:
+    """Set the default container engine for use by AlgoKit CLI to run LocalNet images."""
+    if engine is None:
+        current_engine = get_container_engine()
+        choices = [
+            f"Docker {'(Active)' if current_engine == ContainerEngine.DOCKER else ''}".strip(),
+            f"Podman {'(Active)' if current_engine == ContainerEngine.PODMAN else ''}".strip(),
+        ]
+        engine = questionary.select("Which container engine do you prefer?", choices=choices).ask()
+        if engine is None:
+            raise click.ClickException("No valid container engine selected. Aborting...")
+        engine = engine.split()[0].lower()
+
+    sandbox = ComposeSandbox.from_environment()
+    has_active_instance = sandbox is not None and (
+        force
+        or click.confirm(
+            f"Detected active localnet instance, would you like to restart it with '{engine}'?",
+            default=True,
+        )
+    )
+    if sandbox and has_active_instance:
+        sandbox.down()
+        save_container_engine(engine)
+        sandbox.write_compose_file()
+        sandbox.up()
+    else:
+        save_container_engine(engine)
+
+    logger.info(f"Container engine set to `{engine}`")
+
+
+localnet_group.add_command(config_command)
+
+
+@localnet_group.command("start", short_help="Start the AlgoKit LocalNet.")
+@click.option(
+    "name",
+    "--name",
+    "-n",
+    default=None,
+    help="Specify a name for a custom LocalNet instance. "
+    "AlgoKit will not manage the configuration of named LocalNet instances, "
+    "allowing developers to configure it in any way they need.",
+)
+def start_localnet(name: str | None) -> None:
+    sandbox = ComposeSandbox.from_environment()
+    full_name = f"{SANDBOX_BASE_NAME}_{name}" if name is not None else SANDBOX_BASE_NAME
+    if sandbox is not None and full_name != sandbox.name:
+        logger.debug("LocalNet is already running.")
+        if click.confirm("This will stop any running AlgoKit LocalNet instance. Are you sure?", default=True):
+            sandbox.stop()
+        else:
+            raise click.ClickException("LocalNet is already running. Please stop it first")
+    sandbox = ComposeSandbox() if name is None else ComposeSandbox(name)
+    compose_file_status = sandbox.compose_file_status()
+    sandbox.check_docker_compose_for_new_image_versions()
+    if compose_file_status is ComposeFileStatus.MISSING:
+        logger.debug("LocalNet compose file does not exist yet; writing it out for the first time")
+        sandbox.write_compose_file()
+        if name is not None:
+            logger.info(
+                f"The named LocalNet configuration has been created in {sandbox.directory}. \n"
+                f"You can edit the configuration by changing those files. "
+                f"Running `algokit localnet reset` will ensure the configuration is applied"
+            )
+    elif compose_file_status is ComposeFileStatus.UP_TO_DATE:
+        logger.debug("LocalNet compose file does not require updating")
+    elif compose_file_status is ComposeFileStatus.OUT_OF_DATE and name is None:
+        logger.warning("LocalNet definition is out of date; please run `algokit localnet reset`")
+    if name is not None:
+        logger.info(
+            "A named LocalNet is running, update checks are disabled. If you wish to synchronize with the latest "
+            "version, run `algokit localnet reset --update`"
+        )
+    sandbox.up()
+
+
+@localnet_group.command("stop", short_help="Stop the AlgoKit LocalNet.")
+def stop_localnet() -> None:
+    sandbox = ComposeSandbox.from_environment()
+    if sandbox is not None:
+        compose_file_status = sandbox.compose_file_status()
+        if compose_file_status is not ComposeFileStatus.MISSING:
+            sandbox.stop()
+    else:
+        logger.debug("LocalNet is not running; run `algokit localnet start` to start the AlgoKit LocalNet")
+
+
+@localnet_group.command("reset", short_help="Reset the AlgoKit LocalNet.")
+@click.option(
+    "--update/--no-update",
+    default=False,
+    help="Enable or disable updating to the latest available LocalNet version, default: don't update",
+)
+def reset_localnet(*, update: bool) -> None:
+    sandbox = ComposeSandbox.from_environment()
+    if sandbox is None:
+        sandbox = ComposeSandbox()
+    compose_file_status = sandbox.compose_file_status()
+    if compose_file_status is ComposeFileStatus.MISSING:
+        logger.debug("Existing LocalNet not found; creating from scratch...")
+        sandbox.write_compose_file()
+    elif sandbox.name == SANDBOX_BASE_NAME:
+        sandbox.down()
+        if compose_file_status is not ComposeFileStatus.UP_TO_DATE:
+            logger.info("LocalNet definition is out of date; updating it to latest")
+            sandbox.write_compose_file()
+        if update:
+            sandbox.pull()
+        else:
+            sandbox.check_docker_compose_for_new_image_versions()
+    elif update:
+        if click.confirm(
+            f"A named LocalNet is running, are you sure you want to reset the LocalNet configuration "
+            f"in {sandbox.directory}?\nThis will stop the running LocalNet and overwrite any changes "
+            "you've made to the configuration",
+            default=True,
+        ):
+            sandbox.down()
+            sandbox.write_compose_file()
+            sandbox.pull()
+        else:
+            raise click.ClickException("LocalNet configuration has not been reset")
+    else:
+        sandbox.down()
+    sandbox.up()
+
+
+SERVICE_NAMES = ("algod", "conduit", "indexer-db", "indexer", "proxy")
+
+
+@localnet_group.command("status", short_help="Check the status of the AlgoKit LocalNet.")
+def localnet_status() -> None:
+    sandbox = ComposeSandbox.from_environment()
+    if sandbox is None:
+        sandbox = ComposeSandbox()
+
+    logger.info("# container engine")
+    logger.info(
+        "Name: " + click.style(get_container_engine(), bold=True) + " (change with `algokit config container-engine`)"
+    )
+
+    ps = sandbox.ps()
+    ps_by_name = {stats["Service"]: stats for stats in ps}
+    # if any of the required containers does not exist (ie it's not just stopped but hasn't even been created),
+    # then they will be missing from the output dictionary
+    if set(SERVICE_NAMES) != ps_by_name.keys():
+        raise click.ClickException("LocalNet has not been initialized yet, please run 'algokit localnet start'")
+    # initialise output dict by setting status
+    output_by_name = {
+        name: {"Status": "Running" if ps_by_name[name]["State"] == "running" else "Not running"}
+        for name in SERVICE_NAMES
+    }
+    # fill out remaining output_by_name["algod"] values
+    if output_by_name["algod"]["Status"] == "Running":
+        output_by_name["algod"].update(fetch_algod_status_data(ps_by_name["proxy"]))
+    # fill out remaining output_by_name["indexer"] values
+    if output_by_name["indexer"]["Status"] == "Running":
+        output_by_name["indexer"].update(fetch_indexer_status_data(ps_by_name["proxy"]))
+
+    # Print the status details
+    for service_name, service_info in output_by_name.items():
+        logger.info(click.style(f"# {service_name} status", bold=True))
+        for key, value in service_info.items():
+            logger.info(click.style(f"{key}:", bold=True) + f" {value}")
+
+    # return non-zero if any container is not running
+    if not all(item["Status"] == "Running" for item in output_by_name.values()):
+        raise click.ClickException(
+            "At least one container isn't running; execute `algokit localnet start` to start the LocalNet"
+        )
+
+
+@localnet_group.command(
+    "console",
+    short_help="Run the Algorand goal CLI against the AlgoKit LocalNet via a Bash console"
+    " so you can execute multiple goal commands and/or interact with a filesystem.",
+)
+@click.pass_context
+def localnet_console(context: click.Context) -> None:
+    context.invoke(goal_command, console=True)
+
+
+@localnet_group.command("explore", short_help="Explore the AlgoKit LocalNet using lora.")
+@click.pass_context
+def localnet_explore(context: click.Context) -> None:
+    context.invoke(explore_command)
+
+
+@localnet_group.command(
+    "logs",
+    short_help="See the output of the Docker containers.",
+)
+@click.option(
+    "--follow/-f",
+    is_flag=True,
+    help="Follow log output.",
+    default=False,
+)
+@click.option(
+    "--tail",
+    default="all",
+    help="Number of lines to show from the end of the logs for each container.",
+    show_default=True,
+)
+@click.pass_context
+def localnet_logs(ctx: click.Context, *, follow: bool, tail: str) -> None:
+    sandbox = ComposeSandbox()
+    sandbox.logs(follow=follow, no_color=ctx.color is False, tail=tail)
+
+
+localnet_group.add_command(codespace_command)