feat: deferred app calls, modular test context, refined access to value generators, numerous fixes/improvements

.github/workflows/cd.yaml

@@ -57,7 +57,7 @@ jobs:
           cache: "pip"
 
       - name: Start LocalNet
-        run: hatch run cicd:localnet_start
+        run: pipx install algokit && algokit localnet start
 
       - name: Check pre-commits
         run: hatch run check

.github/workflows/ci.yaml

@@ -3,6 +3,8 @@ name: Check Python Code (algopy_testing)
 on:
   workflow_call:
   pull_request:
+  schedule:
+    - cron: "0 8 * * 1" # Each monday 8 AM UTC
 
 jobs:
   check-python:
@@ -21,14 +23,17 @@ jobs:
           cache: "pip"
 
       - name: Start LocalNet
-        run: hatch run cicd:localnet_start
+        run: pipx install algokit && algokit localnet start
 
       - name: Check pre-commits
         run: hatch run check
 
       - name: Check pre-commits (examples)
         run: hatch run examples:check
 
+      - name: Validate examples folder
+        run: hatch run validate_examples
+
       - name: Check wheels can be built
         run: hatch build
 

.pre-commit-config.yaml

@@ -1,18 +1,10 @@
 repos:
   - repo: local
     hooks:
-      - id: pre-commit
+      - id: pre-commit (src & examples)
         name: pre-commit
         description: "Run pre-commit task via hatch"
         entry: hatch run pre_commit
         language: system
         additional_dependencies: []
         minimum_pre_commit_version: "0"
-
-      - id: examples-pre-commit
-        name: examples-pre-commit
-        description: "Run examples venv pre-commit task via hatch"
-        entry: hatch run examples:pre_commit
-        language: system
-        additional_dependencies: []
-        minimum_pre_commit_version: "0"

.vscode/extensions.json

@@ -0,0 +1,10 @@
+{
+    "recommendations": [
+        "ms-python.python",
+        "charliermarsh.ruff",
+        "ms-python.mypy-type-checker",
+        "ms-python.black-formatter",
+        "tamasfe.even-better-toml",
+        "editorconfig.editorconfig"
+    ]
+}

.vscode/settings.json

@@ -28,10 +28,11 @@
     "ruff.codeAction.fixViolation": {
         "enable": true
     },
-
-    "mypy.configFile": "pyproject.toml",
-    // set to empty array to use config from project
-    "mypy.targets": ["--cache-dir=/dev/null"],
-    "mypy.runUsingActiveInterpreter": true,
-    "cSpell.words": ["addw", "mulw"]
+    "mypy-type-checker.importStrategy": "fromEnvironment",
+    "mypy-type-checker.args": [
+        "--enable-incomplete-feature=Unpack",
+        "--config-file=pyproject.toml",
+        "--strict",
+        "--show-column-numbers"
+    ]
 }

CONTRIBUTING.md

