algokit-utils 2.4.0b1__py3-none-any.whl → 3.0.0b2__py3-none-any.whl

algokit_utils/clients/dispenser_api_client.py

@@ -0,0 +1,192 @@
+import contextlib
+import enum
+import os
+from dataclasses import dataclass
+
+import httpx
+
+from algokit_utils.config import config
+
+__all__ = [
+    "DISPENSER_ACCESS_TOKEN_KEY",
+    "DISPENSER_ASSETS",
+    "DISPENSER_REQUEST_TIMEOUT",
+    "DispenserApiConfig",
+    "DispenserAsset",
+    "DispenserAssetName",
+    "DispenserFundResponse",
+    "DispenserLimitResponse",
+    "TestNetDispenserApiClient",
+]
+
+
+logger = config.logger
+
+
+class DispenserApiConfig:
+    BASE_URL = "https://api.dispenser.algorandfoundation.tools"
+
+
+class DispenserAssetName(enum.IntEnum):
+    ALGO = 0
+
+
+@dataclass
+class DispenserAsset:
+    asset_id: int
+    decimals: int
+    description: str
+
+
+@dataclass
+class DispenserFundResponse:
+    tx_id: str
+    amount: int
+
+
+@dataclass
+class DispenserLimitResponse:
+    amount: int
+
+
+DISPENSER_ASSETS = {
+    DispenserAssetName.ALGO: DispenserAsset(
+        asset_id=0,
+        decimals=6,
+        description="Algo",
+    ),
+}
+DISPENSER_REQUEST_TIMEOUT = 15
+DISPENSER_ACCESS_TOKEN_KEY = "ALGOKIT_DISPENSER_ACCESS_TOKEN"
+
+
+class TestNetDispenserApiClient:
+    """
+    Client for interacting with the [AlgoKit TestNet Dispenser API](https://github.com/algorandfoundation/algokit/blob/main/docs/testnet_api.md).
+    To get started create a new access token via `algokit dispenser login --ci`
+    and pass it to the client constructor as `auth_token`.
+    Alternatively set the access token as environment variable `ALGOKIT_DISPENSER_ACCESS_TOKEN`,
+    and it will be auto loaded. If both are set, the constructor argument takes precedence.
+
+    Default request timeout is 15 seconds. Modify by passing `request_timeout` to the constructor.
+    """
+
+    auth_token: str
+    request_timeout = DISPENSER_REQUEST_TIMEOUT
+
+    def __init__(self, auth_token: str | None = None, request_timeout: int = DISPENSER_REQUEST_TIMEOUT):
+        auth_token_from_env = os.getenv(DISPENSER_ACCESS_TOKEN_KEY)
+
+        if auth_token:
+            self.auth_token = auth_token
+        elif auth_token_from_env:
+            self.auth_token = auth_token_from_env
+        else:
+            raise Exception(
+                f"Can't init AlgoKit TestNet Dispenser API client "
+                f"because neither environment variable {DISPENSER_ACCESS_TOKEN_KEY} or "
+                "the auth_token were provided."
+            )
+
+        self.request_timeout = request_timeout
+
+    def _process_dispenser_request(
+        self, *, auth_token: str, url_suffix: str, data: dict | None = None, method: str = "POST"
+    ) -> httpx.Response:
+        """
+        Generalized method to process http requests to dispenser API
+        """
+
+        headers = {"Authorization": f"Bearer {(auth_token)}"}
+
+        # Set request arguments
+        request_args = {
+            "url": f"{DispenserApiConfig.BASE_URL}/{url_suffix}",
+            "headers": headers,
+            "timeout": self.request_timeout,
+        }
+
+        if method.upper() != "GET" and data is not None:
+            request_args["json"] = data
+
+        try:
+            response: httpx.Response = getattr(httpx, method.lower())(**request_args)
+            response.raise_for_status()
+            return response
+
+        except httpx.HTTPStatusError as err:
+            error_message = f"Error processing dispenser API request: {err.response.status_code}"
+            error_response = None
+            with contextlib.suppress(Exception):
+                error_response = err.response.json()
+
+            if error_response and error_response.get("code"):
+                error_message = error_response.get("code")
+
+            elif err.response.status_code == httpx.codes.BAD_REQUEST:
+                error_message = err.response.json()["message"]
+
+            raise Exception(error_message) from err
+
+        except Exception as err:
+            error_message = "Error processing dispenser API request"
+            logger.debug(f"{error_message}: {err}", exc_info=True)
+            raise err
+
+    def fund(self, address: str, amount: int, asset_id: int) -> DispenserFundResponse:
+        """
+        Fund an account with Algos from the dispenser API
+        """
+
+        try:
+            response = self._process_dispenser_request(
+                auth_token=self.auth_token,
+                url_suffix=f"fund/{asset_id}",
+                data={"receiver": address, "amount": amount, "assetID": asset_id},
+                method="POST",
+            )
+
+            content = response.json()
+            return DispenserFundResponse(tx_id=content["txID"], amount=content["amount"])
+
+        except Exception as err:
+            logger.exception(f"Error funding account {address}: {err}")
+            raise err
+
+    def refund(self, refund_txn_id: str) -> None:
+        """
+        Register a refund for a transaction with the dispenser API
+        """
+
+        try:
+            self._process_dispenser_request(
+                auth_token=self.auth_token,
+                url_suffix="refund",
+                data={"refundTransactionID": refund_txn_id},
+                method="POST",
+            )
+
+        except Exception as err:
+            logger.exception(f"Error issuing refund for txn_id {refund_txn_id}: {err}")
+            raise err
+
+    def get_limit(
+        self,
+        address: str,
+    ) -> DispenserLimitResponse:
+        """
+        Get current limit for an account with Algos from the dispenser API
+        """
+
+        try:
+            response = self._process_dispenser_request(
+                auth_token=self.auth_token,
+                url_suffix=f"fund/{DISPENSER_ASSETS[DispenserAssetName.ALGO].asset_id}/limit",
+                method="GET",
+            )
+            content = response.json()
+
+            return DispenserLimitResponse(amount=content["amount"])
+        except Exception as err:
+            logger.exception(f"Error setting limit for account {address}: {err}")
+            raise err

