docs: integrating pydoclint; formatting docs; removing docs from stub…

… implementation

.gitignore

@@ -15,3 +15,5 @@ examples/**/*.trace
 .coverage
 coverage.xml
 .venv*
+
+.cursorignore

pyproject.toml

@@ -72,6 +72,7 @@ validate_examples = "python scripts/validate_examples.py"
 check_stubs_cov = "python scripts/check_stubs_cov.py"
 pre_commit = [
     "hatch run lint:fix",
+    "hatch run lint:check",
     "mypy_testing",
     "hatch run examples:pre_commit",
 ]
@@ -97,15 +98,17 @@ dependencies = [
     "ruff==0.5.6",
     "ruff-lsp",
     "docformatter",
+    "pydoclint",
 ]
 
 [tool.hatch.envs.lint.scripts]
 check = [
   "black --check .",
   "ruff check",
+  "pydoclint --config=pyproject.toml src",
 ]
 fix = [
-  "docformatter -i -r src",
+  "docformatter -i -r --black --style sphinx src",
   "black .",
   "ruff check --fix",
 ]
@@ -315,3 +318,12 @@ upload_to_vcs_release = true
 
 [tool.semantic_release.remote.token]
 env = "GITHUB_TOKEN"
+
+[tool.pydoclint]
+style = 'sphinx'
+check-return-types = 'False'
+skip-checking-raises = 'True'
+arg-type-hints-in-docstring = 'False'
+
+[tool.docformatter]
+style = "sphinx"

src/algopy_testing/_context_helpers/context_storage.py

@@ -21,9 +21,9 @@
 
 
 class _InternalContext:
-    """For accessing implementation specific functions, with a convenient
-    single entry point for other modules to import Also allows for a single
-    place to check and provide."""
+    """For accessing implementation specific functions, with a convenient single entry
+    point for other modules to import Also allows for a single place to check and
+    provide."""
 
     @property
     def value(self) -> AlgopyTestContext:

src/algopy_testing/_context_helpers/txn_context.py

@@ -87,16 +87,8 @@ def defer_app_call(
         *args: TParamSpec.args,
         **kwargs: TParamSpec.kwargs,
     ) -> DeferredAppCall[TReturn]:
-        """Prepare an application call transaction group for a contract method
-        without executing it.
-
-        :param method: The decorated contract method (baremethod or
-            abimethod).
-        :param args: Positional arguments for the method.
-        :param kwargs: Keyword arguments for the method.
-        :return: A DeferredAppCall object containing the transaction
-            group and method info.
-        """
+        r"""Prepare an application call transaction group for a contract method without
+        executing it."""
         from algopy_testing.models import ARC4Contract
 
         arc4_metadata = get_arc4_metadata(method)
