Contract Events APIs (#3472)

* 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`

* Newsfragment for #3472

* Apply changes from #3479

* Allow optional parens on events for sync and async contracts

* Tests for overlapping function/event names

* Corrections per feedback

Author: reedsa

docs/web3.contract.rst

@@ -0,0 +1 @@
+New contract methods to obtain event elements from a contract ABI using a name, signature, selector, or topic.

newsfragments/3472.feature.rst

@@ -217,6 +217,28 @@ def non_strict_emitter(
     return emitter_contract
 
 
+@pytest.fixture
+def emitter(
+    w3,
+    emitter_contract_data,
+    wait_for_transaction,
+    wait_for_block,
+    address_conversion_func,
+):
+    emitter_contract_factory = w3.eth.contract(**emitter_contract_data)
+
+    wait_for_block(w3)
+    deploy_txn_hash = emitter_contract_factory.constructor().transact({"gas": 30029121})
+    deploy_receipt = wait_for_transaction(w3, deploy_txn_hash)
+    contract_address = address_conversion_func(deploy_receipt["contractAddress"])
+
+    bytecode = w3.eth.get_code(contract_address)
+    assert bytecode == emitter_contract_factory.bytecode_runtime
+    _emitter = emitter_contract_factory(address=contract_address)
+    assert _emitter.address == contract_address
+    return _emitter
+
+
 # --- event contract --- #
 
 
@@ -760,3 +782,27 @@ def async_call(request):
 @pytest.fixture
 def async_estimate_gas(request):
     return async_partial(async_invoke_contract, api_call_desig="estimate_gas")
+
+
+@pytest_asyncio.fixture
+async def async_emitter(
+    async_w3,
+    emitter_contract_data,
+    async_wait_for_transaction,
+    async_wait_for_block,
+    address_conversion_func,
+):
+    async_emitter_contract_factory = async_w3.eth.contract(**emitter_contract_data)
+
+    await async_wait_for_block(async_w3)
+    deploy_txn_hash = await async_emitter_contract_factory.constructor().transact(
+        {"gas": 10000000}
+    )
+    deploy_receipt = await async_wait_for_transaction(async_w3, deploy_txn_hash)
+    contract_address = address_conversion_func(deploy_receipt["contractAddress"])
+
+    bytecode = await async_w3.eth.get_code(contract_address)
+    assert bytecode == async_emitter_contract_factory.bytecode_runtime
+    _emitter = async_emitter_contract_factory(address=contract_address)
+    assert _emitter.address == contract_address
+    return _emitter

tests/core/contracts/conftest.py

@@ -133,6 +133,53 @@ def test_find_or_get_functions_by_type(w3, method, args, repr_func, expected):
     assert repr_func(function) == expected
 
 
+def test_get_function_by_name(w3):
+    FUNCTION_NAME_OVERLAP_ABI = [
+        {
+            "anonymous": False,
+            "inputs": [],
+            "name": "increment",
+            "type": "function",
+        },
+        {
+            "anonymous": False,
+            "inputs": [],
+            "name": "incrementCount",
+            "type": "function",
+        },
+    ]
+    contract = w3.eth.contract(abi=FUNCTION_NAME_OVERLAP_ABI)
+
+    increment_func = contract.get_function_by_name("increment")
+    increment_count_func = contract.get_function_by_name("incrementCount")
+    assert repr(increment_func) == "<Function increment()>"
+    assert repr(increment_count_func) == "<Function incrementCount()>"
+
+
+def test_get_event_by_name(w3):
+    EVENT_NAME_OVERLAP_ABI = [
+        {
+            "anonymous": False,
+            "inputs": [],
+            "name": "Deposit",
+            "type": "event",
+        },
+        {
+            "anonymous": False,
+            "inputs": [],
+            "name": "Deposited",
+            "type": "event",
+        },
+    ]
+    contract = w3.eth.contract(abi=EVENT_NAME_OVERLAP_ABI)
+
+    deposit_event = contract.get_event_by_name("Deposit")
+    deposited_event = contract.get_event_by_name("Deposited")
+
+    assert repr(deposit_event) == "<Event Deposit()>"
+    assert repr(deposited_event) == "<Event Deposited()>"
+
+
 @pytest.mark.parametrize(
     "method,args,expected_message,expected_error",
     (

tests/core/contracts/test_contract_ambiguous_functions.py

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