Address remaining comments from PR #3554:

- ``sx`` -> ``sub``.
- Some clarifying changes on type hints and arg names in tests.
- Docs update to clarify handlers. This whole area of the docs will get
  a lot of attention and refactoring in a future PR. But at least the
  current docs are more descriptive.

Author: fselmo

docs/internals.rst

@@ -445,12 +445,12 @@ the user is done with it.
 .. code-block:: python
 
     >>> async def new_heads_handler(
-    ...     context: NewHeadsSubscriptionContext,
+    ...     handler_context: NewHeadsSubscriptionContext,
     ... ) -> None:
-    ...     result = context.result
+    ...     result = handler_context.result
     ...     print(f"New block header: {result}\n")
     ...     if result["number"] > 1234567:
-    ...         await context.subscription.unsubscribe()
+    ...         await handler_context.subscription.unsubscribe()
 
     >>> async def ws_subscription_example():
     ...     async with AsyncWeb3(WebSocketProvider(f"ws://127.0.0.1:8546")) as w3:
@@ -470,7 +470,17 @@ The manager can also subscribe to many subscriptions at one time. The
 friendly API for managing subscriptions. Since each connection and provider instance
 has its own message listener task and subscription manager instance, you can subscribe
 to many subscriptions at once and handle the many responses that come in over the socket
-connections.
+connections via handlers. The handlers contain:
+
+- ``async_w3``: The ``AsyncWeb3`` instance that the subscription was made on.
+- ``subscription``: The subscription instance that the handler is attached to.
+- ``result``: The response that came in over the socket connection for the subscription.
+
+Subscriptions also accept a ``handler_context`` argument that can be used to pass
+additional information to the handler when subscribing to a subscription. This can be
+used to pass in an event object, for example, that can be used to parse a log event
+when it comes in.
+
 
 .. code-block:: python
 
@@ -490,23 +500,28 @@ connections.
     ... )
 
     >>> async def new_heads_handler(
-    ...     context: NewHeadsSubscriptionContext,
+    ...     handler_context: NewHeadsSubscriptionContext,
     ... ) -> None:
-    ...     print(f"New block header: {context.result}\n")
-    ...     if context.result["number"] > 1234567:
-    ...         await context.subscription.unsubscribe()
+    ...     header = handler_context.result
+    ...     print(f"New block header: {header}\n")
+    ...     if header["number"] > 1234567:
+    ...         await handler_context.subscription.unsubscribe()
 
     >>> async def pending_txs_handler(
-    ...     context: PendingTxSubscriptionContext,
+    ...     handler_context: PendingTxSubscriptionContext,
     ... ) -> None:
     ...     ...
 
     >>> async def log_handler(
-    ...     context: LogsSubscriptionContext,
+    ...     handler_context: LogsSubscriptionContext,
     ... ) -> None:
-    ...     ...
+    ...     log_receipt = handler_context.result
+    ...     # event is now available in the handler context, because we pass it to in the
+    ...     # ``handler_context`` when subscribing to the log
+    ...     event_data = handler_context.event.process_log(log_receipt)
+    ...     print(f"Log event data: {event_data}\n")
 
-    >>> async def sx_manager():
+    >>> async def sub_manager():
     ...     local_w3 = await AsyncWeb3(AsyncIPCProvider(LOCAL_IPC, label="mainnet-ipc"))
     ...     # subscribe to many subscriptions via the subscription manager with handlers
     ...     await local_w3.subscription_manager.subscribe(
@@ -522,6 +537,8 @@ connections.
     ...                 address=local_w3.to_checksum_address("0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"),
     ...                 topics=[HexStr("0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef")],
     ...                 handler=log_handler,
+    ...                 # optional ``handler_context`` args to help parse a response
+    ...                 handler_context={"event": my_event},
     ...             ),
     ...         ]
     ...     )
@@ -538,7 +555,7 @@ connections.
     ...         local_w3.subscription_manager.handle_subscriptions(),
     ...     )
 
-    >>> asyncio.run(sx_manager())
+    >>> asyncio.run(sub_manager())
 
 
 The ``process_subscriptions()`` method on the

tests/core/providers/test_websocket_provider.py

