refactor: refining codebase; cleanup for initial beta release

.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",

legacy_v2_tests/test_app_client_call.approvals/test_readonly_call_with_error_with_new_client_missing_source_map.approved.txt

@@ -2,6 +2,6 @@ Txn {txn} had error 'assert failed pc=743' at PC 743:
 
 Could not determine TEAL source line for the error as no approval source map was provided, to receive a trace of the
 error please provide an approval SourceMap. Either by:
-    1. Providing template_values when creating the ApplicationClient, so a SourceMap can be obtained automatically OR
-    2. Set approval_source_map from a previously compiled approval program OR
-    3. Import a previously exported source map using import_source_map
+    1.Providing template_values when creating the ApplicationClient, so a SourceMap can be obtained automatically OR
+    2.Set approval_source_map from a previously compiled approval program OR
+    3.Import a previously exported source map using import_source_map

legacy_v2_tests/test_debug_utils.py

@@ -37,7 +37,7 @@ def client_fixture(algod_client: "AlgodClient", app_spec: ApplicationSpecificati
     return client
 
 
-def test_build_teal_sourcemaps(algod_client: "AlgodClient", tmp_path_factory: pytest.TempPathFactory) -> None:
+def test_legacy_build_teal_sourcemaps(algod_client: "AlgodClient", tmp_path_factory: pytest.TempPathFactory) -> None:
     cwd = tmp_path_factory.mktemp("cwd")
 
     approval = """
@@ -78,7 +78,7 @@ def test_build_teal_sourcemaps(algod_client: "AlgodClient", tmp_path_factory: py
         assert item.location != "dummy"
 
 
-def test_build_teal_sourcemaps_without_sources(
+def test_legacy_build_teal_sourcemaps_without_sources(
     algod_client: "AlgodClient", tmp_path_factory: pytest.TempPathFactory
 ) -> None:
     cwd = tmp_path_factory.mktemp("cwd")
@@ -118,7 +118,7 @@ def test_build_teal_sourcemaps_without_sources(
     check_output_stability(json.dumps(result.to_dict()))
 
 
-def test_simulate_and_persist_response_via_app_call(
+def test_legacy_simulate_and_persist_response_via_app_call(
     tmp_path_factory: pytest.TempPathFactory,
     client_fixture: ApplicationClient,
     mocker: Mock,
@@ -142,7 +142,7 @@ def test_simulate_and_persist_response_via_app_call(
     assert simulated_txn["apid"] == client_fixture.app_id
 
 
-def test_simulate_and_persist_response(
+def test_legacy_simulate_and_persist_response(
     tmp_path_factory: pytest.TempPathFactory, client_fixture: ApplicationClient, mocker: Mock, funded_account: Account
 ) -> None:
     mock_config = mocker.patch("algokit_utils._legacy_v2.application_client.config")

pyproject.toml

@@ -10,11 +10,11 @@ readme = "README.md"
 python = "^3.10"
 py-algorand-sdk = "^2.4.0"
 httpx = "^0.23.1"
-deprecated = "^1.2.14"
+typing-extensions = ">=4.6.0"  # Add this line
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^7.2.0"
-ruff = ">=0.1.6,<=0.8.2"
+ruff = ">=0.1.6,<=0.8.3"
 pip-audit = "^2.5.6"
 pytest-mock = "^3.11.1"
 mypy = "^1.5.1"
@@ -29,7 +29,6 @@ sphinx-rtd-theme = "^1.2.0"
 sphinx-autodoc2 = ">=0.4.2,<0.6.0"
 poethepoet = ">=0.19,<0.26"
 beaker-pyteal = "^1.1.1"
-types-deprecated = "^1.2.9.2"
 pytest-httpx = "^0.21.3"
 pytest-xdist = "^3.4.0"
 sphinx-markdown-builder = "^0.6.6"
@@ -81,7 +80,6 @@ lint.select = [
   "SLF",    # flake8-self
   "SIM",    # flake8-simplify
   "TID",    # flake8-tidy-imports
-  "TCH",    # flake8-type-checking
   "ARG",    # flake8-unused-arguments
   "PTH",    # flake8-use-pathlib
   "ERA",    # eradicate
@@ -131,12 +129,12 @@ 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"]
 docs-md-only = "sphinx-build docs/source docs/markdown -b markdown"
 docs-html-only = "sphinx-build docs/source docs/html"
-"tests/**/*" = ["PLR2004"]  
 
 [tool.pytest.ini_options]
 pythonpath = ["src", "tests"]

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,
@@ -54,7 +96,6 @@
     get_creator_apps,
     replace_template_variables,
 )
-from algokit_utils._legacy_v2.logic_error import LogicError
 from algokit_utils._legacy_v2.models import (
     ABIArgsDict,
     ABIMethod,
@@ -81,55 +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.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 ====
 ]