chore: extra exceptions for discouraging nested contexts (#20)

* chore: extra exceptions for discouraging nested contexts

* chore: adjusting finally block to ensure active group is reset upon execution

* docs: refining docs

* ci: improving documentation hatch scripts

* ci: adding doctest checks as part of main ci

* docs: note on future refinement

* docs: further refining the api section

Author: aorumbayev

.github/workflows/ci.yaml

@@ -42,3 +42,6 @@ jobs:
 
       - name: Run tests (examples)
         run: hatch run examples:tests
+
+      - name: Check doctests
+        run: hatch run docs:test

.github/workflows/gh-pages.yaml

@@ -24,6 +24,9 @@ jobs:
           python-version: "3.12"
           cache: "pip"
 
+      - name: Test doctests
+        run: hatch run docs:test
+
       - name: Build doc
         run: hatch run docs:build
 

docs/api.md

@@ -1,5 +1,15 @@
 # API Reference
 
+An overview of the `algorand-python-testing`'s `algopy_testing` module - covering the main classes and functions.
+
+```{hint}
+Spotted a typo in documentation? This project is open source, please submit an issue or a PR on [GitHub](https://github.com/algorand/algorand-python-testing).
+```
+
+```{warning}
+Note, assume `_algopy_testing` to refer to `algopy_testing` namespace in the auto-generated class documentation above. To be patched in near future.
+```
+
 ## Contexts
 
 ```{autodoc2-summary}

docs/conf.py

@@ -84,3 +84,13 @@
 sphinxmermaid_mermaid_init = {
     "theme": "dark",
 }
+
+# Ignore specific warning types
+# TODO : remove upon refining autodoc2 (or finding alternative to sphinx)
+suppress_warnings = [
+    "myst.xref_missing",
+    "autodoc2.dup_item",
+    "ref.python",  # Ignore Python reference warnings
+    "ref.class",  # Ignore class reference warnings
+    "ref.obj",  # Ignore object reference warnings
+]

docs/faq.md

@@ -0,0 +1,61 @@
+# FAQ
+
+## What is a Test Context?
+
+A Test Context is a context manager that provides a simulated Algorand environment for testing Python smart contracts. It allows developers to create and manipulate a virtual Algorand ecosystem for testing purposes. For more details, see the [Test Context section](testing-guide/concepts.md#test-context) in our documentation.
+
+## What is the Algorand Virtual Machine (AVM)?
+
+The Algorand Virtual Machine (AVM) is the runtime environment for Algorand smart contracts. It executes the compiled code of smart contracts on the Algorand blockchain. To learn more about the AVM, visit the [official Algorand documentation](https://developer.algorand.org/docs/get-details/dapps/avm/).
+
+## What are Operational Codes in Algorand?
+
+Operational Codes, or opcodes, are AVM instructions that are executed directly by the AVM. In the context of Algorand Python testing, these opcodes are provided by `algopy` stubs and are either emulated, implemented, or mocked by `algorand-python-testing`. For a comprehensive list of opcodes, refer to the [Algorand Developer Documentation](https://developer.algorand.org/docs/get-details/dapps/avm/teal/opcodes/?from_query=OPcodes#template-modal-overlay).
+
+## What are Value Generators?
+
+Value Generators are helper methods that generate randomized values for testing when the specific value of the tested type is not important. In the context of Algorand Python testing, these are represented by property on the context manager, accessed via `any.*` (or `any.arc4.*`, `any.txn.*`. in the case of ARC 4 types). To understand how to use Value Generators effectively, check out our [Value Generators section](testing-guide/concepts.md#value-generators) in the documentation.
+
+## What are the limitations of the Algorand Python Testing framework?
+
+The Algorand Python Testing framework emulates the Algorand Virtual Machine (AVM) for unit testing Algorand Python smart contracts without interacting with the real Algorand Network. However, it has some limitations due to its scope and purpose:
+
+1. Simplified balance tracking and transaction validation
+2. No consensus mechanism or AVM network operations simulation
+3. Absence of a strict opcode budget system
+4. Certain cryptographic operations are mocked or simplified
+5. No state proof generation or verification
+
+For scenarios where these limitations are crucial, it's recommended to pair this framework with integration testing. If you have a solid reason to justify introducing new emulated behaviour, please open an issue or contribute to the project on [Github](https://github.com/algorandfoundation/algorand-python-testing).
+
+## How does balance tracking work in the testing framework?
+
+The framework uses simplified balance tracking and transaction validation. For scenarios where precise balance or fee verification is important, it's recommended to complement unit tests with integration testing.
+
+## Does the framework simulate the entire AVM network?
+
+No, the framework does not simulate the entire AVM network or consensus mechanism. It focuses on emulating the parts of the AVM relevant to unit testing smart contracts.
+
+## How does the framework handle opcode budgets?
+
+The framework does not implement a strict opcode budget system. For scenarios where validating opcode budget is crucial, it's recommended to use integration testing alongside this framework.
+
+## Are all cryptographic operations fully implemented?
+
+Some cryptographic operations are mocked or simplified in the framework. For a detailed list of which operations are mocked, refer to the _mockable_ types under the [coverage](./coverage.md) section.
+
+## Can I use this framework for security-critical validations?
+
+While this framework is useful for unit testing and local development, it should not be the only tool used for security-critical validations or performance benchmarking. It's designed to approximate AVM behavior for common scenarios. Always complement your testing with additional integration testing options available in `algokit`, where you can test against real localnet or testnet environments.
+
+## Is there an example of how to use this framework alongside integration tests?
+
+Yes, the `algokit-python-template`, accessible via `algokit init`, provides a working example of how to structure `algorand-python-testing` along with regular integration tests against localnet.
+
+```{hint}
+An `algokit-python-template` accessible via `algokit init -t python`, provides a comprehensive and customizable working example of how to structure `algorand-python-testing` along with regular integration tests against localnet.
+```
+
+## Is it compatible with `pytest`?
+
+Yes, it is compatible with `pytest` and _any_ other python testing framework as its agnostic of the testing framework as long as its python. If you spot incompatibility with a certain tool, please open an issue or contribute to the project on [Github](https://github.com/algorandfoundation/algorand-python-testing).

docs/glossary.md

@@ -13,18 +13,6 @@ The `algorand-python-testing` package provides:
 -   An offline testing environment that simulates core AVM functionality
 -   A familiar Pythonic experience, compatible with testing frameworks like [pytest](https://docs.pytest.org/en/latest/), [unittest](https://docs.python.org/3/library/unittest.html), and [hypothesis](https://hypothesis.readthedocs.io/en/latest/)
 
-```{testsetup}
-import algopy
-import algopy_testing
-from algopy_testing import algopy_testing_context
-
-# Create the context manager for snippets below
-ctx_manager = algopy_testing_context()
-
-# Enter the context
-context = ctx_manager.__enter__()
-```
-
 ## Quick Start
 
 `algopy` is a prerequisite for `algorand-python-testing`, providing stubs and type annotations for Algorand Python syntax. It enhances code completion and type checking when writing smart contracts. Note that this code isn't directly executable in standard Python interpreters; it's compiled by `puya` into TEAL for Algorand Network deployment.
@@ -188,11 +176,7 @@ hidden: true
 testing-guide/index
 examples
 coverage
-glossary
+faq
 api
 algopy
 ```
-
-```{testcleanup}
-ctx_manager.__exit__(None, None, None)
-```

docs/index.md

@@ -150,8 +150,10 @@ post-install-commands = [
 ]
 
 [tool.hatch.envs.docs.scripts]
-build = "sphinx-build -b doctest docs docs/_build -W --keep-going -n -E"
-dev = "sphinx-build -b doctest docs docs/_build && sphinx-autobuild docs docs/_build"
+test = "sphinx-build -b doctest docs docs/_build -W --keep-going -n -E"
+clear = "rm -rf docs/_build"
+build = "hatch run docs:clear && sphinx-build docs docs/_build -W --keep-going -n -E"
+dev = "hatch run docs:test  && sphinx-autobuild docs docs/_build"
 
 # Examples environment
 [tool.hatch.envs.examples]

pyproject.toml

@@ -104,6 +104,9 @@ def algopy_testing_context(
     """
     from _algopy_testing.context import AlgopyTestContext
 
+    if _var.get(None) is not None:
+        raise RuntimeError("Nested `algopy_testing_context`s are not allowed.")
+
     token = _var.set(
         AlgopyTestContext(
             default_sender=default_sender,

src/_algopy_testing/context_helpers/context_storage.py

@@ -145,6 +145,8 @@ def create_group(
         :param active_txn_overrides: Overrides for active txn
         :return: None
         """
+        if self._active_group is not None:
+            raise RuntimeError("Nested `create_group` calls are not allowed.")
         if gtxns and active_txn_overrides:
             raise ValueError("cannot specified gtxns and active_txn_overrides at the same time")
         if active_txn_index is not None and not gtxns:
@@ -164,18 +166,18 @@ def create_group(
             last_app_call_txn = app_calls[-1]._txns[-1]
             active_txn_index = processed_gtxns.index(last_app_call_txn)
 
-        previous_group = self._active_group
-        active_group = self._active_group = TransactionGroup(
+        new_group = TransactionGroup(
             txns=processed_gtxns,
             active_txn_index=active_txn_index,
             active_txn_overrides=typing.cast(dict[str, typing.Any], active_txn_overrides),
         )
+        self._active_group = new_group
         try:
             yield
         finally:
-            if active_group.txns:
-                self._groups.append(active_group)
-            self._active_group = previous_group
+            if new_group.txns:
+                self._groups.append(new_group)
+            self._active_group = None
 
     @contextlib.contextmanager
     def _get_or_create_group(self) -> Iterator[TransactionGroup]: