algorand-python-testing 1.2.0b5__tar.gz → 1.2.0b7__tar.gz

{algorand_python_testing-1.2.0b5 → algorand_python_testing-1.2.0b7}/CHANGELOG.md

@@ -1,4 +1,12 @@
 # CHANGELOG
+## v1.2.0-beta.7 (2026-04-09)
+
+## v1.2.0-beta.6 (2026-04-07)
+
+### Features
+
+* add arc65 support: loggedErr() and loggedAssert() functions, to log a formatted error string before failing ([`5ac27a5`](https://github.com/algorandfoundation/algorand-python-testing/commit/5ac27a5f96d075224c47dc7c8b6ceba65db0e5e3))
+
 ## v1.2.0-beta.5 (2026-04-01)
 
 ### Features

{algorand_python_testing-1.2.0b5 → algorand_python_testing-1.2.0b7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: algorand-python-testing
-Version: 1.2.0b5
+Version: 1.2.0b7
 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

{algorand_python_testing-1.2.0b5 → algorand_python_testing-1.2.0b7}/docs/coverage.md

@@ -41,6 +41,8 @@ See which `algorand-python` stubs are implemented by the `algorand-python-testin
 | algopy.compile_logicsig                     | Mockable            |
 | algopy.ensure_budget                        | Emulated            |
 | algopy.log                                  | Emulated            |
+| algopy.logged_assert                        | Emulated            |
+| algopy.log_err                              | Emulated            |
 | algopy.logicsig                             | Emulated            |
 | algopy.public                               | Emulated            |
 | algopy.size_of                              | Emulated            |

{algorand_python_testing-1.2.0b5 → algorand_python_testing-1.2.0b7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "algorand-python-testing"
-version = "1.2.0-beta.5"
+version = "1.2.0-beta.7"
 description = 'Algorand Python testing library'
 readme = "README.md"
 requires-python = ">=3.12"
@@ -50,7 +50,7 @@ type = "virtual"
 path = ".venv"
 python = "3.12"
 dependencies = [
-    "puyapy>=5.7.1",
+    "puyapy>=5.8.0",
     "pytest>=7.4",
     "pytest-mock>=3.10.0",
     "pytest-xdist[psutil]>=3.3",
@@ -132,7 +132,7 @@ dependencies = [
     "pytest-cov>=4.1.0",
     "py-algorand-sdk>=2.4.0",
     "algokit-utils>=4.0.0",
-    "puyapy>=5.7.1",
+    "puyapy>=5.8.0",
 ]
 
 [tool.hatch.envs.test.scripts]

{algorand_python_testing-1.2.0b5 → algorand_python_testing-1.2.0b7}/src/_algopy_testing/models/contract.py

@@ -37,16 +37,16 @@ class _ContractMeta(type):
     _scratch_slots: typing.Any
     _state_totals: StateTotals | None
     _avm_version: int
-
-    def __init__(cls, *args: typing.Any, **kwargs: typing.Any) -> None:
-        super().__init__(*args, **kwargs)
-        cls.global_state_types = dict[str, type]()
+    _global_state_types: dict[str, type]
 
     def __call__(cls, *args: typing.Any, **kwargs: dict[str, typing.Any]) -> object:
+        # cls is both _ContractMeta and a (sub)class of Contract, but mypy can't
+        # handle intersection types (and assumes that cls is just _ContractMeta)
+        assert issubclass(cls, Contract)
         context = lazy_context.value
         app_ref = context.any.application()  # new reference to get a unique app_id
         app_id = app_ref.id.value
-        instance: Contract = cls.__new__(cls, *args, **kwargs)  # type: ignore[arg-type]
+        instance = cls.__new__(cls, *args, **kwargs)
         instance.__app_id__ = app_id
         app_data = lazy_context.get_app_data(app_id)
         app_data.contract = instance
@@ -54,6 +54,9 @@ class _ContractMeta(type):
 
         fields = get_active_txn_fields(app_ref)
         txn = context.any.txn.application_call(**fields)
+        # the below is the key reason for this being a metaclass, rather than overriding
+        # the __new__ method in Contract itself: we get to control the calling of __init__,
+        # and place it inside the following context manager
         with context.txn._maybe_implicit_txn_group([txn]) as active_group:
             if active_group.active_app_id != app_id:
                 raise ValueError(
@@ -64,10 +67,9 @@ class _ContractMeta(type):
                 app_id,
                 creator=creator,
             )
-            instance.__init__(*args, **kwargs)  # type: ignore[misc]
+            cls.__init__(instance, *args, **kwargs)
         app_data.is_creating = _has_create_methods(cls)
 
-        assert isinstance(instance, Contract)
         cls_state_totals = cls._state_totals or StateTotals()
         state_totals = _get_state_totals(instance, cls_state_totals)
         context.ledger.update_app(
@@ -96,6 +98,7 @@ class Contract(metaclass=_ContractMeta):
         state_totals: StateTotals | None = None,
         avm_version: int = 11,
     ):
+        cls._global_state_types = dict[str, type]()  # ensure each subclass gets its own
         cls._name = name or cls.__name__
         cls._scratch_slots = scratch_slots
         cls._state_totals = state_totals
@@ -138,9 +141,8 @@ class Contract(metaclass=_ContractMeta):
             return set_is_creating
 
         cls = type(self)
-        assert isinstance(cls, _ContractMeta)
         try:
-            unproxied_global_state_type = cls.global_state_types[name]
+            unproxied_global_state_type = cls._global_state_types[name]
         except KeyError:
             return attr
         value = lazy_context.ledger.get_global_state(self.__app_id__, name.encode("utf8"))
@@ -173,8 +175,7 @@ class Contract(metaclass=_ContractMeta):
                 app_id = self.__app_id__
                 lazy_context.ledger.set_global_state(app_id, name_bytes, serialize(value))
                 cls = type(self)
-                assert isinstance(cls, _ContractMeta)
-                cls.global_state_types[name] = type(value)
+                cls._global_state_types[name] = type(value)
 
         super().__setattr__(name, value)
 
@@ -242,7 +243,7 @@ def _is_uint_state(type_: type) -> bool:
         return issubclass(type_, UInt64 | UInt64Backed | bool)
 
 
-def _has_create_methods(contract_cls: _ContractMeta) -> bool:
+def _has_create_methods(contract_cls: type[Contract]) -> bool:
     for method in vars(contract_cls).values():
         if callable(method) and (arc4_meta := maybe_arc4_metadata(method)) and arc4_meta.is_create:
             return True

algorand_python_testing-1.2.0b7/src/_algopy_testing/utilities/__init__.py

@@ -0,0 +1,5 @@
+from _algopy_testing.utilities.budget import OpUpFeeSource, ensure_budget
+from _algopy_testing.utilities.log import log, logged_assert, logged_err
+from _algopy_testing.utilities.size_of import size_of
+
+__all__ = ["OpUpFeeSource", "ensure_budget", "log", "logged_assert", "logged_err", "size_of"]

algorand_python_testing-1.2.0b7/src/_algopy_testing/utilities/log.py

@@ -0,0 +1,116 @@
+import typing
+
+from _algopy_testing.constants import UINT64_BYTES_LENGTH
+from _algopy_testing.context_helpers import lazy_context
+from _algopy_testing.primitives.bytes import Bytes
+from _algopy_testing.primitives.uint64 import UInt64
+from _algopy_testing.protocols import BytesBacked
+from _algopy_testing.utils import int_to_bytes
+
+
+def log(
+    *args: UInt64 | Bytes | BytesBacked | str | bytes | int,
+    sep: Bytes | bytes | str = b"",
+) -> None:
+    """Concatenates and logs supplied args as a single bytes value.
+
+    UInt64 args are converted to bytes and each argument is separated by `sep`.
+    Literal `str` values will be encoded as UTF8.
+    """
+    logs: list[bytes] = []
+
+    for arg in args:
+        if isinstance(arg, UInt64):
+            logs.append(int_to_bytes(arg.value, pad_to=UINT64_BYTES_LENGTH))
+        elif isinstance(arg, Bytes):
+            logs.append(arg.value)
+        elif isinstance(arg, str):
+            logs.append(arg.encode("utf8"))
+        elif isinstance(arg, bytes):
+            logs.append(arg)
+        elif isinstance(arg, int):
+            logs.append(int_to_bytes(arg, pad_to=UINT64_BYTES_LENGTH))
+        else:
+            logs.append(arg.bytes.value)
+
+    if isinstance(sep, Bytes):
+        separator = sep.value
+    elif isinstance(sep, str):
+        separator = sep.encode("utf8")
+    else:
+        separator = sep
+
+    active_txn = lazy_context.active_group.active_txn
+    active_txn.append_log(separator.join(logs))
+
+
+def logged_assert(
+    condition: bool,  # noqa: FBT001
+    /,
+    error_code: typing.LiteralString,
+    error_message: typing.LiteralString | None = None,
+    prefix: typing.Literal["AER", "ERR"] = "ERR",
+) -> None:
+    """Asserts that a condition is true, logging a formatted error message before
+    failing if the condition is false.
+
+    The logged output follows the format ``{prefix}:{error_code}`` or
+    ``{prefix}:{error_code}:{error_message}`` and is compatible with ARC-56 and ARC-32 clients.
+
+    Note this increases the generated bytecode, so keeping ``error_code`` and ``error_message``
+    short is recommended.
+
+    :arg condition: The condition to assert; if false, logs an error and fails.
+    :arg error_code: An alphanumeric error code. Must not contain ``:``.
+    :arg error_message: Optional message appended after the code. Must not contain ``:``.
+    :arg prefix: Error prefix, either ``"AER"`` or ``"ERR"``.
+    """
+    if condition:
+        return
+    msg = _resolve_error_message(error_code, error_message, prefix)
+    log(msg)
+    raise RuntimeError(msg)
+
+
+def logged_err(
+    error_code: typing.LiteralString,
+    error_message: typing.LiteralString | None = None,
+    prefix: typing.Literal["AER", "ERR"] = "ERR",
+) -> None:
+    """Logs a formatted error message and immediately fails the transaction.
+
+    Note this is equivalent to ``logged_assert(False, error_code, error_message, prefix)``.
+    This function increases the generated bytecode, so keeping ``error_code`` and ``error_message``
+    short is recommended.
+
+    The logged output follows the ARC-65 format ``{prefix}:{error_code}`` or
+    ``{prefix}:{error_code}:{error_message}`` and is compatible with ARC-56 and ARC-32 clients.
+
+    :arg error_code: An alphanumeric error code. Must not contain ``:``.
+    :arg error_message: Optional message appended after the code. Must not contain ``:``.
+    :arg prefix: Error prefix, either ``"AER"`` or ``"ERR"``.
+    """
+    msg = _resolve_error_message(error_code, error_message, prefix)
+    log(msg)
+    raise RuntimeError(msg)
+
+
+_VALID_PREFIXES = frozenset({"ERR", "AER"})
+
+
+def _resolve_error_message(
+    code: str,
+    message: str | None = None,
+    prefix: str = "ERR",
+) -> str:
+    if ":" in code:
+        raise ValueError("error code must not contain domain separator ':'")
+    if message and ":" in message:
+        raise ValueError("error message must not contain domain separator ':'")
+    if prefix not in _VALID_PREFIXES:
+        raise ValueError("error prefix must be one of AER, ERR")
+
+    if message:
+        return f"{prefix}:{code}:{message}"
+    else:
+        return f"{prefix}:{code}"

{algorand_python_testing-1.2.0b5 → algorand_python_testing-1.2.0b7}/src/algopy/__init__.py

@@ -31,7 +31,14 @@ from _algopy_testing.primitives import (
 )
 from _algopy_testing.protocols import BytesBacked
 from _algopy_testing.state import Box, BoxMap, BoxRef, GlobalMap, GlobalState, LocalMap, LocalState
-from _algopy_testing.utilities import OpUpFeeSource, ensure_budget, log, size_of
+from _algopy_testing.utilities import (
+    OpUpFeeSource,
+    ensure_budget,
+    log,
+    logged_assert,
+    logged_err,
+    size_of,
+)
 
 from . import arc4, gtxn, itxn, op
 from _algopy_testing.decorators.arc4 import (
@@ -80,6 +87,8 @@ __all__ = [
     "gtxn",
     "itxn",
     "log",
+    "logged_assert",
+    "logged_err",
     "logicsig",
     "op",
     "public",

{algorand_python_testing-1.2.0b5 → algorand_python_testing-1.2.0b7}/tests/artifacts/PrimitiveOps/contract.py

@@ -1,6 +1,18 @@
 import typing
 
-from algopy import ARC4Contract, BigUInt, Bytes, FixedBytes, String, UInt64, arc4, log, op
+from algopy import (
+    ARC4Contract,
+    BigUInt,
+    Bytes,
+    FixedBytes,
+    String,
+    UInt64,
+    arc4,
+    log,
+    logged_assert,
+    logged_err,
+    op,
+)
 
 
 class PrimitiveOpsContract(ARC4Contract):
@@ -371,3 +383,27 @@ class PrimitiveOpsContract(ARC4Contract):
         arc4_m = arc4.DynamicArray[arc4.UInt16].from_bytes(m)
         arc4_n = arc4.Tuple[arc4.UInt32, arc4.UInt64, arc4.String].from_bytes(n)
         log(a, b, c, d_biguint, e, f, g, h, i, j, arc4_k, arc4_m, arc4_n, o, sep="-")
+
+    @arc4.abimethod
+    def verify_logged_errs(self, arg: UInt64) -> None:
+        # "ERR:01"
+        logged_assert(arg != 1, "01")
+        # "ERR:arg02:arg is two"
+        logged_assert(arg != 2, "arg02", error_message="arg is two")
+        # "AER:arg03"
+        logged_assert(arg != 3, "arg03", prefix="AER")
+        # "AER:arg04:arg is 4"
+        logged_assert(arg != 4, "arg04", error_message="arg is 4", prefix="AER")
+
+        # "ERR:arg05"
+        if arg == 5:
+            logged_err("arg05")
+        # "ERR:arg06:arg was 6"
+        if arg == 6:
+            logged_err("06", error_message="arg was 6")
+        # "AER:arg07"
+        if arg == 7:
+            logged_err("arg07", prefix="AER")
+        # "AER:arg08:arg is eight (08)"
+        if arg == 8:
+            logged_err("arg08", error_message="arg is eight (08)", prefix="AER")