@@ -40,3 +40,59 @@ Examples folder uses a dedicated 'venv.examples' virtual environment managed by
 Project relies on [python-semantic-release](https://python-semantic-release.readthedocs.io/en/latest/) for release automation.
 
 Releases are triggered by a `workflow_dispatch` event on the `main` branch with `prerelease` set to accordingly using the `.github/workflows/cd.yaml` file.
+
+# Implementation vs Stubs
+
+The canonical definition of the algopy API comes from the [`alogrand-python`](https://pypi.org/project/algorand-python/) package which consists only of typing information defined in the `algopy-stubs` module.
+In this library the testing implementation should follow the "shape" of the API defined in these stubs. In particular, types, methods and attributes should reflect what is described in the stubs.
+
+However, implementation specific details can diverge from what is described in the stubs. For example methods marked as `@staticmethod` in the stubs do not need to be static methods in the implementation.
+Implementation types may provide more methods or properties than described in the stubs, the stubs are just the minimal set of what should be defined.
+
+The `algopy_testing` module contains the implementation of the stubs and additional parts of the testing framework.
+The `algopy` module is used to alias the relevant `algopy_testing` implementations into the correct namespaces defined in the stubs.
+
+Implementations within `algopy_testing` should use `algopy_testing` types as much as possible, except for typing annotations which should use the `algopy` equivalents instead. A rule of thumb to follow is 
+withing the `algopy_testing` module, `import algopy` should only be used for type definitions e.g.
+
+```python
+import typing
+
+if typing.TYPE_CHECKING:
+    import algopy
+
+def do_something_with_bytes(a: algopy.Bytes) -> algopy.Bytes:
+    ...
+```
+
+Instance checks should be done via the `algopy_testing` namespace, this will ensure any additional attributes on the implementation will be type checked correctly e.g.
+
+```python
+import algopy_testing
+
+
+def do_something(value: object) -> None:
+    if isinstance(value, algopy_testing.Bytes):
+        raw_bytes: bytes = value.value
+        ...
+```
+
+Occasionally this will require silencing Mypy warnings, within the scope of the implementation code this is considered acceptable.
+
+```python
+import typing
+
+import algopy_testing
+
+if typing.TYPE_CHECKING:
+    import algopy
+
+def get_some_bytes() -> algopy.Bytes:
+    value = algopy_testing.Bytes(b"42")
+    # in the following statement, the return type warning is silenced as 
+    # algopy.Bytes is an alias of algopy_testing.Bytes
+    return value # type: ignore[return-value]
+```
+
+
+

docs/coverage.md

@@ -15,11 +15,10 @@ See which `algorand-python` stubs are implemented by the `algorand-python-testin
 | Primitives (UInt64, BigUInt, Bytes, String)                  | Implemented           |
 | urange                                                       | Implemented           |
 | All crypto ops in op.\* namespace (to be expanded in detail) | Implemented           |
-| Txn, GTxn, ITxn                                              | Implemented           |
 | arc4.\* namespace (to be expanded in detail)                 | Implemented           |
 | uenumerate                                                   | Implemented           |
-| op.ITxnCreate                                                | Implemented           |
 | StateTotals                                                  | Implemented           |
+| Txn, GTxn, ITxn                                              | Emulated              |
 | Asset                                                        | Emulated              |
 | Account                                                      | Emulated              |
 | Application                                                  | Emulated              |
@@ -34,10 +33,11 @@ See which `algorand-python` stubs are implemented by the `algorand-python-testin
 | log                                                          | Emulated              |
 | itxn.\* namespace (inner transactions)                       | Emulated              |
 | gtxn.\* namespace (group transactions)                       | Emulated              |
+| op.ITxnCreate                                                | Emulated              |
 | ensure_budget                                                | Mockable              |
 | op.EllipticCurve                                             | Mockable              |
-| op.AssetParamsGet                                            | Mockable              |
-| op.AppParamsGet                                              | Mockable              |
-| op.AppLocal                                                  | Mockable              |
-| op.AppGlobal                                                 | Mockable              |
-| op.AcctParamsGet                                             | Mockable              |
+| op.AssetParamsGet                                            | Emulated              |
+| op.AppParamsGet                                              | Emulated              |
+| op.AppLocal                                                  | Emulated              |
+| op.AppGlobal                                                 | Emulated              |
+| op.AcctParamsGet                                             | Emulated              |

examples/README.md

@@ -0,0 +1,56 @@
+# Algorand Python Testing examples
+
+This directory contains examples demonstrating how to use algorand-python-testing to test smart contracts written in Algorand Python.
+
+## Overview
+
+`algorand-python-testing` provides a powerful framework for unit testing Algorand smart contracts written in Algorand Python. It allows developers to emulate AVM behavior in a Python interpreter, making it easier to write and run tests for your Algorand applications.
+
+## Key Features
+
+1. **Test Environment Setup**: Use the `context` fixture to set up a test environment that emulates AVM behavior.
+2. **Arrange, Act, Assert Pattern**: Examples follow the 'arrange, act, assert' pattern for clear and structured tests.
+3. **Asset and Account Creation**: Easily create test assets and accounts using `context.any.asset` and `context.any.account`.
+4. **State Manipulation**: Test global and local state changes in your smart contracts.
+5. **ABI Method Testing**: Examples of how to test ABI methods in your smart contracts.
+
+## Quickstart
+
+To run the examples in a self-contained manner:
+
+1. Install [hatch](https://hatch.pypa.io/latest/)
+2. From the root of the repo, run:
+
+```bash
+hatch run examples:test examples/<example_directory>
+```
+
+Replace `<example_directory>` with the specific example you want to run (e.g., `auction`, `abi`, etc.).
+
+## Writing Tests
+
+When writing tests for your Algorand smart contracts:
+
+1. Use the `context` fixture to set up your test environment.
+2. Create test assets and accounts as needed using `context.any.asset` and `context.any.account`.
+3. Interact with your smart contract methods.
+4. Assert the expected outcomes, including state changes and transaction results.
+
+For detailed examples, refer to the individual test files in each example directory.
+
+## Contributing
+
+If you have additional examples or improvements, feel free to contribute by submitting a pull request.
+
+1. Follow the [contribution guidelines](https://github.com/algorandfoundation/algorand-python-testing/blob/main/CONTRIBUTING.md).
+2. Create a new folder under `examples/` with your contract/signature and test files.
+3. If you are contributing a smart contract example make sure to name the file `contract.py`. For logic signatures, name it `signature.py`.
+4. For test files use `test_contract.py` or `test_signature.py` respectively.
+5. Use the default PR template when opening a PR, and describe what sort of example are you adding as well as which feature of `algorand-python-testing` it demonstrates.
+
+## Resources
+
+-   [Algorand Developer Documentation](https://developer.algorand.org/)
+-   [algorand-python](https://algorandfoundation.github.io/puya/)
+-   [algorand-python-testing](https://algorandfoundation.github.io/algorand-python-testing/)
+-   ['arrange, act, assert' patern](https://automationpanda.com/2020/07/07/arrange-act-assert-a-pattern-for-writing-good-tests/)