algokit-utils 2.1.2b1__py3-none-any.whl → 2.2.0__py3-none-any.whl

algokit_utils/__init__.py

@@ -1,8 +1,5 @@
-from algokit_utils._ensure_funded import (
-    EnsureBalanceParameters,
-    EnsureFundedResponse,
-    ensure_funded,
-)
+from algokit_utils._debugging import PersistSourceMapInput, persist_sourcemaps, simulate_and_persist_response
+from algokit_utils._ensure_funded import EnsureBalanceParameters, EnsureFundedResponse, ensure_funded
 from algokit_utils._transfer import TransferAssetParameters, TransferParameters, transfer, transfer_asset
 from algokit_utils.account import (
     create_kmd_wallet_account,
@@ -15,7 +12,6 @@ from algokit_utils.account import (
 )
 from algokit_utils.application_client import (
     ApplicationClient,
-    Program,
     execute_atc_with_logic_error,
     get_next_version,
     get_sender_from_signer,
@@ -32,6 +28,7 @@ from algokit_utils.application_specification import (
     OnCompleteActionName,
 )
 from algokit_utils.asset import opt_in, opt_out
+from algokit_utils.common import Program
 from algokit_utils.deploy import (
     DELETABLE_TEMPLATE_NAME,
     NOTE_PREFIX,
@@ -72,14 +69,14 @@ from algokit_utils.models import (
     ABIMethod,
     ABITransactionResponse,
     Account,
-    CommonCallParameters,  # noqa: ignore[F401]
-    CommonCallParametersDict,  # noqa: ignore[F401]
+    CommonCallParameters,  # noqa: F401
+    CommonCallParametersDict,  # noqa: F401
     CreateCallParameters,
     CreateCallParametersDict,
     CreateTransactionParameters,
     OnCompleteCallParameters,
     OnCompleteCallParametersDict,
-    RawTransactionParameters,  # noqa: ignore[F401]
+    RawTransactionParameters,  # noqa: F401
     TransactionParameters,
     TransactionParametersDict,
     TransactionResponse,
@@ -181,4 +178,7 @@ __all__ = [
     "transfer_asset",
     "opt_in",
     "opt_out",
+    "persist_sourcemaps",
+    "PersistSourceMapInput",
+    "simulate_and_persist_response",
 ]

algokit_utils/_debugging.py

@@ -0,0 +1,280 @@
+import base64
+import json
+import logging
+import typing
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+from algosdk.atomic_transaction_composer import (
+    AtomicTransactionComposer,
+    EmptySigner,
+    SimulateAtomicTransactionResponse,
+)
+from algosdk.encoding import checksum
+from algosdk.v2client.models import SimulateRequest, SimulateRequestTransactionGroup, SimulateTraceConfig
+
+from algokit_utils.common import Program
+
+if typing.TYPE_CHECKING:
+    from algosdk.v2client.algod import AlgodClient
+
+logger = logging.getLogger(__name__)
+
+ALGOKIT_DIR = ".algokit"
+SOURCES_DIR = "sources"
+SOURCES_FILE = "sources.avm.json"
+TRACES_FILE_EXT = ".trace.avm.json"
+DEBUG_TRACES_DIR = "debug_traces"
+TEAL_FILE_EXT = ".teal"
+TEAL_SOURCEMAP_EXT = ".teal.tok.map"
+
+
+@dataclass
+class AVMDebuggerSourceMapEntry:
+    location: str = field(metadata={"json": "sourcemap-location"})
+    program_hash: str = field(metadata={"json": "hash"})
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, AVMDebuggerSourceMapEntry):
+            return self.location == other.location and self.program_hash == other.program_hash
+        return False
+
+    def __str__(self) -> str:
+        return json.dumps({"sourcemap-location": self.location, "hash": self.program_hash})
+
+
+@dataclass
+class AVMDebuggerSourceMap:
+    txn_group_sources: list[AVMDebuggerSourceMapEntry] = field(metadata={"json": "txn-group-sources"})
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "AVMDebuggerSourceMap":
+        return cls(
+            txn_group_sources=[
+                AVMDebuggerSourceMapEntry(location=item["sourcemap-location"], program_hash=item["hash"])
+                for item in data.get("txn-group-sources", [])
+            ]
+        )
+
+    def to_dict(self) -> dict:
+        return {"txn-group-sources": [json.loads(str(item)) for item in self.txn_group_sources]}
+
+
+@dataclass
+class PersistSourceMapInput:
+    def __init__(
+        self, app_name: str, file_name: str, raw_teal: str | None = None, compiled_teal: Program | None = None
+    ):
+        self.compiled_teal = compiled_teal
+        self.app_name = app_name
+        self._raw_teal = raw_teal
+        self._file_name = self.strip_teal_extension(file_name)
+
+    @classmethod
+    def from_raw_teal(cls, raw_teal: str, app_name: str, file_name: str) -> "PersistSourceMapInput":
+        return cls(app_name, file_name, raw_teal=raw_teal)
+
+    @classmethod
+    def from_compiled_teal(cls, compiled_teal: Program, app_name: str, file_name: str) -> "PersistSourceMapInput":
+        return cls(app_name, file_name, compiled_teal=compiled_teal)
+
+    @property
+    def raw_teal(self) -> str:
+        if self._raw_teal:
+            return self._raw_teal
+        elif self.compiled_teal:
+            return self.compiled_teal.teal
+        else:
+            raise ValueError("No teal content found")
+
+    @property
+    def file_name(self) -> str:
+        return self._file_name
+
+    @staticmethod
+    def strip_teal_extension(file_name: str) -> str:
+        if file_name.endswith(".teal"):
+            return file_name[:-5]
+        return file_name
+
+
+def _load_or_create_sources(sources_path: Path) -> AVMDebuggerSourceMap:
+    if not sources_path.exists():
+        return AVMDebuggerSourceMap(txn_group_sources=[])
+
+    with sources_path.open() as f:
+        return AVMDebuggerSourceMap.from_dict(json.load(f))
+
+
+def _upsert_debug_sourcemaps(sourcemaps: list[AVMDebuggerSourceMapEntry], project_root: Path) -> None:
+    """
+    This function updates or inserts debug sourcemaps. If path in the sourcemap during iteration leads to non
+    existing file, removes it. Otherwise upserts.
+
+    Args:
+        sourcemaps (list[AVMDebuggerSourceMapEntry]): A list of AVMDebuggerSourceMapEntry objects.
+        project_root (Path): The root directory of the project.
+
+    Returns:
+        None
+    """
+
+    sources_path = project_root / ALGOKIT_DIR / SOURCES_DIR / SOURCES_FILE
+    sources = _load_or_create_sources(sources_path)
+
+    for sourcemap in sourcemaps:
+        source_file_path = Path(sourcemap.location)
+        if not source_file_path.exists() and sourcemap in sources.txn_group_sources:
+            sources.txn_group_sources.remove(sourcemap)
+        elif source_file_path.exists():
+            if sourcemap not in sources.txn_group_sources:
+                sources.txn_group_sources.append(sourcemap)
+            else:
+                index = sources.txn_group_sources.index(sourcemap)
+                sources.txn_group_sources[index] = sourcemap
+
+    with sources_path.open("w") as f:
+        json.dump(sources.to_dict(), f)
+
+
+def _write_to_file(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+
+
+def _build_avm_sourcemap(  # noqa: PLR0913
+    *,
+    app_name: str,
+    file_name: str,
+    output_path: Path,
+    client: "AlgodClient",
+    raw_teal: str | None = None,
+    compiled_teal: Program | None = None,
+    with_sources: bool = True,
+) -> AVMDebuggerSourceMapEntry:
+    if not raw_teal and not compiled_teal:
+        raise ValueError("Either raw teal or compiled teal must be provided")
+
+    result = compiled_teal if compiled_teal else Program(str(raw_teal), client=client)
+    program_hash = base64.b64encode(
+        checksum(result.raw_binary)  # type: ignore[no-untyped-call]
+    ).decode()
+    source_map = result.source_map.__dict__
+    source_map["sources"] = [f"{file_name}{TEAL_FILE_EXT}"] if with_sources else []
+
+    output_dir_path = output_path / ALGOKIT_DIR / SOURCES_DIR / app_name
+    source_map_output_path = output_dir_path / f"{file_name}{TEAL_SOURCEMAP_EXT}"
+    teal_output_path = output_dir_path / f"{file_name}{TEAL_FILE_EXT}"
+    _write_to_file(source_map_output_path, json.dumps(source_map))
+
+    if with_sources:
+        _write_to_file(teal_output_path, result.teal)
+
+    return AVMDebuggerSourceMapEntry(str(source_map_output_path), program_hash)
+
+
+def persist_sourcemaps(
+    *, sources: list[PersistSourceMapInput], project_root: Path, client: "AlgodClient", with_sources: bool = True
+) -> None:
+    """
+    Persist the sourcemaps for the given sources as an AlgoKit AVM Debugger compliant artifacts.
+    Args:
+        sources (list[PersistSourceMapInput]): A list of PersistSourceMapInput objects.
+        project_root (Path): The root directory of the project.
+        client (AlgodClient): An AlgodClient object for interacting with the Algorand blockchain.
+        with_sources (bool): If True, it will dump teal source files along with sourcemaps.
+        Default is True, as needed by an AlgoKit AVM debugger.
+    """
+
+    sourcemaps = [
+        _build_avm_sourcemap(
+            raw_teal=source.raw_teal,
+            compiled_teal=source.compiled_teal,
+            app_name=source.app_name,
+            file_name=source.file_name,
+            output_path=project_root,
+            client=client,
+            with_sources=with_sources,
+        )
+        for source in sources
+    ]
+
+    _upsert_debug_sourcemaps(sourcemaps, project_root)
+
+
+def simulate_response(atc: AtomicTransactionComposer, algod_client: "AlgodClient") -> SimulateAtomicTransactionResponse:
+    """
+    Simulate and fetch response for the given AtomicTransactionComposer and AlgodClient.
+
+    Args:
+        atc (AtomicTransactionComposer): An AtomicTransactionComposer object.
+        algod_client (AlgodClient): An AlgodClient object for interacting with the Algorand blockchain.
+
+    Returns:
+        SimulateAtomicTransactionResponse: The simulated response.
+    """
+
+    unsigned_txn_groups = atc.build_group()
+    empty_signer = EmptySigner()
+    txn_list = [txn_group.txn for txn_group in unsigned_txn_groups]
+    fake_signed_transactions = empty_signer.sign_transactions(txn_list, [])
+    txn_group = [SimulateRequestTransactionGroup(txns=fake_signed_transactions)]
+    trace_config = SimulateTraceConfig(enable=True, stack_change=True, scratch_change=True)
+
+    simulate_request = SimulateRequest(
+        txn_groups=txn_group, allow_more_logs=True, allow_empty_signatures=True, exec_trace_config=trace_config
+    )
+    return atc.simulate(algod_client, simulate_request)
+
+
+def simulate_and_persist_response(
+    atc: AtomicTransactionComposer, project_root: Path, algod_client: "AlgodClient", buffer_size_mb: float = 256
+) -> SimulateAtomicTransactionResponse:
+    """
+    Simulates the atomic transactions using the provided `AtomicTransactionComposer` object and `AlgodClient` object,
+    and persists the simulation response to an AlgoKit AVM Debugger compliant JSON file.
+
+    :param atc: An `AtomicTransactionComposer` object representing the atomic transactions to be
+    simulated and persisted.
+    :param project_root: A `Path` object representing the root directory of the project.
+    :param algod_client: An `AlgodClient` object representing the Algorand client.
+    :param buffer_size_mb: The size of the trace buffer in megabytes. Defaults to 256mb.
+    :return: None
+
+    Returns:
+        SimulateAtomicTransactionResponse: The simulated response after persisting it
+        for AlgoKit AVM Debugger consumption.
+    """
+    atc_to_simulate = atc.clone()
+    sp = algod_client.suggested_params()
+
+    for txn_with_sign in atc_to_simulate.txn_list:
+        txn_with_sign.txn.first_valid_round = sp.first
+        txn_with_sign.txn.last_valid_round = sp.last
+        txn_with_sign.txn.genesis_hash = sp.gh
+
+    response = simulate_response(atc_to_simulate, algod_client)
+    txn_results = response.simulate_response["txn-groups"]
+
+    txn_types = [txn_result["txn-results"][0]["txn-result"]["txn"]["txn"]["type"] for txn_result in txn_results]
+    txn_types_count = {txn_type: txn_types.count(txn_type) for txn_type in set(txn_types)}
+    txn_types_str = "_".join([f"{count}#{txn_type}" for txn_type, count in txn_types_count.items()])
+
+    last_round = response.simulate_response["last-round"]
+    timestamp = datetime.now(tz=timezone.utc).strftime("%Y%m%d_%H%M%S")
+    output_file = project_root / DEBUG_TRACES_DIR / f"{timestamp}_lr{last_round}_{txn_types_str}{TRACES_FILE_EXT}"
+
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+
+    # cleanup old files if buffer size is exceeded
+    total_size = sum(f.stat().st_size for f in output_file.parent.glob("*") if f.is_file())
+    if total_size > buffer_size_mb * 1024 * 1024:
+        sorted_files = sorted(output_file.parent.glob("*"), key=lambda p: p.stat().st_mtime)
+        while total_size > buffer_size_mb * 1024 * 1024:
+            oldest_file = sorted_files.pop(0)
+            total_size -= oldest_file.stat().st_size
+            oldest_file.unlink()
+
+    output_file.write_text(json.dumps(response.simulate_response, indent=2))
+    return response

algokit_utils/application_client.py

@@ -18,7 +18,6 @@ from algosdk.atomic_transaction_composer import (
     AccountTransactionSigner,
     AtomicTransactionComposer,
     AtomicTransactionResponse,
-    EmptySigner,
     LogicSigTransactionSigner,
     MultisigTransactionSigner,
     SimulateAtomicTransactionResponse,
@@ -28,10 +27,16 @@ from algosdk.atomic_transaction_composer import (
 from algosdk.constants import APP_PAGE_MAX_SIZE
 from algosdk.logic import get_application_address
 from algosdk.source_map import SourceMap
-from algosdk.v2client.models import SimulateRequest, SimulateRequestTransactionGroup, SimulateTraceConfig
 
 import algokit_utils.application_specification as au_spec
 import algokit_utils.deploy as au_deploy
+from algokit_utils._debugging import (
+    PersistSourceMapInput,
+    persist_sourcemaps,
+    simulate_and_persist_response,
+    simulate_response,
+)
+from algokit_utils.common import Program
 from algokit_utils.config import config
 from algokit_utils.logic_error import LogicError, parse_logic_error
 from algokit_utils.models import (
@@ -61,7 +66,6 @@ logger = logging.getLogger(__name__)
 
 __all__ = [
     "ApplicationClient",
-    "Program",
     "execute_atc_with_logic_error",
     "get_next_version",
     "get_sender_from_signer",
@@ -72,21 +76,6 @@ __all__ = [
 representing an ABI method name or signature"""
 
 
-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(au_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"])
-
-
 def num_extra_program_pages(approval: bytes, clear: bytes) -> int:
     """Calculate minimum number of extra_pages required for provided approval and clear programs"""
 
@@ -97,7 +86,7 @@ class ApplicationClient:
     """A class that wraps an ARC-0032 app spec and provides high productivity methods to deploy and call the app"""
 
     @overload
-    def __init__(
+    def __init__(  # noqa: PLR0913
         self,
         algod_client: "AlgodClient",
         app_spec: au_spec.ApplicationSpecification | Path,
@@ -111,7 +100,7 @@ class ApplicationClient:
         ...
 
     @overload
-    def __init__(
+    def __init__(  # noqa: PLR0913
         self,
         algod_client: "AlgodClient",
         app_spec: au_spec.ApplicationSpecification | Path,
@@ -127,7 +116,7 @@ class ApplicationClient:
     ):
         ...
 
-    def __init__(
+    def __init__(  # noqa: PLR0913
         self,
         algod_client: "AlgodClient",
         app_spec: au_spec.ApplicationSpecification | Path,
@@ -251,7 +240,7 @@ class ApplicationClient:
         )
         return new_client
 
-    def _prepare(
+    def _prepare(  # noqa: PLR0913
         self,
         target: "ApplicationClient",
         *,
@@ -266,7 +255,7 @@ class ApplicationClient:
         )
         target.template_values = self.template_values | (template_values or {})
 
-    def deploy(
+    def deploy(  # noqa: PLR0913
         self,
         version: str | None = None,
         *,
@@ -346,6 +335,22 @@ class ApplicationClient:
         self._approval_program, self._clear_program = substitute_template_and_compile(
             self.algod_client, self.app_spec, template_values
         )
+
+        if config.debug and config.project_root:
+            persist_sourcemaps(
+                sources=[
+                    PersistSourceMapInput(
+                        compiled_teal=self._approval_program, app_name=self.app_name, file_name="approval.teal"
+                    ),
+                    PersistSourceMapInput(
+                        compiled_teal=self._clear_program, app_name=self.app_name, file_name="clear.teal"
+                    ),
+                ],
+                project_root=config.project_root,
+                client=self.algod_client,
+                with_sources=True,
+            )
+
         deployer = au_deploy.Deployer(
             app_client=self,
             creator=self._creator,
@@ -630,6 +635,11 @@ class ApplicationClient:
         if method:
             hints = self._method_hints(method)
             if hints and hints.read_only:
+                if config.debug and config.project_root and config.trace_all:
+                    simulate_and_persist_response(
+                        atc, config.project_root, self.algod_client, config.trace_buffer_size_mb
+                    )
+
                 return self._simulate_readonly_call(method, atc)
 
         return self._execute_atc_tr(atc)
@@ -865,26 +875,40 @@ class ApplicationClient:
             self._approval_program, self._clear_program = substitute_template_and_compile(
                 self.algod_client, self.app_spec, self.template_values
             )
+
+        if config.debug and config.project_root:
+            persist_sourcemaps(
+                sources=[
+                    PersistSourceMapInput(
+                        compiled_teal=self._approval_program, app_name=self.app_name, file_name="approval.teal"
+                    ),
+                    PersistSourceMapInput(
+                        compiled_teal=self._clear_program, app_name=self.app_name, file_name="clear.teal"
+                    ),
+                ],
+                project_root=config.project_root,
+                client=self.algod_client,
+                with_sources=True,
+            )
+
         return self._approval_program, self._clear_program
 
     def _simulate_readonly_call(
         self, method: Method, atc: AtomicTransactionComposer
     ) -> ABITransactionResponse | TransactionResponse:
-        simulate_response = _simulate_response(atc, self.algod_client)
+        response = simulate_response(atc, self.algod_client)
         traces = None
         if config.debug:
-            traces = _create_simulate_traces(simulate_response)
-        if simulate_response.failure_message:
+            traces = _create_simulate_traces(response)
+        if response.failure_message:
             raise _try_convert_to_logic_error(
-                simulate_response.failure_message,
+                response.failure_message,
                 self.app_spec.approval_program,
                 self._get_approval_source_map,
                 traces,
-            ) or Exception(
-                f"Simulate failed for readonly method {method.get_signature()}: {simulate_response.failure_message}"
-            )
+            ) or Exception(f"Simulate failed for readonly method {method.get_signature()}: {response.failure_message}")
 
-        return TransactionResponse.from_atr(simulate_response)
+        return TransactionResponse.from_atr(response)
 
     def _load_reference_and_check_app_id(self) -> None:
         self._load_app_reference()
@@ -978,7 +1002,7 @@ class ApplicationClient:
         source_map = json.loads(source_map_json)
         self._approval_source_map = SourceMap(source_map)
 
-    def add_method_call(
+    def add_method_call(  # noqa: PLR0913
         self,
         atc: AtomicTransactionComposer,
         abi_method: ABIMethod | bool | None = None,
@@ -1192,7 +1216,9 @@ def substitute_template_and_compile(
     au_deploy.check_template_variables(app_spec.approval_program, template_values)
     approval = au_deploy.replace_template_variables(app_spec.approval_program, template_values)
 
-    return Program(approval, algod_client), Program(clear, algod_client)
+    approval_app, clear_app = Program(approval, algod_client), Program(clear, algod_client)
+
+    return approval_app, clear_app
 
 
 def get_next_version(current_version: str) -> str:
@@ -1263,10 +1289,22 @@ def execute_atc_with_logic_error(
     ```
     """
     try:
+        if config.debug and config.project_root and config.trace_all:
+            simulate_and_persist_response(atc, config.project_root, algod_client, config.trace_buffer_size_mb)
+
         return atc.execute(algod_client, wait_rounds=wait_rounds)
     except Exception as ex:
         if config.debug:
-            simulate = _simulate_response(atc, algod_client)
+            simulate = None
+            if config.project_root and not config.trace_all:
+                # if trace_all is enabled, we already have the traces executed above
+                # hence we only need to simulate if trace_all is disabled and
+                # project_root is set
+                simulate = simulate_and_persist_response(
+                    atc, config.project_root, algod_client, config.trace_buffer_size_mb
+                )
+            else:
+                simulate = simulate_response(atc, algod_client)
             traces = _create_simulate_traces(simulate)
         else:
             traces = None
@@ -1299,22 +1337,6 @@ def _create_simulate_traces(simulate: SimulateAtomicTransactionResponse) -> list
     return traces
 
 
-def _simulate_response(
-    atc: AtomicTransactionComposer, algod_client: "AlgodClient"
-) -> SimulateAtomicTransactionResponse:
-    unsigned_txn_groups = atc.build_group()
-    empty_signer = EmptySigner()
-    txn_list = [txn_group.txn for txn_group in unsigned_txn_groups]
-    fake_signed_transactions = empty_signer.sign_transactions(txn_list, [])
-    txn_group = [SimulateRequestTransactionGroup(txns=fake_signed_transactions)]
-    trace_config = SimulateTraceConfig(enable=True, stack_change=True, scratch_change=True)
-
-    simulate_request = SimulateRequest(
-        txn_groups=txn_group, allow_more_logs=True, allow_empty_signatures=True, exec_trace_config=trace_config
-    )
-    return atc.simulate(algod_client, simulate_request)
-
-
 def _convert_transaction_parameters(
     args: TransactionParameters | TransactionParametersDict | None,
 ) -> CreateCallParameters:

algokit_utils/common.py

@@ -0,0 +1,28 @@
+"""
+This module contains common classes and methods that are reused in more than one file.
+"""
+
+import base64
+import typing
+
+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"])

algokit_utils/config.py

@@ -1,25 +1,112 @@
+import logging
+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 UpdatableConfig:
+    """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.
+        max_search_depth (int): The maximum depth to search for a specific file.
+    """
+
     def __init__(self) -> None:
         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._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.info(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 debug(self) -> bool:
+        """Returns the debug status."""
         return self._debug
 
-    def with_debug(self, lambda_func: Callable[[], None | str]) -> None:
-        original = self._debug
+    @property
+    def project_root(self) -> Path | None:
+        """Returns the project root path."""
+        return self._project_root
+
+    @property
+    def trace_all(self) -> bool:
+        """Indicates whether to store simulation traces for all operations."""
+        return self._trace_all
+
+    @property
+    def trace_buffer_size_mb(self) -> int | float:
+        """Returns the size of the trace buffer in megabytes."""
+        return self._trace_buffer_size_mb
+
+    def with_debug(self, func: Callable[[], str | None]) -> None:
+        """Executes a function with debug mode temporarily enabled."""
+        original_debug = self._debug
         try:
             self._debug = True
-            lambda_func()
+            func()
         finally:
-            self._debug = original
+            self._debug = original_debug
+
+    def configure(  # noqa: PLR0913
+        self,
+        *,
+        debug: bool,
+        project_root: Path | None = None,
+        trace_all: bool = False,
+        trace_buffer_size_mb: float = 256,
+        max_search_depth: int = 10,
+    ) -> 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
+        """
+
+        self._debug = debug
+
+        if project_root:
+            self._project_root = project_root.resolve(strict=True)
+        elif debug and ALGOKIT_PROJECT_ROOT:
+            self._project_root = Path(ALGOKIT_PROJECT_ROOT).resolve(strict=True)
 
-    def configure(self, *, debug: bool) -> None:
-        if debug is not None:
-            self._debug = debug
+        self._trace_all = trace_all
+        self._trace_buffer_size_mb = trace_buffer_size_mb
+        self._max_search_depth = max_search_depth
 
 
 config = UpdatableConfig()

algokit_utils/deploy.py

@@ -253,7 +253,7 @@ class AppChanges:
     schema_change_description: str | None
 
 
-def check_for_app_changes(
+def check_for_app_changes(  # noqa: PLR0913
     algod_client: "AlgodClient",
     *,
     new_approval: bytes,

algokit_utils/logic_error.py

@@ -37,7 +37,7 @@ def parse_logic_error(
 
 
 class LogicError(Exception):
-    def __init__(
+    def __init__(  # noqa: PLR0913
         self,
         *,
         logic_error_str: str,

{algokit_utils-2.1.2b1.dist-info → algokit_utils-2.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: algokit-utils
-Version: 2.1.2b1
+Version: 2.2.0
 Summary: Utilities for Algorand development for use by AlgoKit
 License: MIT
 Author: Algorand Foundation

algokit_utils-2.2.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+algokit_utils/__init__.py,sha256=yeufbE_5wjRILZs_10UD5B3_sjdwAfPXskdFKskzXhg,4963
+algokit_utils/_debugging.py,sha256=4UC5NZGqxF32y742TUB34rX9kWaObXCCPOs-lbkQjGQ,10732
+algokit_utils/_ensure_funded.py,sha256=ZdEdUB43QGIQrg7cSSgNrDmWaLSUhli9x9I6juwKfgo,6786
+algokit_utils/_transfer.py,sha256=CyXGOR_Zy-2crQhk-78uUbB8Sj_ZeTzxPwOAHU7wwno,5947
+algokit_utils/account.py,sha256=UIuOQZe28pQxjEP9TzhtYlOU20tUdzzS-nIIZM9Bp6Y,7364
+algokit_utils/application_client.py,sha256=2EjOPLEur8xsz31nJKzsElm_DEUI3vbts5d4OxjKxfs,58870
+algokit_utils/application_specification.py,sha256=XusOe7VrGPun2UoNspC9Ei202NzPkxRNx5USXiABuXc,7466
+algokit_utils/asset.py,sha256=jsc7T1dH9HZA3Yve2gRLObwUlK6xLDoQz0NxLLnqaGs,7216
+algokit_utils/common.py,sha256=K6-3_9dv2clDn0WMYb8AWE_N46kWWIXglZIPfHIowDs,812
+algokit_utils/config.py,sha256=Ag6Wu2iZDN2CwdmjYA3mJPQ50GInkfXyaWMqb2ZHd6g,4278
+algokit_utils/deploy.py,sha256=ydE3QSq1lRkjXQC9zdFclywx8q1UgV9l-l3Mx-shbHg,34668
+algokit_utils/dispenser_api.py,sha256=BpwEhKDig6qz54wbO-htG8hmLxFIrvdzXpESUb7Y1zw,5584
+algokit_utils/logic_error.py,sha256=bta0YsZF6ggmrspc7tIs0itBOY2jk-AS62EZrKfiHLI,2632
+algokit_utils/models.py,sha256=KynZnM2YbOyTgr2NCT8CA-cYrO0eiyK6u48eeAzj82I,8246
+algokit_utils/network_clients.py,sha256=sj5y_g5uclddWCEyUCptA-KjWuAtLV06hZH4QIGM1yE,5313
+algokit_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+algokit_utils-2.2.0.dist-info/LICENSE,sha256=J5i7U1Q9Q2c7saUzlvFRmrCCFhQyXb5Juz_LO5omNUw,1076
+algokit_utils-2.2.0.dist-info/METADATA,sha256=TeDdZ1Z4Eg2fwYi1sKrAANWoYo0lRpP4TYanIFL45hg,2205
+algokit_utils-2.2.0.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
+algokit_utils-2.2.0.dist-info/RECORD,,

algokit_utils-2.1.2b1.dist-info/RECORD

@@ -1,18 +0,0 @@
-algokit_utils/__init__.py,sha256=NokdZ-V2JKOWipN2TMvcBxgcEKzJ_3F4rSnwsittqC4,4774
-algokit_utils/_ensure_funded.py,sha256=ZdEdUB43QGIQrg7cSSgNrDmWaLSUhli9x9I6juwKfgo,6786
-algokit_utils/_transfer.py,sha256=CyXGOR_Zy-2crQhk-78uUbB8Sj_ZeTzxPwOAHU7wwno,5947
-algokit_utils/account.py,sha256=UIuOQZe28pQxjEP9TzhtYlOU20tUdzzS-nIIZM9Bp6Y,7364
-algokit_utils/application_client.py,sha256=9YH4ecHsn0aXmDeaApraT5WeHaUlN4FPa27QdtN9tew,57878
-algokit_utils/application_specification.py,sha256=XusOe7VrGPun2UoNspC9Ei202NzPkxRNx5USXiABuXc,7466
-algokit_utils/asset.py,sha256=jsc7T1dH9HZA3Yve2gRLObwUlK6xLDoQz0NxLLnqaGs,7216
-algokit_utils/config.py,sha256=V8010eUkbfcoB0bHtxsGQOymq1cqNRc1lDWnwcumQpM,567
-algokit_utils/deploy.py,sha256=klvgxwbS78pOXCLdD0wZB2Q2MSVHOhb66LIs4Nbbt4E,34651
-algokit_utils/dispenser_api.py,sha256=BpwEhKDig6qz54wbO-htG8hmLxFIrvdzXpESUb7Y1zw,5584
-algokit_utils/logic_error.py,sha256=vkLVdxv-XPnwRiIP4CWedgtIZcOPr_5wr7XVH02If9w,2615
-algokit_utils/models.py,sha256=KynZnM2YbOyTgr2NCT8CA-cYrO0eiyK6u48eeAzj82I,8246
-algokit_utils/network_clients.py,sha256=sj5y_g5uclddWCEyUCptA-KjWuAtLV06hZH4QIGM1yE,5313
-algokit_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-algokit_utils-2.1.2b1.dist-info/LICENSE,sha256=J5i7U1Q9Q2c7saUzlvFRmrCCFhQyXb5Juz_LO5omNUw,1076
-algokit_utils-2.1.2b1.dist-info/METADATA,sha256=RRdb7yXQ4J6vR-2WcvmIOETayHq1S9bEJWbVjHHIK2E,2207
-algokit_utils-2.1.2b1.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
-algokit_utils-2.1.2b1.dist-info/RECORD,,