algokit_utils/common.py

@@ -1,28 +1,10 @@
-"""
-This module contains common classes and methods that are reused in more than one file.
-"""
+import warnings
 
-import base64
-import typing
+warnings.warn(
+    "The legacy v2 common module is deprecated and will be removed in a future version. "
+    "Refer to `CompiledTeal` class from `algokit_utils` instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
 
-from algosdk.source_map import SourceMap
-
-from algokit_utils import deploy
-
-if typing.TYPE_CHECKING:
-    from algosdk.v2client.algod import AlgodClient
-
-
-class Program:
-    """A compiled TEAL program"""
-
-    def __init__(self, program: str, client: "AlgodClient"):
-        """
-        Fully compile the program source to binary and generate a
-        source map for matching pc to line number
-        """
-        self.teal = program
-        result: dict = client.compile(deploy.strip_comments(self.teal), source_map=True)
-        self.raw_binary = base64.b64decode(result["result"])
-        self.binary_hash: str = result["hash"]
-        self.source_map = SourceMap(result["sourcemap"])
+from algokit_utils._legacy_v2.common import *  # noqa: F403, E402

algokit_utils/config.py

@@ -2,14 +2,57 @@ import logging
 import os
 from collections.abc import Callable
 from pathlib import Path
-
-logger = logging.getLogger(__name__)
+from typing import Any
 
 # Environment variable to override the project root
 ALGOKIT_PROJECT_ROOT = os.getenv("ALGOKIT_PROJECT_ROOT")
 ALGOKIT_CONFIG_FILENAME = ".algokit.toml"
 
 
+class AlgoKitLogger:
+    def __init__(self) -> None:
+        self._logger = logging.getLogger("algokit")
+        self._setup_logger()
+
+    def _setup_logger(self) -> None:
+        formatter = logging.Formatter("%(levelname)s: %(message)s")
+        handler = logging.StreamHandler()
+        handler.setFormatter(formatter)
+        self._logger.addHandler(handler)
+        self._logger.setLevel(logging.INFO)
+
+    def _get_logger(self, *, suppress_log: bool = False) -> logging.Logger:
+        if suppress_log:
+            null_logger = logging.getLogger("null")
+            null_logger.addHandler(logging.NullHandler())
+            return null_logger
+        return self._logger
+
+    def error(self, message: str, *args: Any, suppress_log: bool = False, **kwargs: Any) -> None:
+        """Log an error message, optionally suppressing output"""
+        self._get_logger(suppress_log=suppress_log).error(message, *args, **kwargs)
+
+    def exception(self, message: str, *args: Any, suppress_log: bool = False, **kwargs: Any) -> None:
+        """Log an exception message, optionally suppressing output"""
+        self._get_logger(suppress_log=suppress_log).exception(message, *args, **kwargs)
+
+    def warning(self, message: str, *args: Any, suppress_log: bool = False, **kwargs: Any) -> None:
+        """Log a warning message, optionally suppressing output"""
+        self._get_logger(suppress_log=suppress_log).warning(message, *args, **kwargs)
+
+    def info(self, message: str, *args: Any, suppress_log: bool = False, **kwargs: Any) -> None:
+        """Log an info message, optionally suppressing output"""
+        self._get_logger(suppress_log=suppress_log).info(message, *args, **kwargs)
+
+    def debug(self, message: str, *args: Any, suppress_log: bool = False, **kwargs: Any) -> None:
+        """Log a debug message, optionally suppressing output"""
+        self._get_logger(suppress_log=suppress_log).debug(message, *args, **kwargs)
+
+    def verbose(self, message: str, *args: Any, suppress_log: bool = False, **kwargs: Any) -> None:
+        """Log a verbose message (maps to debug), optionally suppressing output"""
+        self._get_logger(suppress_log=suppress_log).debug(message, *args, **kwargs)
+
+
 class UpdatableConfig:
     """Class to manage and update configuration settings for the AlgoKit project.
 
@@ -19,26 +62,33 @@ class UpdatableConfig:
         trace_all (bool): Indicates whether to trace all operations.
         trace_buffer_size_mb (int): The size of the trace buffer in megabytes.
         max_search_depth (int): The maximum depth to search for a specific file.
+        populate_app_call_resources (bool): Indicates whether to populate app call resources.
     """
 
     def __init__(self) -> None:
+        self._logger = AlgoKitLogger()
         self._debug: bool = False
         self._project_root: Path | None = None
         self._trace_all: bool = False
         self._trace_buffer_size_mb: int | float = 256  # megabytes
         self._max_search_depth: int = 10
+        self._populate_app_call_resources: bool = False
         self._configure_project_root()
 
     def _configure_project_root(self) -> None:
         """Configures the project root by searching for a specific file within a depth limit."""
         current_path = Path(__file__).resolve()
         for _ in range(self._max_search_depth):
-            logger.debug(f"Searching in: {current_path}")
+            self.logger.debug(f"Searching in: {current_path}")
             if (current_path / ALGOKIT_CONFIG_FILENAME).exists():
                 self._project_root = current_path
                 break
             current_path = current_path.parent
 
+    @property
+    def logger(self) -> AlgoKitLogger:
+        return self._logger
+
     @property
     def debug(self) -> bool:
         """Returns the debug status."""
@@ -59,6 +109,10 @@ class UpdatableConfig:
         """Returns the size of the trace buffer in megabytes."""
         return self._trace_buffer_size_mb
 
+    @property
+    def populate_app_call_resource(self) -> bool:
+        return self._populate_app_call_resources
+
     def with_debug(self, func: Callable[[], str | None]) -> None:
         """Executes a function with debug mode temporarily enabled."""
         original_debug = self._debug
@@ -68,14 +122,15 @@ class UpdatableConfig:
         finally:
             self._debug = original_debug
 
-    def configure(  # noqa: PLR0913
+    def configure(
         self,
         *,
-        debug: bool,
+        debug: bool | None = None,
         project_root: Path | None = None,
         trace_all: bool = False,
         trace_buffer_size_mb: float = 256,
         max_search_depth: int = 10,
+        populate_app_call_resources: bool = False,
     ) -> None:
         """
         Configures various settings for the application.
@@ -85,28 +140,26 @@ class UpdatableConfig:
         If you are executing the config from an algokit compliant project, you can simply call
         `config.configure(debug=True)`.
 
-        Args:
-            debug (bool): Indicates whether debug mode is enabled.
-            project_root (Path | None, optional): The path to the project root directory. Defaults to None.
-            trace_all (bool, optional): Indicates whether to trace all operations. Defaults to False. Which implies that
+        :param debug: Indicates whether debug mode is enabled.
+        :param project_root: The path to the project root directory. Defaults to None.
+        :param trace_all: Indicates whether to trace all operations. Defaults to False. Which implies that
                 only the operations that are failed will be traced by default.
-            trace_buffer_size_mb (float, optional): The size of the trace buffer in megabytes. Defaults to 512mb.
-            max_search_depth (int, optional): The maximum depth to search for a specific file. Defaults to 10.
-
-        Returns:
-            None
+        :param trace_buffer_size_mb: The size of the trace buffer in megabytes. Defaults to 256
+        :param max_search_depth: The maximum depth to search for a specific file. Defaults to 10
+        :param populate_app_call_resources: Indicates whether to populate app call resources. Defaults to False
         """
 
-        self._debug = debug
-
-        if project_root:
+        if debug is not None:
+            self._debug = debug
+        if project_root is not None:
             self._project_root = project_root.resolve(strict=True)
-        elif debug and ALGOKIT_PROJECT_ROOT:
+        elif debug is not None and ALGOKIT_PROJECT_ROOT:
             self._project_root = Path(ALGOKIT_PROJECT_ROOT).resolve(strict=True)
 
         self._trace_all = trace_all
         self._trace_buffer_size_mb = trace_buffer_size_mb
         self._max_search_depth = max_search_depth
+        self._populate_app_call_resources = populate_app_call_resources
 
 
 config = UpdatableConfig()