Context-based approach to subscription handlers args management:

- Introduce a ``handler_context`` to expose the w3, subscription, and result, as well as any user-defined context args.

- Add ``handler_context`` to subscriptions that allow for defining custom
  arguments in the subscription handler implementation, available via
  the context.

- Instead of using transient flags, use the handler context directly
  to create handler tests and assert that the handlers were called
  and the ``passed`` flag was set to ``True``.

- ``event`` for logs subscriptions should be handled by the handler context.

- Changes from comments on #3554; update docs.

- newsfragment for #3554

Author: fselmo

docs/internals.rst

@@ -445,13 +445,12 @@ the user is done with it.
 .. code-block:: python
 
     >>> async def new_heads_handler(
-    ...     async_w3: AsyncWeb3,
-    ...     sx: EthSubscription,
-    ...     response: BlockData,
+    ...     context: NewHeadsSubscriptionContext,
     ... ) -> None:
-    ...     print(f"New block header: {response}\n")
-    ...     if response["number"] > 1234567:
-    ...         await sx.unsubscribe()
+    ...     result = context.result
+    ...     print(f"New block header: {result}\n")
+    ...     if result["number"] > 1234567:
+    ...         await context.subscription.unsubscribe()
 
     >>> async def ws_subscription_example():
     ...     async with AsyncWeb3(WebSocketProvider(f"ws://127.0.0.1:8546")) as w3:
@@ -483,30 +482,27 @@ connections.
     >>> from web3.utils.subscriptions import (
     ...     EthSubscription,
     ...     NewHeadsSubscription,
+    ...     NewHeadsSubscriptionContext,
     ...     PendingTxSubscription,
+    ...     PendingTxSubscriptionContext,
     ...     LogsSubscription,
+    ...     LogsSubscriptionContext,
     ... )
 
     >>> async def new_heads_handler(
-    ...     async_w3: AsyncWeb3,
-    ...     sx: EthSubscription,
-    ...     response: BlockData,
+    ...     context: NewHeadsSubscriptionContext,
     ... ) -> None:
-    ...     print(f"New block header: {response}\n")
-    ...     if response["number"] > 1234567:
-    ...         await sx.unsubscribe()
+    ...     print(f"New block header: {context.result}\n")
+    ...     if context.result["number"] > 1234567:
+    ...         await context.subscription.unsubscribe()
 
     >>> async def pending_txs_handler(
-    ...     async_w3: AsyncWeb3,
-    ...     sx: EthSubscription,
-    ...     response: TxData,
+    ...     context: PendingTxSubscriptionContext,
     ... ) -> None:
     ...     ...
 
     >>> async def log_handler(
-    ...     async_w3: AsyncWeb3,
-    ...     sx: EthSubscription,
-    ...     response: LogData,
+    ...     context: LogsSubscriptionContext,
     ... ) -> None:
     ...     ...
 

newsfragments/3554.feature.rst

@@ -0,0 +1 @@
+Add a subscription manager to persistent connection providers, with support for handler methods for ``eth_subscribe`` subscriptions.

tests/core/subscriptions/test_subscriptions.py

@@ -1,7 +1,4 @@
 import pytest
-from unittest.mock import (
-    Mock,
-)
 
 from web3.utils.subscriptions import (
     LogsSubscription,
@@ -64,9 +61,8 @@ def test_logs_subscription_properties(handler):
         "0x0000000000000000000000000000000000000000000000000000000000000001",
         "0x0000000000000000000000000000000000000000000000000000000000000002",
     ]
-    event = Mock()
     logs_subscription = LogsSubscription(
-        address=address, topics=topics, handler=handler, event=event, label="logs label"
+        address=address, topics=topics, handler=handler, label="logs label"
     )
     assert logs_subscription._handler is handler
     assert logs_subscription.label == "logs label"
@@ -76,7 +72,6 @@ def test_logs_subscription_properties(handler):
     )
     assert logs_subscription.address == address
     assert logs_subscription.topics == topics
-    assert logs_subscription.event is event
 
 
 def test_syncing_subscription_properties(handler):

web3/_utils/module_testing/module_testing_utils.py

@@ -106,6 +106,7 @@ def assert_contains_log(
     emitter_contract_address: ChecksumAddress,
     txn_hash_with_log: HexStr,
 ) -> None:
+    assert len(result) > 0
     log_entry = result[0]
     assert log_entry["blockNumber"] == block_with_txn_with_log["number"]
     assert log_entry["blockHash"] == block_with_txn_with_log["hash"]