refactor: remaining batch of refactoring efforts; improving project s…

…tructure

.gitignore

@@ -170,3 +170,6 @@ cython_debug/
 /docs/source/apidocs
 
 !docs/html
+
+# Received approval test files
+*.received.*

.vscode/launch.json

@@ -1,6 +1,13 @@
 {
     "version": "0.2.0",
     "configurations": [
+        {
+            "name": "Python Debugger: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal"
+        },
         {
             "name": "Python: Debug Tests",
             "type": "debugpy",

pyproject.toml

@@ -41,7 +41,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.ruff]
 line-length = 120
-select = [
+lint.select = [
   # all possible codes as of this ruff version are listed here,
   # ones we don't want/need are commented out to make it clear
   # which have been omitted on purpose vs which ones get added
@@ -129,6 +129,7 @@ suppress-none-returning = true
 "tests/clients/test_algorand_client.py" = ["ERA001"]  
 "src/algokit_utils/_legacy_v2/**/*" = ["E501"]
 "tests/**/*" = ["PLR2004"]  
+"src/algokit_utils/__init__.py" = ["I001", "RUF022"]  # Ignore import sorting for __init__.py
 
 [tool.poe.tasks]
 docs = ["docs-html-only", "docs-md-only"]

src/algokit_utils/__init__.py

@@ -1,6 +1,48 @@
-from algokit_utils._debugging import PersistSourceMapInput, persist_sourcemaps, simulate_and_persist_response
-from algokit_utils._legacy_v2._ensure_funded import EnsureBalanceParameters, EnsureFundedResponse, ensure_funded
-from algokit_utils._legacy_v2._transfer import TransferAssetParameters, TransferParameters, transfer, transfer_asset
+"""AlgoKit Python Utilities - a set of utilities for building solutions on Algorand
+
+This module provides commonly used utilities and types at the root level for convenience.
+For more specific functionality, import directly from the relevant submodules:
+
+    from algokit_utils.accounts import KmdAccountManager
+    from algokit_utils.applications import AppClient
+    from algokit_utils.applications.app_spec import Arc52Contract
+    etc.
+"""
+
+# Core types and utilities that are commonly used
+from algokit_utils.models.account import Account
+from algokit_utils.applications.app_manager import DELETABLE_TEMPLATE_NAME, UPDATABLE_TEMPLATE_NAME
+from algokit_utils.errors.logic_error import LogicError
+from algokit_utils.clients.algorand_client import AlgorandClient
+
+# Common managers/clients that are frequently used entry points
+from algokit_utils.accounts.account_manager import AccountManager
+from algokit_utils.applications.app_client import AppClient
+from algokit_utils.applications.app_factory import AppFactory
+from algokit_utils.assets.asset_manager import AssetManager
+from algokit_utils.clients.client_manager import ClientManager
+from algokit_utils.transactions.transaction_composer import TransactionComposer
+
+# Commonly used constants
+from algokit_utils.clients.dispenser_api_client import (
+    DISPENSER_ACCESS_TOKEN_KEY,
+    TestNetDispenserApiClient,
+    DISPENSER_REQUEST_TIMEOUT,
+)
+
+# ==== LEGACY V2 SUPPORT BEGIN ====
+# These imports are maintained for backwards compatibility
+from algokit_utils._legacy_v2._ensure_funded import (
+    EnsureBalanceParameters,
+    EnsureFundedResponse,
+    ensure_funded,
+)
+from algokit_utils._legacy_v2._transfer import (
+    TransferAssetParameters,
+    TransferParameters,
+    transfer,
+    transfer_asset,
+)
 from algokit_utils._legacy_v2.account import (
     create_kmd_wallet_account,
     get_account,
@@ -80,56 +122,51 @@
     is_mainnet,
     is_testnet,
 )
+# ==== LEGACY V2 SUPPORT END ====
 
-# New interfaces
-from algokit_utils.accounts.account_manager import AccountManager
-from algokit_utils.accounts.kmd_account_manager import KmdAccountManager
-from algokit_utils.applications.app_client import AppClient
-from algokit_utils.applications.app_factory import AppFactory
-from algokit_utils.assets.asset_manager import AssetManager
-from algokit_utils.clients.algorand_client import AlgorandClient
-from algokit_utils.clients.client_manager import ClientManager
-from algokit_utils.clients.dispenser_api_client import (
-    DISPENSER_ACCESS_TOKEN_KEY,
-    DISPENSER_REQUEST_TIMEOUT,
-    DispenserFundResponse,
-    DispenserLimitResponse,
-    TestNetDispenserApiClient,
+# Debugging utilities
+from algokit_utils._debugging import (
+    PersistSourceMapInput,
+    persist_sourcemaps,
+    simulate_and_persist_response,
 )
-from algokit_utils.errors.logic_error import LogicError
-from algokit_utils.models.account import Account
-from algokit_utils.models.application import DELETABLE_TEMPLATE_NAME, UPDATABLE_TEMPLATE_NAME
-from algokit_utils.transactions.transaction_composer import TransactionComposer
 
 __all__ = [
+    # Core types and utilities
+    "Account",
+    "LogicError",
+    "AlgorandClient",
     "DELETABLE_TEMPLATE_NAME",
+    "UPDATABLE_TEMPLATE_NAME",
+    # Common managers/clients
+    "AccountManager",
+    "AppClient",
+    "AppFactory",
+    "AssetManager",
+    "ClientManager",
+    "TransactionComposer",
+    "TestNetDispenserApiClient",
+    # Constants
     "DISPENSER_ACCESS_TOKEN_KEY",
     "DISPENSER_REQUEST_TIMEOUT",
     "NOTE_PREFIX",
-    "UPDATABLE_TEMPLATE_NAME",
+    # Legacy v2 exports - maintained for backwards compatibility
     "ABIArgsDict",
     "ABICallArgs",
     "ABICallArgsDict",
     "ABICreateCallArgs",
     "ABICreateCallArgsDict",
     "ABIMethod",
     "ABITransactionResponse",
-    "Account",
-    "AccountManager",
     "AlgoClientConfig",
-    "AlgorandClient",
-    "AppClient",
     "AppDeployMetaData",
-    "AppFactory",
     "AppLookup",
     "AppMetaData",
     "AppReference",
     "AppSpecStateDict",
     "ApplicationClient",
     "ApplicationSpecification",
-    "AssetManager",
     "CallConfig",
-    "ClientManager",
     "CommonCallParameters",
     "CommonCallParametersDict",
     "CreateCallParameters",
@@ -143,12 +180,8 @@
     "DeployCreateCallArgsDict",
     "DeployResponse",
     "DeploymentFailedError",
-    "DispenserFundResponse",
-    "DispenserLimitResponse",
     "EnsureBalanceParameters",
     "EnsureFundedResponse",
-    "KmdAccountManager",
-    "LogicError",
     "MethodConfigDict",
     "MethodHints",
     "OnCompleteActionName",
@@ -161,14 +194,12 @@
     "Program",
     "TemplateValueDict",
     "TemplateValueMapping",
-    "TestNetDispenserApiClient",
-    "TransactionComposer",
     "TransactionParameters",
     "TransactionParametersDict",
     "TransactionResponse",
     "TransferAssetParameters",
     "TransferParameters",
-    # ==== LEGACY V2 EXPORTS BEGIN ====
+    # Legacy v2 functions
     "create_kmd_wallet_account",
     "ensure_funded",
     "execute_atc_with_logic_error",
@@ -198,5 +229,4 @@
     "simulate_and_persist_response",
     "transfer",
     "transfer_asset",
-    # ==== LEGACY V2 EXPORTS END ====
 ]

src/algokit_utils/_debugging.py

@@ -229,7 +229,7 @@ def simulate_response(
     allow_unnamed_resources: bool | None = None,
     extra_opcode_budget: int | None = None,
     exec_trace_config: SimulateTraceConfig | None = None,
-    round: int | None = None,  # noqa: A002 TODO: revisit
+    simulation_round: int | None = None,
     skip_signatures: int | None = None,  # noqa: ARG001 TODO: revisit
 ) -> SimulateAtomicTransactionResponse:
     """
@@ -253,7 +253,7 @@ def simulate_response(
     simulate_request = SimulateRequest(
         txn_groups=txn_group,
         allow_more_logs=allow_more_logs or True,
-        round=round,
+        round=simulation_round,
         extra_opcode_budget=extra_opcode_budget or 0,
         allow_unnamed_resources=allow_unnamed_resources or True,
         allow_empty_signatures=allow_empty_signatures or True,
@@ -273,7 +273,7 @@ def simulate_and_persist_response(  # noqa: PLR0913
     allow_unnamed_resources: bool | None = None,
     extra_opcode_budget: int | None = None,
     exec_trace_config: SimulateTraceConfig | None = None,
-    round: int | None = None,  # noqa: A002
+    simulation_round: int | None = None,
     skip_signatures: int | None = None,
 ) -> SimulateAtomicTransactionResponse:
     """
@@ -307,7 +307,7 @@ def simulate_and_persist_response(  # noqa: PLR0913
         allow_unnamed_resources,
         extra_opcode_budget,
         exec_trace_config,
-        round,
+        simulation_round,
         skip_signatures,
     )
     txn_results = response.simulate_response["txn-groups"]

src/algokit_utils/accounts/__init__.py

@@ -0,0 +1,2 @@
+from algokit_utils.accounts.account_manager import *  # noqa: F403
+from algokit_utils.accounts.kmd_account_manager import *  # noqa: F403

src/algokit_utils/accounts/account_manager.py

@@ -15,11 +15,12 @@
 from algokit_utils.config import config
 from algokit_utils.models.account import DISPENSER_ACCOUNT_NAME, Account, MultiSigAccount, MultisigMetadata
 from algokit_utils.models.amount import AlgoAmount
-from algokit_utils.models.transaction import SendAtomicTransactionComposerResults, SendSingleTransactionResult
 from algokit_utils.transactions.transaction_composer import (
     PaymentParams,
+    SendAtomicTransactionComposerResults,
     TransactionComposer,
 )
+from algokit_utils.transactions.transaction_sender import SendSingleTransactionResult
 
 logger = config.logger
 

src/algokit_utils/accounts/kmd_account_manager.py

@@ -9,6 +9,8 @@
 from algokit_utils.models.amount import AlgoAmount
 from algokit_utils.transactions.transaction_composer import PaymentParams, TransactionComposer
 
+__all__ = ["KmdAccount", "KmdAccountManager"]
+
 logger = config.logger
 
 

src/algokit_utils/applications/__init__.py

@@ -0,0 +1,5 @@
+from algokit_utils.applications.app_client import *  # noqa: F403
+from algokit_utils.applications.app_deployer import *  # noqa: F403
+from algokit_utils.applications.app_factory import *  # noqa: F403
+from algokit_utils.applications.app_manager import *  # noqa: F403
+from algokit_utils.applications.app_spec import *  # noqa: F403