@@ -119,7 +111,7 @@ def defer_app_call(
         app_id = contract.__app_id__
         # Handle ABI methods
         if arc4_metadata.arc4_signature:
-            ordered_args = get_ordered_args(fn, args, kwargs)  # type: ignore[arg-type]
+            ordered_args = get_ordered_args(fn, args, kwargs)
             txns = create_abimethod_txns(
                 app_id=app_id,
                 arc4_signature=arc4_metadata.arc4_signature,
@@ -140,20 +132,13 @@ def create_group(
         active_txn_index: int | None = None,
         txn_op_fields: TransactionBaseFields | None = None,
     ) -> Iterator[None]:
-        """Adds a new transaction group using a list of transactions and an
-        optional index to indicate the active transaction within the group.
-
-        :param gtxns: List of transactions.
-        :type gtxns: list[algopy.gtxn.TransactionBase]
-        :param active_txn_index: Index of the active transaction.
-        :type active_txn_index: int
-        :param active_txn_index: Index of the active transaction.
-            Defaults to None.
-        :type active_txn_index: int
-        :param gtxn: list[algopy.gtxn.TransactionBase]:
-        :param active_txn_index: int | None: (Default value = None)
-        :param txn_op_fields: dict[str, typing.Any] | None: (Default
-            value = None)
+        """Adds a new transaction group using a list of transactions and an optional
+        index to indicate the active transaction within the group.
+
+        :param gtxns: List of transactions
+        :param active_txn_index: Index of the active transaction
+        :param txn_op_fields: Additional transaction operation fields
+        :return: None
         """
 
         processed_gtxns = []
@@ -291,12 +276,10 @@ def get_scratch_slot(
         self,
         index: algopy.UInt64 | int,
     ) -> algopy.UInt64 | algopy.Bytes:
-        """Retrieves the scratch values for a specific slot in the active
-        transaction.
+        """Retrieves the scratch values for a specific slot in the active transaction.
 
-        :param index: algopy.UInt64 | int: Which scratch slot to query
-        :returns: Scratch slot value for the active transaction.
-        :rtype: algopy.UInt64 | algopy.Bytes
+        :param index: Which scratch slot to query
+        :return: Scratch slot value for the active transaction
         """
         # this wraps an internal method on TransactionBase, so it can be exposed to
         # consumers of algopy_testing
@@ -307,8 +290,8 @@ def get_scratch_space(
     ) -> Sequence[algopy.Bytes | algopy.UInt64]:
         """Retrieves scratch space for the active transaction.
 
-        :returns: List of scratch space values for the active
-            transaction.
+        :return: List of scratch space values for the active transaction
+        :rtype: Sequence[algopy.Bytes | algopy.UInt64]
         """
         return self._active_txn.get_scratch_space()
 

src/algopy_testing/_itxn_loader.py

@@ -24,12 +24,12 @@
 
 
 class ITxnLoader:
-    """A helper class for handling access to individual inner transactions in
-    test context.
+    """A helper class for handling access to individual inner transactions in test
+    context.
 
-    This class provides methods to access and retrieve specific types of
-    inner transactions. It performs type checking and conversion for
-    various transaction types.
+    This class provides methods to access and retrieve specific types of inner
+    transactions. It performs type checking and conversion for various transaction
+    types.
     """
 
     _TXN_TYPE_MAP: typing.ClassVar = {
@@ -57,74 +57,66 @@ def _get_itxn(self, txn_type: type[_T]) -> _T:
     def payment(self) -> algopy.itxn.PaymentInnerTransaction:
         """Retrieve the last PaymentInnerTransaction.
 
-        :raises ValueError: If the transaction is not found or not of
-            the expected type.
+        :raises ValueError: If the transaction is not found or not of the expected type.
         """
         return self._get_itxn(itxn.PaymentInnerTransaction)
 
     @property
     def asset_config(self) -> algopy.itxn.AssetConfigInnerTransaction:
         """Retrieve the last AssetConfigInnerTransaction.
 
-        :raises ValueError: If the transaction is not found or not of
-            the expected type.
+        :raises ValueError: If the transaction is not found or not of the expected type.
         """
         return self._get_itxn(itxn.AssetConfigInnerTransaction)
 
     @property
     def asset_transfer(self) -> algopy.itxn.AssetTransferInnerTransaction:
         """Retrieve the last AssetTransferInnerTransaction.
 
-        :raises ValueError: If the transaction is not found or not of
-            the expected type.
+        :raises ValueError: If the transaction is not found or not of the expected type.
         """
         return self._get_itxn(itxn.AssetTransferInnerTransaction)
 
     @property
     def asset_freeze(self) -> algopy.itxn.AssetFreezeInnerTransaction:
         """Retrieve the last AssetFreezeInnerTransaction.
 
-        :raises ValueError: If the transaction is not found or not of
-            the expected type.
+        :raises ValueError: If the transaction is not found or not of the expected type.
         """
         return self._get_itxn(itxn.AssetFreezeInnerTransaction)
 
     @property
     def application_call(self) -> algopy.itxn.ApplicationCallInnerTransaction:
         """Retrieve the last ApplicationCallInnerTransaction.
 
-        :raises ValueError: If the transaction is not found or not of
-            the expected type.
+        :raises ValueError: If the transaction is not found or not of the expected type.
         """
         return self._get_itxn(itxn.ApplicationCallInnerTransaction)
 
     @property
     def key_registration(self) -> algopy.itxn.KeyRegistrationInnerTransaction:
         """Retrieve the last KeyRegistrationInnerTransaction.
 
-        :raises ValueError: If the transaction is not found or not of
-            the expected type.
+        :raises ValueError: If the transaction is not found or not of the expected type.
         """
         return self._get_itxn(itxn.KeyRegistrationInnerTransaction)
 
     @property
     def transaction(self) -> algopy.itxn.InnerTransactionResult:
         """Retrieve the last InnerTransactionResult.
 
-        :raises ValueError: If the transaction is not found or not of
-            the expected type.
+        :raises ValueError: If the transaction is not found or not of the expected type.
         """
         return self._get_itxn(itxn.InnerTransactionResult)
 
 
 class ITxnGroupLoader:
-    """A helper class for handling access to groups of inner transactions in
-    test context.
+    """A helper class for handling access to groups of inner transactions in test
+    context.
 
-    This class provides methods to access and retrieve inner
-    transactions from a group, either individually or as slices. It
-    supports type-specific retrieval of inner transactions and
-    implements indexing operations.
+    This class provides methods to access and retrieve inner transactions from a group,
+    either individually or as slices. It supports type-specific retrieval of inner
+    transactions and implements indexing operations.
     """
 
     @typing.overload
@@ -157,74 +149,57 @@ def _get_itxn(self, index: int) -> InnerTransactionResultType:
     def payment(self, index: int) -> algopy.itxn.PaymentInnerTransaction:
         """Return a PaymentInnerTransaction from the group at the given index.
 
-        :param index: int
-        :param index: int:
-        :returns: algopy.itxn.PaymentInnerTransaction: The
-            PaymentInnerTransaction at the given index.
+        :param index: The index of the transaction in the group.
+        :returns: The PaymentInnerTransaction at the given index.
+        :raises TypeError: If the transaction is not found or not of
         """
         return ITxnLoader(self._get_itxn(index)).payment
 
     def asset_config(self, index: int) -> algopy.itxn.AssetConfigInnerTransaction:
-        """Return an AssetConfigInnerTransaction from the group at the given
-        index.
+        """Return an AssetConfigInnerTransaction from the group at the given index.
 
-        :param index: int
-        :param index: int:
-        :returns: algopy.itxn.AssetConfigInnerTransaction: The
-            AssetConfigInnerTransaction at the given index.
+        :param index: The index of the transaction in the group.
+        :returns: The AssetConfigInnerTransaction at the given index.
+        :raises TypeError: If the transaction is not found or not of the expected type.
         """
         return ITxnLoader(self._get_itxn(index)).asset_config
 
     def asset_transfer(self, index: int) -> algopy.itxn.AssetTransferInnerTransaction:
-        """Return an AssetTransferInnerTransaction from the group at the given
-        index.
+        """Return an AssetTransferInnerTransaction from the group at the given index.
 
-        :param index: int
-        :param index: int:
-        :returns: algopy.itxn.AssetTransferInnerTransaction: The
-            AssetTransferInnerTransaction at the given index.
+        :param index: The index of the transaction in the group.
+        :returns: The AssetTransferInnerTransaction at the given index.
         """
         return ITxnLoader(self._get_itxn(index)).asset_transfer
 
     def asset_freeze(self, index: int) -> algopy.itxn.AssetFreezeInnerTransaction:
-        """Return an AssetFreezeInnerTransaction from the group at the given
-        index.
+        """Return an AssetFreezeInnerTransaction from the group at the given index.
 
-        :param index: int
-        :param index: int:
-        :returns: algopy.itxn.AssetFreezeInnerTransaction: The
-            AssetFreezeInnerTransaction at the given index.
+        :param index: The index of the transaction in the group.
+        :returns: The AssetFreezeInnerTransaction at the given index.
         """
         return ITxnLoader(self._get_itxn(index)).asset_freeze
 
     def application_call(self, index: int) -> algopy.itxn.ApplicationCallInnerTransaction:
-        """Return an ApplicationCallInnerTransaction from the group at the
-        given index.
+        """Return an ApplicationCallInnerTransaction from the group at the given index.
 
-        :param index: int
-        :param index: int:
-        :returns: algopy.itxn.ApplicationCallInnerTransaction: The
-            ApplicationCallInnerTransaction at the given index.
+        :param index: The index of the transaction in the group.
+        :returns: The ApplicationCallInnerTransaction at the given index.
         """
         return ITxnLoader(self._get_itxn(index)).application_call
 
     def key_registration(self, index: int) -> algopy.itxn.KeyRegistrationInnerTransaction:
-        """Return a KeyRegistrationInnerTransaction from the group at the given
-        index.
+        """Return a KeyRegistrationInnerTransaction from the group at the given index.
 
-        :param index: int
-        :param index: int:
-        :returns: algopy.itxn.KeyRegistrationInnerTransaction: The
-            KeyRegistrationInnerTransaction at the given index.
+        :param index: The index of the transaction in the group.
+        :returns: The KeyRegistrationInnerTransaction at the given index.
         """
         return ITxnLoader(self._get_itxn(index)).key_registration
 
     def transaction(self, index: int) -> algopy.itxn.InnerTransactionResult:
         """Return an InnerTransactionResult from the group at the given index.
 
-        :param index: int
-        :param index: int:
-        :returns: algopy.itxn.InnerTransactionResult: The
-            InnerTransactionResult at the given index.
+        :param index: The index of the transaction in the group.
+        :returns: The InnerTransactionResult at the given index.
         """
         return ITxnLoader(self._get_itxn(index)).transaction