algorand-python-testing 0.3.0b9__tar.gz → 0.4.0__tar.gz

{algorand_python_testing-0.3.0b9 → algorand_python_testing-0.4.0}/.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

{algorand_python_testing-0.3.0b9 → algorand_python_testing-0.4.0}/.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
 

{algorand_python_testing-0.3.0b9 → algorand_python_testing-0.4.0}/CHANGELOG.md

@@ -1,4 +1,42 @@
 # CHANGELOG
+## v0.4.0 (2024-08-27)
+
+## v0.4.0-beta.2 (2024-08-27)
+
+## v0.4.0-beta.1 (2024-08-27)
+
+### Feature
+
+* add support for frozen on asset holdings, including a new ledger function `update_asset_holdings` for setting asset holding balances and frozen states ([`d777ca0`](https://github.com/algorandfoundation/algorand-python-testing/commit/d777ca0a318a8ade7a20363c9ce77fe8a8bf5d68))
+
+* expand accepted types when interacting with accounts, applications and assets ([`f448a97`](https://github.com/algorandfoundation/algorand-python-testing/commit/f448a97cb154c9f90ecf42c599b240f12928af20))
+
+  wip
+
+* replaced `account_exists` with `account_is_funded` as the later is more useful ([`4d08690`](https://github.com/algorandfoundation/algorand-python-testing/commit/4d086903eb93a70ce1d485cdd7b12d8472ef16db))
+
+### Fix
+
+* use correct type for Globals.caller_application_id ([`a30d85a`](https://github.com/algorandfoundation/algorand-python-testing/commit/a30d85a4416dfc2c5d901f3ace2265384ef60c01))
+
+* do not allow specifying `address` for applications, it is derived from the app_id ([`00fe1bc`](https://github.com/algorandfoundation/algorand-python-testing/commit/00fe1bc8ea247dcc36b01154db36b984b151e396))
+
+* do not treat asset and application ids as possible foreign array indexes ([`94a989f`](https://github.com/algorandfoundation/algorand-python-testing/commit/94a989f77169da2ae437c629cd5f4d8a872263f6))
+
+* removed incorrect deduction in `algopy.op.balance` ([`76e67c5`](https://github.com/algorandfoundation/algorand-python-testing/commit/76e67c5e3dd1cda388a2a948d452ba89805add6a))
+
+* ensure all comparable types return `NotImplemented` when a comparison is not possible ([`b055fa6`](https://github.com/algorandfoundation/algorand-python-testing/commit/b055fa68531e0b7923773ec10c2097a3d64b9dbe))
+
+* `arc4_prefix` annotated to also accept `algopy.Bytes` ([`40328ca`](https://github.com/algorandfoundation/algorand-python-testing/commit/40328ca3701b3e255193e206e8a7b1bdb441a346))
+
+### Documentation
+
+* include usage of `algopy_testing_context` in README.md quick start ([`4702f60`](https://github.com/algorandfoundation/algorand-python-testing/commit/4702f60cfe7d09956a5ae6dbdcd72da29fdda808))
+
+## v0.3.0 (2024-08-22)
+
+## v0.3.0-beta.10 (2024-08-22)
+
 ## v0.3.0-beta.9 (2024-08-22)
 
 ## v0.3.0-beta.8 (2024-08-22)

{algorand_python_testing-0.3.0b9 → algorand_python_testing-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: algorand-python-testing
-Version: 0.3.0b9
+Version: 0.4.0
 Summary: Algorand Python testing library
 Project-URL: Documentation, https://github.com/algorandfoundation/puya/tree/main/algopy_testing#README.md
 Project-URL: Issues, https://github.com/algorandfoundation/puya/issues
@@ -55,17 +55,18 @@ Alternatively, if you want to start from scratch:
     ```python
     from algopy_testing import algopy_testing_context
     from your_contract import YourContract
-
+    
     def test_your_contract():
-        # Arrange
-        contract = YourContract()
-        expected_result = ... # Your expected result here
-
-        # Act
-        result = contract.your_method()  # Your test code here
-
-        # Assert
-        assert result == expected_result
+        with algopy_testing_context() as context:
+            # Arrange
+            contract = YourContract()
+            expected_result = ... # Your expected result here
+    
+            # Act
+            result = contract.your_method(context.any.uint64())  # Your test code here
+    
+            # Assert
+            assert result == expected_result
     ```
 
 5. Run your tests using your preferred Python testing framework (e.g., pytest, unittest)

{algorand_python_testing-0.3.0b9 → algorand_python_testing-0.4.0}/README.md

@@ -32,17 +32,18 @@ Alternatively, if you want to start from scratch:
     ```python
     from algopy_testing import algopy_testing_context
     from your_contract import YourContract
-
+    
     def test_your_contract():
-        # Arrange
-        contract = YourContract()
-        expected_result = ... # Your expected result here
-
-        # Act
-        result = contract.your_method()  # Your test code here
-
-        # Assert
-        assert result == expected_result
+        with algopy_testing_context() as context:
+            # Arrange
+            contract = YourContract()
+            expected_result = ... # Your expected result here
+    
+            # Act
+            result = contract.your_method(context.any.uint64())  # Your test code here
+    
+            # Assert
+            assert result == expected_result
     ```
 
 5. Run your tests using your preferred Python testing framework (e.g., pytest, unittest)

{algorand_python_testing-0.3.0b9 → algorand_python_testing-0.4.0}/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}

{algorand_python_testing-0.3.0b9 → algorand_python_testing-0.4.0}/docs/conf.py

@@ -84,3 +84,13 @@ doctest_test_doctest_blocks = "default"
 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
+]

algorand_python_testing-0.4.0/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).

{algorand_python_testing-0.3.0b9 → algorand_python_testing-0.4.0}/docs/index.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)
-```

{algorand_python_testing-0.3.0b9 → algorand_python_testing-0.4.0}/docs/testing-guide/avm-types.md

@@ -103,7 +103,7 @@ asset = context.ledger.get_asset(asset_id=random_asset.id)
 
 # Update an asset
 context.ledger.update_asset(
-    asset_id=random_asset.id,
+    random_asset,
     name=...,  # Optional: New asset name
     total=...,  # Optional: New total supply
     decimals=...,  # Optional: Number of decimals
@@ -130,7 +130,7 @@ account = algopy.Account(raw_address) # zero address by default
 # Generate a random account
 random_account = context.any.account(
     address=str(raw_address),  # Optional: Specify a custom address, defaults to a random address
-    opted_asset_balances=...,  # Optional: Specify opted asset balances as dict of algopy.UInt64 as key and algopy.UInt64 as value
+    opted_asset_balances={},  # Optional: Specify opted asset balances as dict of assets to balance
     opted_apps=[],  # Optional: Specify opted apps as sequence of algopy.Application objects
     balance=...,  # Optional: Specify an initial balance
     min_balance=...,  # Optional: Specify a minimum balance
@@ -145,7 +145,7 @@ random_account = context.any.account(
 # Generate a random account that is opted into a specific asset
 mock_asset = context.any.asset()
 mock_account = context.any.account(
-    opted_asset_balances={mock_asset.id: algopy.UInt64(123)}
+    opted_asset_balances={mock_asset: 123}
 )
 
 # Get an account by address
@@ -153,7 +153,7 @@ account = context.ledger.get_account(str(mock_account))
 
 # Update an account
 context.ledger.update_account(
-    str(mock_account),
+    mock_account,
     balance=...,  # Optional: New balance
     min_balance=...,  # Optional: New minimum balance
     auth_address=context.any.account(),  # Optional: New auth address
@@ -181,7 +181,6 @@ application = algopy.Application()
 
 # Generate a random application
 random_app = context.any.application(
-    address=...,  # Optional: Specify a custom address for the application
     approval_program=algopy.Bytes(b''),  # Optional: Specify a custom approval program
     clear_state_program=algopy.Bytes(b''),  # Optional: Specify a custom clear state program
     global_num_uint=algopy.UInt64(1),  # Optional: Number of global uint values
@@ -197,7 +196,7 @@ app = context.ledger.get_app(app_id=random_app.id)
 
 # Update an application
 context.ledger.update_app(
-    app_id=random_app.id,
+    random_app,
     approval_program=...,  # Optional: New approval program
     clear_state_program=...,  # Optional: New clear state program
     global_num_uint=...,  # Optional: New number of global uint values

{algorand_python_testing-0.3.0b9 → algorand_python_testing-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "algorand-python-testing"
-version = "0.3.0-beta.9"
+version = "0.4.0"
 description = 'Algorand Python testing library'
 readme = "README.md"
 requires-python = ">=3.12"
@@ -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]

{algorand_python_testing-0.3.0b9 → algorand_python_testing-0.4.0}/src/_algopy_testing/__init__.py

@@ -25,9 +25,6 @@ from _algopy_testing.value_generators.arc4 import ARC4ValueGenerator
 from _algopy_testing.value_generators.avm import AVMValueGenerator
 from _algopy_testing.value_generators.txn import TxnValueGenerator
 
-# 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",

{algorand_python_testing-0.3.0b9 → algorand_python_testing-0.4.0}/src/_algopy_testing/arc4.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import dataclasses
 import decimal
+import functools
 import types
 import typing
 
@@ -169,7 +170,8 @@ class _ABIEncoded(BytesBacked):
     def __eq__(self, other: object) -> bool:
         if isinstance(other, _ABIEncoded):
             return self._type_info == other._type_info and self.bytes == other.bytes
-        return NotImplemented
+        else:
+            return NotImplemented
 
     def __hash__(self) -> int:
         return hash(self.bytes)
@@ -234,7 +236,11 @@ class String(_ABIEncoded):
         return String(as_string(other) + self.native)
 
     def __eq__(self, other: String | str) -> bool:  # type: ignore[override]
-        return self.native == as_string(other)
+        try:
+            other_string = as_string(other)
+        except TypeError:
+            return NotImplemented
+        return self.native == other_string
 
     def __bool__(self) -> bool:
         """Returns `True` if length is not zero."""
@@ -294,47 +300,12 @@ class _UIntN(_ABIEncoded, typing.Generic[_TBitSize], metaclass=_UIntNMeta):
         bytes_value = int_to_bytes(value, self._type_info.max_bytes_len)
         self._value = as_bytes(bytes_value)
 
-    def __eq__(  # type: ignore[override]
-        self,
-        other: UIntN[_TBitSize] | BigUIntN[_TBitSize] | algopy.UInt64 | algopy.BigUInt | int,
-    ) -> bool:
-        raise NotImplementedError
-
-    def __ne__(  # type: ignore[override]
-        self,
-        other: UIntN[_TBitSize] | BigUIntN[_TBitSize] | algopy.UInt64 | algopy.BigUInt | int,
-    ) -> bool:
-        raise NotImplementedError
-
-    def __le__(
-        self,
-        other: UIntN[_TBitSize] | BigUIntN[_TBitSize] | algopy.UInt64 | algopy.BigUInt | int,
-    ) -> bool:
-        raise NotImplementedError
-
-    def __lt__(
-        self,
-        other: UIntN[_TBitSize] | BigUIntN[_TBitSize] | algopy.UInt64 | algopy.BigUInt | int,
-    ) -> bool:
-        raise NotImplementedError
-
-    def __ge__(
-        self,
-        other: UIntN[_TBitSize] | BigUIntN[_TBitSize] | algopy.UInt64 | algopy.BigUInt | int,
-    ) -> bool:
-        raise NotImplementedError
-
-    def __gt__(
-        self,
-        other: UIntN[_TBitSize] | BigUIntN[_TBitSize] | algopy.UInt64 | algopy.BigUInt | int,
-    ) -> bool:
-        raise NotImplementedError
-
     def __bool__(self) -> bool:
         """Returns `True` if not equal to zero."""
         raise NotImplementedError
 
 
+@functools.total_ordering
 class UIntN(_UIntN, typing.Generic[_TBitSize]):  # type: ignore[type-arg]
     """An ARC4 UInt consisting of the number of bits specified.
 
@@ -349,22 +320,18 @@ class UIntN(_UIntN, typing.Generic[_TBitSize]):  # type: ignore[type-arg]
         return algopy.UInt64(int.from_bytes(self._value))
 
     def __eq__(self, other: object) -> bool:
-        return as_int64(self.native) == as_int(other, max=None)
-
-    def __ne__(self, other: object) -> bool:
-        return as_int64(self.native) != as_int(other, max=None)
-
-    def __le__(self, other: object) -> bool:
-        return as_int64(self.native) <= as_int(other, max=None)
+        try:
+            other_int = as_int64(other)
+        except (TypeError, ValueError):
+            return NotImplemented
+        return as_int64(self.native) == other_int
 
     def __lt__(self, other: object) -> bool:
-        return as_int64(self.native) < as_int(other, max=None)
-
-    def __ge__(self, other: object) -> bool:
-        return as_int64(self.native) >= as_int(other, max=None)
-
-    def __gt__(self, other: object) -> bool:
-        return as_int64(self.native) > as_int(other, max=None)
+        try:
+            other_int = as_int64(other)
+        except (TypeError, ValueError):
+            return NotImplemented
+        return as_int64(self.native) < other_int
 
     def __bool__(self) -> bool:
         return bool(self.native)
@@ -376,6 +343,7 @@ class UIntN(_UIntN, typing.Generic[_TBitSize]):  # type: ignore[type-arg]
         return _arc4_repr(self)
 
 
+@functools.total_ordering
 class BigUIntN(_UIntN, typing.Generic[_TBitSize]):  # type: ignore[type-arg]
     """An ARC4 UInt consisting of the number of bits specified.
 
@@ -390,22 +358,18 @@ class BigUIntN(_UIntN, typing.Generic[_TBitSize]):  # type: ignore[type-arg]
         return algopy.BigUInt.from_bytes(self._value)
 
     def __eq__(self, other: object) -> bool:
-        return as_int512(self.native) == as_int(other, max=None)
-
-    def __ne__(self, other: object) -> bool:
-        return as_int512(self.native) != as_int(other, max=None)
-
-    def __le__(self, other: object) -> bool:
-        return as_int512(self.native) <= as_int(other, max=None)
+        try:
+            other_int = as_int512(other)
+        except (TypeError, ValueError):
+            return NotImplemented
+        return as_int512(self.native) == other_int
 
     def __lt__(self, other: object) -> bool:
-        return as_int512(self.native) < as_int(other, max=None)
-
-    def __ge__(self, other: object) -> bool:
-        return as_int512(self.native) >= as_int(other, max=None)
-
-    def __gt__(self, other: object) -> bool:
-        return as_int512(self.native) > as_int(other, max=None)
+        try:
+            other_int = as_int512(other)
+        except (TypeError, ValueError):
+            return NotImplemented
+        return as_int512(self.native) < other_int
 
     def __bool__(self) -> bool:
         return bool(self.native)
@@ -749,8 +713,11 @@ class Address(StaticArray[Byte, typing.Literal[32]]):
         `Account` or `str`"""
         if isinstance(other, Address | Account):
             return self.bytes == other.bytes
-        other_bytes: bytes = algosdk.encoding.decode_address(other)
-        return self.bytes == other_bytes
+        elif isinstance(other, str):
+            other_bytes: bytes = algosdk.encoding.decode_address(other)
+            return self.bytes == other_bytes
+        else:
+            return NotImplemented
 
     def __str__(self) -> str:
         return str(self.native)

{algorand_python_testing-0.3.0b9 → algorand_python_testing-0.4.0}/src/_algopy_testing/context_helpers/context_storage.py

@@ -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,