refactor: moving implementation into private namespace; refining docs; configuring api docs

docs/api.md

@@ -1,14 +1,31 @@
 # API Reference
 
-```{autodoc2-summary}
-:renderer: myst
+## Contexts
 
+```{autodoc2-summary}
 algopy_testing.AlgopyTestContext
 algopy_testing.LedgerContext
 algopy_testing.TransactionContext
+```
+
+## Value Generators
+
+```{autodoc2-summary}
 algopy_testing.AVMValueGenerator
-algopy_testing.TxnValueGenerator
 algopy_testing.ARC4ValueGenerator
+algopy_testing.TxnValueGenerator
 ```
 
-> TODO: 1.0 Restructure algopy_testing index file once refactoring changes are merged
+## Inner transaction loaders
+
+```{autodoc2-summary}
+algopy_testing.ITxnGroupLoader
+algopy_testing.ITxnLoader
+```
+
+## Utils
+
+```{autodoc2-summary}
+algopy_testing.algopy_testing_context
+algopy_testing.arc4_prefix
+```

docs/conf.py

@@ -61,7 +61,11 @@
 autodoc2_packages = [
     {
         "path": "../src/algopy_testing",
-        "auto_mode": False,
+        "auto_mode": True,
+    },
+    {
+        "path": "../src/_algopy_testing",
+        "auto_mode": True,
     },
 ]
 autodoc2_render_plugin = "myst"

docs/coverage.md

@@ -1,8 +1,6 @@
 # Coverage
 
-See which `algorand-python` stubs are implemented by the `algorand-python-testing` library. See the [Concepts](testing-guide/concepts.md#types-of-algopy-stub-implementations) section for more details on the implementation categories.
-
-Based on the definitions provided and the implementation details in the `src` directory, here is the classification for the abstractions outlined in the table under the `Name` column:
+See which `algorand-python` stubs are implemented by the `algorand-python-testing` library. See the [Concepts](testing-guide/concepts.md#types-of-algopy-stub-implementations) section for more details on the implementation categories. Refer to the [`algorand-python` stubs API](api.md) for the full list of the stubs for which the `algorand-python-testing` library provides implementations referenced in the table below.
 
 | Name                                        | Implementation type |
 | ------------------------------------------- | ------------------- |
@@ -159,4 +157,3 @@ Based on the definitions provided and the implementation details in the `src` di
 | algopy.op.EllipticCurve                     | Mockable            |
 | algopy.op.VrfVerify                         | Mockable            |
 | algopy.op.vrf_verify                        | Mockable            |
-

examples/zk_whitelist/test_contract.py

@@ -3,8 +3,7 @@
 
 import algopy
 import pytest
-from algopy_testing import AlgopyTestContext, algopy_testing_context
-from algopy_testing.utils import arc4_prefix
+from algopy_testing import AlgopyTestContext, algopy_testing_context, arc4_prefix
 
 from .contract import ZkWhitelistContract
 

src/_algopy_testing/__init__.py

@@ -0,0 +1,68 @@
+from _algopy_testing import arc4, gtxn, itxn
+from _algopy_testing._context_helpers.context_storage import algopy_testing_context
+from _algopy_testing._context_helpers.ledger_context import LedgerContext
+from _algopy_testing._context_helpers.txn_context import TransactionContext
+from _algopy_testing._itxn_loader import ITxnGroupLoader, ITxnLoader
+from _algopy_testing._value_generators.arc4 import ARC4ValueGenerator
+from _algopy_testing._value_generators.avm import AVMValueGenerator
+from _algopy_testing._value_generators.txn import TxnValueGenerator
+from _algopy_testing.context import AlgopyTestContext
+from _algopy_testing.decorators.subroutine import subroutine
+from _algopy_testing.enums import OnCompleteAction, TransactionType
+from _algopy_testing.models import (
+    Account,
+    Application,
+    ARC4Contract,
+    Asset,
+    Contract,
+    LogicSig,
+    StateTotals,
+    TemplateVar,
+    logicsig,
+    uenumerate,
+    urange,
+)
+from _algopy_testing.primitives import BigUInt, Bytes, String, UInt64
+from _algopy_testing.state import Box, BoxMap, BoxRef, GlobalState, LocalState
+
+# TODO: clean up and ensure only algopy_testing namespace specific user facing abstractions
+# are exposed Only keep the _value_generators, ledger_context, txn_context,
+# context, and arc4_prexif from utils (make utils private)
+__all__ = [
+    "ARC4Contract",
+    "ARC4ValueGenerator",
+    "Account",
+    "AlgopyTestContext",
+    "Application",
+    "Asset",
+    "BigUInt",
+    "Box",
+    "BoxMap",
+    "BoxRef",
+    "Bytes",
+    "Contract",
+    "GlobalState",
+    "LocalState",
+    "LogicSig",
+    "ITxnLoader",
+    "TxnValueGenerator",
+    "ITxnGroupLoader",
+    "OnCompleteAction",
+    "StateTotals",
+    "String",
+    "TemplateVar",
+    "LedgerContext",
+    "TransactionContext",
+    "AVMValueGenerator",
+    "TxnValueGenerator",
+    "TransactionType",
+    "UInt64",
+    "algopy_testing_context",
+    "arc4",
+    "gtxn",
+    "itxn",
+    "logicsig",
+    "subroutine",
+    "uenumerate",
+    "urange",
+]

src/algopy_testing/_compiled.py → src/_algopy_testing/_compiled.py

@@ -4,7 +4,7 @@
 import dataclasses
 import typing
 
-from algopy_testing.utils import raise_mocked_function_error
+from _algopy_testing.utils import raise_mocked_function_error
 
 if typing.TYPE_CHECKING:
     from collections.abc import Mapping

src/_algopy_testing/_context_helpers/__init__.py

@@ -0,0 +1,13 @@
+from _algopy_testing._context_helpers.context_storage import (
+    algopy_testing_context,
+    lazy_context,
+)
+from _algopy_testing._context_helpers.ledger_context import LedgerContext
+from _algopy_testing._context_helpers.txn_context import TransactionContext
+
+__all__ = [
+    "LedgerContext",
+    "TransactionContext",
+    "algopy_testing_context",
+    "lazy_context",
+]

src/algopy_testing/_context_helpers/context_storage.py → src/_algopy_testing/_context_helpers/context_storage.py

@@ -9,13 +9,13 @@
 
     import algopy
 
-    from algopy_testing._context_helpers.ledger_context import LedgerContext
-    from algopy_testing._context_helpers.txn_context import TransactionContext, TransactionGroup
-    from algopy_testing._value_generators import AlgopyValueGenerator
-    from algopy_testing.context import AlgopyTestContext
-    from algopy_testing.models.account import AccountContextData
-    from algopy_testing.models.application import ApplicationContextData
-    from algopy_testing.models.asset import AssetFields
+    from _algopy_testing._context_helpers.ledger_context import LedgerContext
+    from _algopy_testing._context_helpers.txn_context import TransactionContext, TransactionGroup
+    from _algopy_testing._value_generators import AlgopyValueGenerator
+    from _algopy_testing.context import AlgopyTestContext
+    from _algopy_testing.models.account import AccountContextData
+    from _algopy_testing.models.application import ApplicationContextData
+    from _algopy_testing.models.asset import AssetFields
 
 _var: ContextVar[AlgopyTestContext] = ContextVar("_var")
 
@@ -97,7 +97,12 @@ def algopy_testing_context(
     *,
     default_sender: str | None = None,
 ) -> Generator[AlgopyTestContext, None, None]:
-    from algopy_testing.context import AlgopyTestContext
+    """Context manager for the AlgopyTestContext.
+
+    Args:
+        default_sender: The default sender for the context.
+    """
+    from _algopy_testing.context import AlgopyTestContext
 
     token = _var.set(
         AlgopyTestContext(

src/algopy_testing/_context_helpers/ledger_context.py → src/_algopy_testing/_context_helpers/ledger_context.py

@@ -3,25 +3,25 @@
 import typing
 from collections import defaultdict
 
-from algopy_testing.constants import MAX_BOX_SIZE
-from algopy_testing.models.account import Account
-from algopy_testing.primitives.uint64 import UInt64
-from algopy_testing.utils import as_bytes, assert_address_is_valid, get_default_global_fields
+from _algopy_testing.constants import MAX_BOX_SIZE
+from _algopy_testing.models.account import Account
+from _algopy_testing.primitives.uint64 import UInt64
+from _algopy_testing.utils import as_bytes, assert_address_is_valid, get_default_global_fields
 
 if typing.TYPE_CHECKING:
     import algopy
 
-    from algopy_testing.models.account import AccountFields
-    from algopy_testing.models.application import ApplicationContextData, ApplicationFields
-    from algopy_testing.models.asset import AssetFields
-    from algopy_testing.op.global_values import GlobalFields
+    from _algopy_testing.models.account import AccountFields
+    from _algopy_testing.models.application import ApplicationContextData, ApplicationFields
+    from _algopy_testing.models.asset import AssetFields
+    from _algopy_testing.op.global_values import GlobalFields
 
 
 class LedgerContext:
     """Context for managing the ledger state."""
 
     def __init__(self) -> None:
-        from algopy_testing.models.account import AccountContextData, get_empty_account
+        from _algopy_testing.models.account import AccountContextData, get_empty_account
 
         self.account_data = defaultdict[str, AccountContextData](get_empty_account)
         self.app_data: dict[int, ApplicationContextData] = {}
@@ -374,7 +374,7 @@ def patch_global_fields(self, **global_fields: typing.Unpack[GlobalFields]) -> N
         Raises:
             AttributeError: If invalid fields are provided.
         """
-        from algopy_testing.op.global_values import GlobalFields
+        from _algopy_testing.op.global_values import GlobalFields
 
         invalid_keys = global_fields.keys() - GlobalFields.__annotations__.keys()
 
@@ -436,8 +436,8 @@ def _get_app_id(app: algopy.UInt64 | algopy.Application | algopy.Contract | int)
     Raises:
         TypeError: If an invalid type is provided.
     """
-    from algopy_testing.models import Application, Contract
-    from algopy_testing.primitives import UInt64
+    from _algopy_testing.models import Application, Contract
+    from _algopy_testing.primitives import UInt64
 
     if isinstance(app, Contract):
         app_id = app.__app_id__

src/algopy_testing/_context_helpers/txn_context.py → src/_algopy_testing/_context_helpers/txn_context.py

@@ -5,30 +5,30 @@
 
 import algosdk
 
-from algopy_testing._itxn_loader import ITxnGroupLoader
-from algopy_testing.decorators.arc4 import (
+from _algopy_testing._itxn_loader import ITxnGroupLoader
+from _algopy_testing.decorators.arc4 import (
     check_routing_conditions,
     create_abimethod_txns,
     create_baremethod_txns,
     get_arc4_metadata,
     get_ordered_args,
 )
-from algopy_testing.enums import OnCompleteAction
+from _algopy_testing.enums import OnCompleteAction
 
 if typing.TYPE_CHECKING:
     from collections.abc import Callable, Iterator, Sequence
 
     import algopy
 
-    from algopy_testing._itxn_loader import InnerTransactionResultType
-    from algopy_testing.models.txn_fields import ActiveTransactionFields
+    from _algopy_testing._itxn_loader import InnerTransactionResultType
+    from _algopy_testing.models.txn_fields import ActiveTransactionFields
 
-from algopy_testing import gtxn
-from algopy_testing._itxn_loader import ITxnLoader
-from algopy_testing.gtxn import TransactionBase
-from algopy_testing.itxn import InnerTransaction, submit_txns
-from algopy_testing.models import Application
-from algopy_testing.primitives import UInt64
+from _algopy_testing import gtxn
+from _algopy_testing._itxn_loader import ITxnLoader
+from _algopy_testing.gtxn import TransactionBase
+from _algopy_testing.itxn import InnerTransaction, submit_txns
+from _algopy_testing.models import Application
+from _algopy_testing.primitives import UInt64
 
 TReturn = typing.TypeVar("TReturn")
 TParamSpec = typing.ParamSpec("TParamSpec")
@@ -56,6 +56,8 @@ def submit(self) -> TReturn:
 
 
 class TransactionContext:
+    """Context for managing transaction groups and active transactions."""
+
     def __init__(self) -> None:
         self._groups: list[TransactionGroup] = []
         self._active_group: TransactionGroup | None = None
@@ -91,7 +93,7 @@ def defer_app_call(
     ) -> DeferredAppCall[TReturn]:
         r"""Prepare an application call transaction group for a contract method without
         executing it."""
-        from algopy_testing.models import ARC4Contract
+        from _algopy_testing.models import ARC4Contract
 
         arc4_metadata = get_arc4_metadata(method)
         # unwrap instance method

src/algopy_testing/_itxn_loader.py → src/_algopy_testing/_itxn_loader.py

@@ -2,8 +2,8 @@
 
 import typing
 
-from algopy_testing import itxn
-from algopy_testing.enums import TransactionType
+from _algopy_testing import itxn
+from _algopy_testing.enums import TransactionType
 
 if typing.TYPE_CHECKING:
     from collections.abc import Sequence

src/algopy_testing/_value_generators/arc4.py → src/_algopy_testing/_value_generators/arc4.py

@@ -6,9 +6,9 @@
 
 import algosdk
 
-from algopy_testing import arc4
-from algopy_testing.constants import MAX_UINT8, MAX_UINT16, MAX_UINT32, MAX_UINT64, MAX_UINT512
-from algopy_testing.utils import generate_random_int
+from _algopy_testing import arc4
+from _algopy_testing.constants import MAX_UINT8, MAX_UINT16, MAX_UINT32, MAX_UINT64, MAX_UINT512
+from _algopy_testing.utils import generate_random_int
 
 if typing.TYPE_CHECKING:
     import algopy