Contract APIs for event elements in a contract ABI

Contract utils for `get_event_by_name`, `get_event_by_signature`, `get_event_by_selector`, `get_event_by_topic`
Contract utils for `find_events_by_name`, `find_events_by_signature`, `find_events_by_selector`, `find_events_by_topic`

Author: Stuart Reed

docs/web3.contract.rst

@@ -0,0 +1,145 @@
+import pytest
+from typing import (
+    Any,
+    Callable,
+    Sequence,
+)
+
+from eth_typing import (
+    ABIEvent,
+)
+from eth_utils.toolz import (
+    compose,
+    curry,
+)
+
+from web3 import (
+    Web3,
+)
+from web3.contract.async_contract import (
+    AsyncContractEvent,
+)
+from web3.contract.contract import (
+    Contract,
+    ContractEvent,
+)
+
+map_repr = compose(list, curry(map, repr))
+
+
+@pytest.mark.parametrize(
+    "method,args,repr_func,expected",
+    (
+        (
+            "all_events",
+            (),
+            map_repr,
+            [
+                "<Event LogSingleArg(uint256)>",
+                "<Event LogSingleWithIndex(uint256)>",
+            ],
+        ),
+        (
+            "get_event_by_signature",
+            ("LogSingleArg(uint256)",),
+            repr,
+            "<Event LogSingleArg(uint256)>",
+        ),
+        (
+            "find_events_by_name",
+            ("LogSingleArg",),
+            map_repr,
+            [
+                "<Event LogSingleArg(uint256)>",
+            ],
+        ),
+        (
+            "get_event_by_name",
+            ("LogSingleArg",),
+            repr,
+            "<Event LogSingleArg(uint256)>",
+        ),
+        (
+            "find_events_by_selector",
+            (
+                b"\xf7\x0f\xe6\x89\xe2\x90\xd8\xce+*8\x8a\xc2\x8d\xb3o\xbb\x0e\x16\xa6\xd8\x9ch\x04\xc4a\xf6Z\x1b@\xbb\x15",  # noqa: E501
+            ),
+            map_repr,
+            [
+                "<Event LogSingleWithIndex(uint256)>",
+            ],
+        ),
+        (
+            "get_event_by_selector",
+            (
+                b"\xf7\x0f\xe6\x89\xe2\x90\xd8\xce+*8\x8a\xc2\x8d\xb3o\xbb\x0e\x16\xa6\xd8\x9ch\x04\xc4a\xf6Z\x1b@\xbb\x15",  # noqa: E501
+            ),
+            repr,
+            "<Event LogSingleWithIndex(uint256)>",
+        ),
+        (
+            "get_event_by_selector",
+            (0xF70FE689E290D8CE2B2A388AC28DB36FBB0E16A6D89C6804C461F65A1B40BB15,),
+            repr,
+            "<Event LogSingleWithIndex(uint256)>",
+        ),
+        (
+            "get_event_by_selector",
+            ("0xf70fe689e290d8ce2b2a388ac28db36fbb0e16a6d89c6804c461f65a1b40bb15",),
+            repr,
+            "<Event LogSingleWithIndex(uint256)>",
+        ),
+        (
+            "get_event_by_topic",
+            ("0x56d2ef3c5228bf5d88573621e325a4672ab50e033749a601e4f4a5e1dce905d4",),
+            repr,
+            "<Event LogSingleArg(uint256)>",
+        ),
+    ),
+)
+def test_find_or_get_events_by_type(
+    w3: "Web3",
+    method: str,
+    args: Sequence[str],
+    repr_func: Callable[[Any], str],
+    expected: str,
+    event_contract: "Contract",
+) -> None:
+    contract = w3.eth.contract(abi=event_contract.abi)
+    contract_event = getattr(contract, method)(*args)
+    assert repr_func(contract_event) == expected
+
+
+def test_find_events_by_identifier(w3: "Web3", event_contract: "Contract") -> None:
+    def callable_check(event_abi: ABIEvent) -> bool:
+        return event_abi["name"] == "LogSingleArg"
+
+    contract_events = event_contract.find_events_by_identifier(
+        event_contract.abi, w3, event_contract.address, callable_check
+    )
+    assert [repr(evt) for evt in contract_events] == ["<Event LogSingleArg(uint256)>"]
+
+
+def test_get_event_by_identifier(w3: "Web3", event_contract: "Contract") -> None:
+    contract_event = event_contract.get_event_by_identifier(
+        [event_contract.events.LogSingleArg], "LogSingleArg"
+    )
+    assert repr(contract_event) == "<Event LogSingleArg(uint256)>"
+
+
+def test_events_iterator(math_contract):
+    all_events = math_contract.all_events()
+    events_iter = math_contract.events
+
+    for event, expected_event in zip(iter(events_iter), all_events):
+        assert isinstance(event, ContractEvent)
+        assert event.name == expected_event.name
+
+
+def test_async_events_iterator(async_math_contract):
+    all_events = async_math_contract.all_events()
+    events_iter = async_math_contract.events
+
+    for event, expected_event in zip(iter(events_iter), all_events):
+        assert isinstance(event, AsyncContractEvent)
+        assert event.name == expected_event.name