@@ -20,6 +20,7 @@
 )
 from web3._utils.caching import (
     RequestInformation,
+    generate_cache_key,
 )
 from web3._utils.module_testing.module_testing_utils import (
     WebSocketMessageStreamMock,
@@ -274,8 +275,7 @@ async def test_listen_event_awaits_msg_processing_when_subscription_queue_is_ful
         subscription_id=sub_id,
     )
     async_w3.provider._request_processor._request_information_cache.cache(
-        # cache key is the result of `generate_cache_key` with the sub_id as the arg
-        "0138b5d63d66121d8a6e680d23720fa7",
+        generate_cache_key(sub_id),
         sub_request_information,
     )
 

tests/core/subscriptions/test_subscription_manager.py

@@ -40,63 +40,63 @@ async def subscription_manager():
 
 
 @pytest.mark.asyncio
-async def test_subscription_manager_raises_for_sx_with_the_same_label(
+async def test_subscription_manager_raises_for_sub_with_the_same_label(
     subscription_manager,
 ):
-    sx1 = NewHeadsSubscription(label="foo")
-    await subscription_manager.subscribe(sx1)
+    sub1 = NewHeadsSubscription(label="foo")
+    await subscription_manager.subscribe(sub1)
 
     with pytest.raises(
         Web3ValueError,
         match="Subscription label already exists. Subscriptions must have unique "
         "labels.\n    label: foo",
     ):
-        sx2 = LogsSubscription(label="foo")
-        await subscription_manager.subscribe(sx2)
+        sub2 = LogsSubscription(label="foo")
+        await subscription_manager.subscribe(sub2)
 
     # make sure the subscription was subscribed to and not added to the manager
-    assert subscription_manager.subscriptions == [sx1]
-    assert subscription_manager._subscriptions_by_label == {"foo": sx1}
-    assert subscription_manager._subscriptions_by_id == {"0x0": sx1}
+    assert subscription_manager.subscriptions == [sub1]
+    assert subscription_manager._subscriptions_by_label == {"foo": sub1}
+    assert subscription_manager._subscriptions_by_id == {"0x0": sub1}
 
 
 @pytest.mark.asyncio
 async def test_subscription_manager_get_by_id(subscription_manager):
-    sx = NewHeadsSubscription(label="foo")
-    await subscription_manager.subscribe(sx)
-    assert subscription_manager.get_by_id("0x0") == sx
+    sub = NewHeadsSubscription(label="foo")
+    await subscription_manager.subscribe(sub)
+    assert subscription_manager.get_by_id("0x0") == sub
     assert subscription_manager.get_by_id("0x1") is None
 
 
 @pytest.mark.asyncio
 async def test_subscription_manager_get_by_label(subscription_manager):
-    sx = NewHeadsSubscription(label="foo")
-    await subscription_manager.subscribe(sx)
-    assert subscription_manager.get_by_label("foo") == sx
+    sub = NewHeadsSubscription(label="foo")
+    await subscription_manager.subscribe(sub)
+    assert subscription_manager.get_by_label("foo") == sub
     assert subscription_manager.get_by_label("bar") is None
 
 
 @pytest.mark.asyncio
 async def test_unsubscribe_one_by_one_clears_all_subscriptions(
     subscription_manager,
 ):
-    sx1 = NewHeadsSubscription(label="foo")
-    sx2 = PendingTxSubscription(label="bar")
-    await subscription_manager.subscribe(sx1)
-    await subscription_manager.subscribe(sx2)
+    sub1 = NewHeadsSubscription(label="foo")
+    sub2 = PendingTxSubscription(label="bar")
+    await subscription_manager.subscribe(sub1)
+    await subscription_manager.subscribe(sub2)
 
-    await subscription_manager.unsubscribe(sx1)
-    assert subscription_manager.subscriptions == [sx2]
+    await subscription_manager.unsubscribe(sub1)
+    assert subscription_manager.subscriptions == [sub2]
 
-    await subscription_manager.unsubscribe(sx2)
+    await subscription_manager.unsubscribe(sub2)
     assert subscription_manager.subscriptions == []
 
 
 @pytest.mark.asyncio
 async def test_unsubscribe_all_clears_all_subscriptions(subscription_manager):
-    sx1 = NewHeadsSubscription(label="foo")
-    sx2 = PendingTxSubscription(label="bar")
-    await subscription_manager.subscribe([sx1, sx2])
+    sub1 = NewHeadsSubscription(label="foo")
+    sub2 = PendingTxSubscription(label="bar")
+    await subscription_manager.subscribe([sub1, sub2])
 
     await subscription_manager.unsubscribe_all()
     assert subscription_manager.subscriptions == []