algokit-utils 2.4.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

algokit_utils/clients/dispenser_api_client.py

@@ -0,0 +1,224 @@
+import contextlib
+import enum
+import os
+from dataclasses import dataclass
+from typing import overload
+
+import httpx
+from typing_extensions import deprecated
+
+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
+    """The ID of the asset"""
+    decimals: int
+    """The amount of decimal places the asset was created with"""
+    description: str
+    """The description of the asset"""
+
+
+@dataclass
+class DispenserFundResponse:
+    tx_id: str
+    """The transaction ID of the funded transaction"""
+    amount: int
+    """The amount of Algos funded"""
+
+
+@dataclass
+class DispenserLimitResponse:
+    amount: int
+    """The amount of Algos that can be funded"""
+
+
+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.
+    """
+
+    # NOTE: ensures pytest does not think this is a test
+    # https://docs.pytest.org/en/stable/example/pythoncollection.html#customizing-test-collection
+    __test__ = False
+    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
+
+    @overload
+    def fund(self, address: str, amount: int) -> DispenserFundResponse: ...
+
+    @deprecated("Asset ID parameter is deprecated. Can now use `fund(address, amount)` instead.")
+    @overload
+    def fund(self, address: str, amount: int, asset_id: int | None = None) -> DispenserFundResponse: ...
+
+    def fund(self, address: str, amount: int, asset_id: int | None = None) -> DispenserFundResponse:  # noqa: ARG002
+        """
+        Fund an account with Algos from the dispenser API
+
+        :param address: The address to fund
+        :param amount: The amount of Algos to fund
+        :param asset_id: The asset ID to fund (deprecated)
+        :return: The transaction ID of the funded transaction
+        :raises Exception: If the dispenser API request fails
+
+        :example:
+            >>> dispenser_client = TestNetDispenserApiClient()
+            >>> dispenser_client.fund(address="SENDER_ADDRESS", amount=1000000)
+        """
+
+        try:
+            response = self._process_dispenser_request(
+                auth_token=self.auth_token,
+                url_suffix=f"fund/{DISPENSER_ASSETS[DispenserAssetName.ALGO].asset_id}",
+                data={
+                    "receiver": address,
+                    "amount": amount,
+                    "assetID": DISPENSER_ASSETS[DispenserAssetName.ALGO].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

@@ -3,42 +3,82 @@ import os
 from collections.abc import Callable
 from pathlib import Path
 
-logger = logging.getLogger(__name__)
-
 # Environment variable to override the project root
 ALGOKIT_PROJECT_ROOT = os.getenv("ALGOKIT_PROJECT_ROOT")
 ALGOKIT_CONFIG_FILENAME = ".algokit.toml"
 
 
+class AlgoKitLogger(logging.Logger):
+    def __init__(self, name: str = "algokit-utils-py", level: int = logging.NOTSET):
+        super().__init__(name, level)
+
+    def _log(self, level: int, msg: object, args, exc_info=None, extra=None, stack_info=False, stacklevel=1) -> None:  # type: ignore[no-untyped-def]  # noqa: FBT002, ANN001
+        """
+        Overrides the base _log method to allow suppressing individual log calls.
+        When a caller passes suppress_log=True in the extra keyword, the log call is ignored.
+        """
+
+        # Check if the 'suppress_log' flag is provided in the extra dictionary.
+        if extra and extra.get("suppress_log", False):
+            return
+        # Call the parent _log
+        super()._log(level, msg, args, exc_info, extra, stack_info, stacklevel)
+
+    @classmethod
+    def get_null_logger(cls) -> logging.Logger:
+        """Return a logger that does nothing (a null logger)."""
+        null_logger = logging.getLogger("null")
+        null_logger.handlers.clear()
+        null_logger.addHandler(logging.NullHandler())
+        null_logger.propagate = False
+        return null_logger
+
+
+# Set our custom logger class as the default.
+logging.setLoggerClass(AlgoKitLogger)
+
+
 class UpdatableConfig:
-    """Class to manage and update configuration settings for the AlgoKit project.
+    """
+    Class to manage and update configuration settings for the AlgoKit project.
 
     Attributes:
         debug (bool): Indicates whether debug mode is enabled.
         project_root (Path | None): The path to the project root directory.
         trace_all (bool): Indicates whether to trace all operations.
-        trace_buffer_size_mb (int): The size of the trace buffer in megabytes.
+        trace_buffer_size_mb (int | float): 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): Whether to populate app call resources.
+        logger (logging.Logger): The logger instance to use. Defaults to an AlgoKitLogger instance.
     """
 
     def __init__(self) -> None:
+        self._logger: logging.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."""
+        """
+        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) -> logging.Logger:
+        """Returns the logger instance."""
+        return self._logger
+
     @property
     def debug(self) -> bool:
         """Returns the debug status."""
@@ -51,7 +91,7 @@ class UpdatableConfig:
 
     @property
     def trace_all(self) -> bool:
-        """Indicates whether to store simulation traces for all operations."""
+        """Indicates whether simulation traces for all operations should be stored."""
         return self._trace_all
 
     @property
@@ -59,8 +99,15 @@ 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:
+        """Indicates whether or not to populate app call resources."""
+        return self._populate_app_call_resources
+
     def with_debug(self, func: Callable[[], str | None]) -> None:
-        """Executes a function with debug mode temporarily enabled."""
+        """
+        Executes a function with debug mode temporarily enabled.
+        """
         original_debug = self._debug
         try:
             self._debug = True
@@ -68,45 +115,45 @@ 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,
+        logger: logging.Logger | None = None,
     ) -> None:
         """
         Configures various settings for the application.
-        Please note, when `project_root` is not specified, by default config will attempt to find the `algokit.toml` by
-        scanning the parent directories according to the `max_search_depth` parameter.
-        Alternatively value can also be set via the `ALGOKIT_PROJECT_ROOT` environment variable.
-        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
-                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 debug: Whether debug mode is enabled.
+        :param project_root: The path to the project root directory.
+        :param trace_all: Whether to trace all operations. Defaults to False.
+        :param trace_buffer_size_mb: The trace buffer size 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: Whether to populate app call resources. Defaults to False.
+        :param logger: A custom logger to use. Defaults to AlgoKitLogger instance.
         """
+        if logger is not None:
+            self._logger = logger
 
-        self._debug = debug
+        if debug is not None:
+            self._debug = debug
+            # Update logger's level so debug messages are processed only when debug is True.
+            self._logger.setLevel(logging.DEBUG)
 
-        if project_root:
+        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()