tests/core/contracts/test_contract_events.py

@@ -128,7 +128,7 @@ def test_event_data_extraction(
     assert len(txn_receipt["logs"]) == 1
     log_entry = txn_receipt["logs"][0]
 
-    event_abi = emitter._get_event_abi(event_name)
+    event_abi = emitter.get_event_by_name(event_name).abi
 
     event_topic = getattr(emitter_contract_log_topics, event_name)
     is_anonymous = event_abi["anonymous"]
@@ -335,7 +335,7 @@ def test_event_data_extraction_bytes(
     log_entry = txn_receipt["logs"][0]
 
     event_name = "LogListArgs"
-    event_abi = emitter._get_event_abi(event_name)
+    event_abi = emitter.get_event_by_name(event_name).abi
 
     event_topic = getattr(emitter_contract_log_topics, event_name)
 
@@ -386,7 +386,7 @@ def test_event_data_extraction_bytes_non_strict(
     log_entry = txn_receipt["logs"][0]
 
     event_name = "LogListArgs"
-    event_abi = non_strict_emitter._get_event_abi(event_name)
+    event_abi = non_strict_emitter.get_event_by_name(event_name).abi
 
     event_topic = getattr(emitter_contract_log_topics, event_name)
 
@@ -431,7 +431,7 @@ def test_dynamic_length_argument_extraction(
     assert len(txn_receipt["logs"]) == 1
     log_entry = txn_receipt["logs"][0]
 
-    event_abi = emitter._get_event_abi("LogDynamicArgs")
+    event_abi = emitter.get_event_by_name("LogDynamicArgs").abi
 
     event_topic = emitter_contract_log_topics.LogDynamicArgs
     assert event_topic in log_entry["topics"]
@@ -466,7 +466,7 @@ def test_argument_extraction_strict_bytes_types(
     log_entry = txn_receipt["logs"][0]
     assert len(log_entry["topics"]) == 2
 
-    event_abi = emitter._get_event_abi("LogListArgs")
+    event_abi = emitter.get_event_by_name("LogListArgs").abi
 
     event_topic = emitter_contract_log_topics.LogListArgs
     assert event_topic in log_entry["topics"]
@@ -545,14 +545,14 @@ def test_contract_event_get_logs_sorted_by_log_index(w3, emitter, request_mocker
     ]
 
     with request_mocker(w3, mock_results={"eth_getLogs": get_logs_response}):
-        logs = emitter.events.LogNoArguments().get_logs()
+        logs = emitter.events.LogNoArguments.get_logs()
 
         sorted_logs = sorted(
-            emitter.events.LogNoArguments().get_logs(),
+            emitter.events.LogNoArguments.get_logs(),
             key=lambda log: log["logIndex"],
         )
         sorted_logs = sorted(
-            emitter.events.LogNoArguments().get_logs(),
+            emitter.events.LogNoArguments.get_logs(),
             key=lambda log: log["blockNumber"],
         )
 
@@ -796,7 +796,7 @@ def test_event_rich_log(
         txn_hash = emitter_fn(*call_args).transact()
     txn_receipt = wait_for_transaction(w3, txn_hash)
 
-    event_instance = emitter.events[event_name]()
+    event_instance = emitter.events[event_name]
 
     if process_receipt:
         processed_logs = event_instance.process_receipt(txn_receipt)
@@ -819,7 +819,7 @@ def test_event_rich_log(
 
     quiet_event = emitter.events["LogBytes"]
     with pytest.warns(UserWarning, match=warning_msg):
-        empty_rich_log = quiet_event().process_receipt(txn_receipt)
+        empty_rich_log = quiet_event.process_receipt(txn_receipt)
         assert empty_rich_log == tuple()
 
 
@@ -1059,7 +1059,7 @@ def test_event_rich_log_non_strict(
         txn_hash = emitter_fn(*call_args).transact()
     txn_receipt = wait_for_transaction(w3_non_strict_abi, txn_hash)
 
-    event_instance = non_strict_emitter.events[event_name]()
+    event_instance = non_strict_emitter.events[event_name]
 
     if process_receipt:
         processed_logs = event_instance.process_receipt(txn_receipt)
@@ -1082,7 +1082,7 @@ def test_event_rich_log_non_strict(
 
     quiet_event = non_strict_emitter.events["LogBytes"]
     with pytest.warns(UserWarning, match=warning_msg):
-        empty_rich_log = quiet_event().process_receipt(txn_receipt)
+        empty_rich_log = quiet_event.process_receipt(txn_receipt)
         assert empty_rich_log == tuple()
 
 
@@ -1093,7 +1093,7 @@ def test_event_rich_log_with_byte_args(
     txn_hash = emitter.functions.logListArgs([b"13"], [b"54"]).transact()
     txn_receipt = wait_for_transaction(w3, txn_hash)
 
-    event_instance = emitter.events.LogListArgs()
+    event_instance = emitter.events.LogListArgs
 
     if process_receipt:
         processed_logs = event_instance.process_receipt(txn_receipt)
@@ -1122,7 +1122,7 @@ def test_event_rich_log_with_byte_args(
 def test_receipt_processing_with_discard_flag(
     event_contract, indexed_event_contract, dup_txn_receipt, wait_for_transaction
 ):
-    event_instance = indexed_event_contract.events.LogSingleWithIndex()
+    event_instance = indexed_event_contract.events.LogSingleWithIndex
 
     returned_logs = event_instance.process_receipt(dup_txn_receipt, errors=DISCARD)
     assert returned_logs == ()
@@ -1131,7 +1131,7 @@ def test_receipt_processing_with_discard_flag(
 def test_receipt_processing_with_ignore_flag(
     event_contract, indexed_event_contract, dup_txn_receipt, wait_for_transaction
 ):
-    event_instance = indexed_event_contract.events.LogSingleWithIndex()
+    event_instance = indexed_event_contract.events.LogSingleWithIndex
 
     returned_logs = event_instance.process_receipt(dup_txn_receipt, errors=IGNORE)
     assert len(returned_logs) == 2
@@ -1155,37 +1155,37 @@ def test_receipt_processing_with_ignore_flag(
 
 
 def test_receipt_processing_with_warn_flag(indexed_event_contract, dup_txn_receipt):
-    event_instance = indexed_event_contract.events.LogSingleWithIndex()
+    event_instance = indexed_event_contract.events.LogSingleWithIndex
 
     with pytest.warns(UserWarning, match="Expected 1 log topics.  Got 0"):
         returned_logs = event_instance.process_receipt(dup_txn_receipt, errors=WARN)
         assert len(returned_logs) == 0
 
 
 def test_receipt_processing_with_strict_flag(indexed_event_contract, dup_txn_receipt):
-    event_instance = indexed_event_contract.events.LogSingleWithIndex()
+    event_instance = indexed_event_contract.events.LogSingleWithIndex
 
     with pytest.raises(LogTopicError, match="Expected 1 log topics.  Got 0"):
         event_instance.process_receipt(dup_txn_receipt, errors=STRICT)
 
 
 def test_receipt_processing_with_invalid_flag(indexed_event_contract, dup_txn_receipt):
-    event_instance = indexed_event_contract.events.LogSingleWithIndex()
+    event_instance = indexed_event_contract.events.LogSingleWithIndex
 
     with pytest.raises(Web3AttributeError, match="Error flag must be one of: "):
         event_instance.process_receipt(dup_txn_receipt, errors="not-a-flag")
 
 
 def test_receipt_processing_with_no_flag(indexed_event_contract, dup_txn_receipt):
-    event_instance = indexed_event_contract.events.LogSingleWithIndex()
+    event_instance = indexed_event_contract.events.LogSingleWithIndex
 
     with pytest.warns(UserWarning, match="Expected 1 log topics.  Got 0"):
         returned_log = event_instance.process_receipt(dup_txn_receipt)
         assert len(returned_log) == 0
 
 
 def test_single_log_processing_with_errors(indexed_event_contract, dup_txn_receipt):
-    event_instance = indexed_event_contract.events.LogSingleWithIndex()
+    event_instance = indexed_event_contract.events.LogSingleWithIndex
 
     with pytest.raises(LogTopicError, match="Expected 1 log topics.  Got 0"):
         event_instance.process_log(dup_txn_receipt["logs"][0])
@@ -1244,7 +1244,7 @@ def test_receipt_processing_catches_insufficientdatabytes_error_by_default(
 ):
     txn_hash = emitter.functions.logListArgs([b"13"], [b"54"]).transact()
     txn_receipt = wait_for_transaction(w3, txn_hash)
-    event_instance = emitter.events.LogListArgs()
+    event_instance = emitter.events.LogListArgs
 
     # web3 doesn't generate logs with non-standard lengths, so we have to do it manually
     txn_receipt_dict = copy.deepcopy(txn_receipt)

tests/core/contracts/test_extracting_event_data.py

@@ -97,7 +97,7 @@ def test_event_data_extraction(
     assert len(txn_receipt["logs"]) == 1
     log_entry = txn_receipt["logs"][0]
 
-    event_abi = emitter._get_event_abi(event_name)
+    event_abi = emitter.get_event_by_name(event_name).abi
 
     event_topic = getattr(emitter_contract_log_topics, event_name)
     is_anonymous = event_abi["anonymous"]
@@ -132,7 +132,7 @@ def test_dynamic_length_argument_extraction(
     assert len(txn_receipt["logs"]) == 1
     log_entry = txn_receipt["logs"][0]
 
-    event_abi = emitter._get_event_abi("LogDynamicArgs")
+    event_abi = emitter.get_event_by_name("LogDynamicArgs").abi
 
     event_topic = emitter_contract_log_topics.LogDynamicArgs
     assert event_topic in log_entry["topics"]

tests/core/contracts/test_extracting_event_data_old.py

@@ -50,9 +50,7 @@ def test_event_filter_new_events(
         builder.from_block = "latest"
         event_filter = builder.deploy(w3)
     else:
-        event_filter = emitter.events.LogNoArguments().create_filter(
-            from_block="latest"
-        )
+        event_filter = emitter.events.LogNoArguments.create_filter(from_block="latest")
 
     expected_match_counter = 0
 
@@ -109,9 +107,7 @@ def gen_non_matching_transact():
         builder.from_block = "latest"
         event_filter = builder.deploy(w3)
     else:
-        event_filter = emitter.events.LogNoArguments().create_filter(
-            from_block="latest"
-        )
+        event_filter = emitter.events.LogNoArguments.create_filter(from_block="latest")
 
     expected_match_counter = 0
 
@@ -179,7 +175,7 @@ async def test_async_event_filter_new_events(
         builder.from_block = "latest"
         event_filter = await builder.deploy(async_w3)
     else:
-        event_filter = await async_emitter.events.LogNoArguments().create_filter(
+        event_filter = await async_emitter.events.LogNoArguments.create_filter(
             from_block="latest"
         )
 
@@ -247,7 +243,7 @@ async def gen_non_matching_transact():
         builder.from_block = "latest"
         event_filter = await builder.deploy(async_w3)
     else:
-        event_filter = await async_emitter.events.LogNoArguments().create_filter(
+        event_filter = await async_emitter.events.LogNoArguments.create_filter(
             from_block="latest"
         )