web3 7.6.1__py3-none-any.whl → 7.8.0__py3-none-any.whl

web3/eth/async_eth.py

@@ -99,11 +99,16 @@ from web3.types import (
     _Hash32,
 )
 from web3.utils import (
+    EthSubscription,
     async_handle_offchain_lookup,
 )
+from web3.utils.subscriptions import (
+    EthSubscriptionHandler,
+)
 
 if TYPE_CHECKING:
     from web3 import AsyncWeb3  # noqa: F401
+    from web3.contract.async_contract import AsyncContractEvent  # noqa: F401
 
 
 class AsyncEth(BaseEth):
@@ -714,6 +719,9 @@ class AsyncEth(BaseEth):
                 bool,  # newPendingTransactions, full_transactions
             ]
         ] = None,
+        handler: Optional[EthSubscriptionHandler] = None,
+        handler_context: Optional[Dict[str, Any]] = None,
+        label: Optional[str] = None,
     ) -> HexStr:
         if not isinstance(self.w3.provider, PersistentConnectionProvider):
             raise MethodNotSupported(
@@ -721,10 +729,13 @@ class AsyncEth(BaseEth):
                 "persistent connections."
             )
 
-        if subscription_arg is None:
-            return await self._subscribe(subscription_type)
-
-        return await self._subscribe_with_args(subscription_type, subscription_arg)
+        sub = EthSubscription._create_type_aware_subscription(
+            subscription_params=(subscription_type, subscription_arg),
+            handler=handler,
+            handler_context=handler_context or {},
+            label=label,
+        )
+        return await self.w3.subscription_manager.subscribe(sub)
 
     _unsubscribe: Method[Callable[[HexStr], Awaitable[bool]]] = Method(
         RPC.eth_unsubscribe,
@@ -738,7 +749,14 @@ class AsyncEth(BaseEth):
                 "persistent connections."
             )
 
-        return await self._unsubscribe(subscription_id)
+        for sub in self.w3.subscription_manager.subscriptions:
+            if sub._id == subscription_id:
+                return await sub.unsubscribe()
+
+        raise Web3ValueError(
+            f"Cannot unsubscribe subscription with id `{subscription_id}`. "
+            "Subscription not found."
+        )
 
     # -- contract methods -- #
 

web3/exceptions.py

@@ -353,6 +353,13 @@ class PersistentConnectionClosedOK(PersistentConnectionError):
     """
 
 
+class SubscriptionProcessingFinished(Web3Exception):
+    """
+    Raised to alert the subscription manager that the processing of subscriptions
+    has finished.
+    """
+
+
 class Web3RPCError(Web3Exception):
     """
     Raised when a JSON-RPC response contains an error field.

web3/main.py

@@ -148,6 +148,9 @@ from web3.tracing import (
 from web3.types import (
     Wei,
 )
+from web3.providers.persistent.subscription_manager import (
+    SubscriptionManager,
+)
 
 if TYPE_CHECKING:
     from web3._utils.batching import RequestBatcher  # noqa: F401
@@ -508,12 +511,27 @@ class AsyncWeb3(BaseWeb3):
             new_ens.w3 = self  # set self object reference for ``AsyncENS.w3``
         self._ens = new_ens
 
-    # -- persistent connection methods -- #
+    # -- persistent connection settings -- #
+
+    _subscription_manager: Optional[SubscriptionManager] = None
+    _persistent_connection: Optional["PersistentConnection"] = None
+
+    @property
+    @persistent_connection_provider_method()
+    def subscription_manager(self) -> SubscriptionManager:
+        """
+        Access the subscription manager for the current PersistentConnectionProvider.
+        """
+        if not self._subscription_manager:
+            self._subscription_manager = SubscriptionManager(self)
+        return self._subscription_manager
 
     @property
     @persistent_connection_provider_method()
     def socket(self) -> PersistentConnection:
-        return PersistentConnection(self)
+        if self._persistent_connection is None:
+            self._persistent_connection = PersistentConnection(self)
+        return self._persistent_connection
 
     # w3 = await AsyncWeb3(PersistentConnectionProvider(...))
     @persistent_connection_provider_method(
@@ -522,7 +540,10 @@ class AsyncWeb3(BaseWeb3):
     )
     def __await__(self) -> Generator[Any, None, Self]:
         async def __async_init__() -> Self:
-            await self.provider.connect()
+            provider = cast("PersistentConnectionProvider", self.provider)
+            await provider.connect()
+            # set signal handlers since not within a context manager
+            provider._set_signal_handlers()
             return self
 
         return __async_init__().__await__()

web3/manager.py

@@ -6,7 +6,9 @@ from typing import (
     AsyncGenerator,
     Callable,
     Coroutine,
+    Dict,
     List,
+    NoReturn,
     Optional,
     Sequence,
     Tuple,
@@ -69,7 +71,9 @@ from web3.providers.async_base import (
     AsyncJSONBaseProvider,
 )
 from web3.types import (
+    FormattedEthSubscriptionResponse,
     RPCEndpoint,
+    RPCRequest,
     RPCResponse,
 )
 
@@ -255,15 +259,38 @@ def _validate_response(
             web3_rpc_error = Web3RPCError(repr(error), rpc_response=response)
 
         response = apply_error_formatters(error_formatters, response)
-
-        logger.error(web3_rpc_error.user_message)
         logger.debug(f"RPC error response: {response}")
+
         raise web3_rpc_error
 
     elif "result" not in response and not is_subscription_response:
         _raise_bad_response_format(response)
 
 
+def _raise_error_for_batch_response(
+    response: RPCResponse,
+    logger: Optional[logging.Logger] = None,
+) -> NoReturn:
+    error = response.get("error")
+    if error is None:
+        _raise_bad_response_format(
+            response,
+            "Batch response must be formatted as a list of responses or "
+            "as a single JSON-RPC error response.",
+        )
+    _validate_response(
+        response,
+        None,
+        is_subscription_response=False,
+        logger=logger,
+        params=[],
+    )
+    # This should not be reached, but if it is, raise a generic `BadResponseFormat`
+    raise BadResponseFormat(
+        "Batch response was in an unexpected format and unable to be parsed."
+    )
+
+
 class RequestManager:
     logger = logging.getLogger("web3.manager.RequestManager")
 
@@ -293,9 +320,6 @@ class RequestManager:
             provider = cast(PersistentConnectionProvider, self.provider)
             self._request_processor: RequestProcessor = provider._request_processor
 
-    w3: Union["AsyncWeb3", "Web3"] = None
-    _provider = None
-
     @property
     def provider(self) -> Union["BaseProvider", "AsyncBaseProvider"]:
         return self._provider
@@ -437,17 +461,23 @@ class RequestManager:
         request_func = provider.batch_request_func(
             cast("Web3", self.w3), cast("MiddlewareOnion", self.middleware_onion)
         )
-        responses = request_func(
+        response = request_func(
             [
                 (method, params)
                 for (method, params), _response_formatters in requests_info
             ]
         )
-        formatted_responses = [
-            self._format_batched_response(info, resp)
-            for info, resp in zip(requests_info, responses)
-        ]
-        return list(formatted_responses)
+
+        if isinstance(response, list):
+            # expected format
+            formatted_responses = [
+                self._format_batched_response(info, cast(RPCResponse, resp))
+                for info, resp in zip(requests_info, response)
+            ]
+            return list(formatted_responses)
+        else:
+            # expect a single response with an error
+            _raise_error_for_batch_response(response, self.logger)
 
     async def _async_make_batch_request(
         self,
@@ -466,22 +496,31 @@ class RequestManager:
         # since we add items to the batch without awaiting, we unpack the coroutines
         # and await them all here
         unpacked_requests_info = await asyncio.gather(*requests_info)
-        responses = await request_func(
+        response = await request_func(
             [
                 (method, params)
                 for (method, params), _response_formatters in unpacked_requests_info
             ]
         )
 
-        if isinstance(self.provider, PersistentConnectionProvider):
-            # call _process_response for each response in the batch
-            return [await self._process_response(resp) for resp in responses]
-
-        formatted_responses = [
-            self._format_batched_response(info, resp)
-            for info, resp in zip(unpacked_requests_info, responses)
-        ]
-        return list(formatted_responses)
+        if isinstance(response, list):
+            # expected format
+            response = cast(List[RPCResponse], response)
+            if isinstance(self.provider, PersistentConnectionProvider):
+                # call _process_response for each response in the batch
+                return [
+                    cast(RPCResponse, await self._process_response(resp))
+                    for resp in response
+                ]
+
+            formatted_responses = [
+                self._format_batched_response(info, resp)
+                for info, resp in zip(unpacked_requests_info, response)
+            ]
+            return list(formatted_responses)
+        else:
+            # expect a single response with an error
+            _raise_error_for_batch_response(response, self.logger)
 
     def _format_batched_response(
         self,
@@ -489,6 +528,13 @@ class RequestManager:
         response: RPCResponse,
     ) -> RPCResponse:
         result_formatters, error_formatters, null_result_formatters = requests_info[1]
+        _validate_response(
+            response,
+            error_formatters,
+            is_subscription_response=False,
+            logger=self.logger,
+            params=requests_info[0][1],
+        )
         return apply_result_formatters(
             result_formatters,
             self.formatted_response(
@@ -501,32 +547,65 @@ class RequestManager:
 
     # -- persistent connection -- #
 
-    async def socket_request(self, method: RPCEndpoint, params: Any) -> RPCResponse:
+    async def socket_request(
+        self,
+        method: RPCEndpoint,
+        params: Any,
+        response_formatters: Optional[
+            Tuple[Dict[str, Callable[..., Any]], Callable[..., Any], Callable[..., Any]]
+        ] = None,
+    ) -> RPCResponse:
         provider = cast(PersistentConnectionProvider, self._provider)
-        request_func = await provider.request_func(
-            cast("AsyncWeb3", self.w3), cast("MiddlewareOnion", self.middleware_onion)
-        )
         self.logger.debug(
             "Making request to open socket connection and waiting for response: "
-            f"{provider.get_endpoint_uri_or_ipc_path()}, method: {method}"
+            f"{provider.get_endpoint_uri_or_ipc_path()},\n    method: {method},\n"
+            f"    params: {params}"
         )
-        response = await request_func(method, params)
-        return await self._process_response(response)
+        rpc_request = await self.send(method, params)
+        provider._request_processor.cache_request_information(
+            rpc_request["id"],
+            rpc_request["method"],
+            rpc_request["params"],
+            response_formatters=response_formatters or ((), (), ()),
+        )
+        return await self.recv_for_request(rpc_request)
 
-    async def send(self, method: RPCEndpoint, params: Any) -> None:
+    async def send(self, method: RPCEndpoint, params: Any) -> RPCRequest:
         provider = cast(PersistentConnectionProvider, self._provider)
-        # run through the request processors of the middleware
-        for mw_class in self.middleware_onion.as_tuple_of_middleware():
-            mw = mw_class(self.w3)
-            method, params = mw.request_processor(method, params)
-
+        async_w3 = cast("AsyncWeb3", self.w3)
+        middleware_onion = cast("MiddlewareOnion", self.middleware_onion)
+        send_func = await provider.send_func(
+            async_w3,
+            middleware_onion,
+        )
         self.logger.debug(
             "Sending request to open socket connection: "
-            f"{provider.get_endpoint_uri_or_ipc_path()}, method: {method}"
+            f"{provider.get_endpoint_uri_or_ipc_path()},\n    method: {method},\n"
+            f"    params: {params}"
         )
-        await provider.socket_send(provider.encode_rpc_request(method, params))
+        return await send_func(method, params)
 
-    async def recv(self) -> RPCResponse:
+    async def recv_for_request(self, rpc_request: RPCRequest) -> RPCResponse:
+        provider = cast(PersistentConnectionProvider, self._provider)
+        async_w3 = cast("AsyncWeb3", self.w3)
+        middleware_onion = cast("MiddlewareOnion", self.middleware_onion)
+        recv_func = await provider.recv_func(
+            async_w3,
+            middleware_onion,
+        )
+        self.logger.debug(
+            "Getting response for request from open socket connection:\n"
+            f"    request: {rpc_request}"
+        )
+        response = await recv_func(rpc_request)
+        try:
+            return cast(RPCResponse, await self._process_response(response))
+        except Exception:
+            response_id_key = generate_cache_key(response["id"])
+            provider._request_processor._request_information_cache.pop(response_id_key)
+            raise
+
+    async def recv(self) -> Union[RPCResponse, FormattedEthSubscriptionResponse]:
         provider = cast(PersistentConnectionProvider, self._provider)
         self.logger.debug(
             "Getting next response from open socket connection: "
@@ -544,15 +623,18 @@ class RequestManager:
     def _persistent_message_stream(self) -> "_AsyncPersistentMessageStream":
         return _AsyncPersistentMessageStream(self)
 
-    async def _get_next_message(self) -> RPCResponse:
+    async def _get_next_message(self) -> FormattedEthSubscriptionResponse:
         return await self._message_stream().__anext__()
 
-    async def _message_stream(self) -> AsyncGenerator[RPCResponse, None]:
+    async def _message_stream(
+        self,
+    ) -> AsyncGenerator[FormattedEthSubscriptionResponse, None]:
         if not isinstance(self._provider, PersistentConnectionProvider):
             raise Web3TypeError(
                 "Only providers that maintain an open, persistent connection "
                 "can listen to streams."
             )
+        async_w3 = cast("AsyncWeb3", self.w3)
 
         if self._provider._message_listener_task is None:
             raise ProviderConnectionError(
@@ -564,13 +646,21 @@ class RequestManager:
                 response = await self._request_processor.pop_raw_response(
                     subscription=True
                 )
-                if (
-                    response is not None
-                    and response.get("params", {}).get("subscription")
-                    in self._request_processor.active_subscriptions
-                ):
-                    # if response is an active subscription response, process it
-                    yield await self._process_response(response)
+                # if the subscription was unsubscribed from, we won't have a formatted
+                # response because we lost the request information.
+                sub_id = response.get(
+                    "subscription", response.get("params", {}).get("subscription")
+                )
+                if async_w3.subscription_manager.get_by_id(sub_id):
+                    # if active subscription, process and yield the formatted response
+                    formatted_sub_response = cast(
+                        FormattedEthSubscriptionResponse,
+                        await self._process_response(response),
+                    )
+                    yield formatted_sub_response
+                else:
+                    # if not an active sub, skip processing and continue
+                    continue
             except TaskNotRunning:
                 await asyncio.sleep(0)
                 self._provider._handle_listener_task_exceptions()
@@ -580,7 +670,9 @@ class RequestManager:
                 )
                 return
 
-    async def _process_response(self, response: RPCResponse) -> RPCResponse:
+    async def _process_response(
+        self, response: RPCResponse
+    ) -> Union[RPCResponse, FormattedEthSubscriptionResponse]:
         provider = cast(PersistentConnectionProvider, self._provider)
         request_info = self._request_processor.get_request_information_for_response(
             response
@@ -643,5 +735,5 @@ class _AsyncPersistentMessageStream:
     def __aiter__(self) -> Self:
         return self
 
-    async def __anext__(self) -> RPCResponse:
+    async def __anext__(self) -> FormattedEthSubscriptionResponse:
         return await self.manager._get_next_message()

web3/method.py

@@ -203,7 +203,7 @@ class Method(Generic[TFunc]):
     def process_params(
         self, module: "Module", *args: Any, **kwargs: Any
     ) -> Tuple[
-        Tuple[Union[RPCEndpoint, Callable[..., RPCEndpoint]], Tuple[Any, ...]],
+        Tuple[Union[RPCEndpoint, Callable[..., RPCEndpoint]], Tuple[RPCEndpoint, ...]],
         Tuple[
             Union[TReturn, Dict[str, Callable[..., Any]]],
             Callable[..., Any],

web3/middleware/attrdict.py

@@ -7,10 +7,6 @@ from typing import (
     cast,
 )
 
-from eth_utils.toolz import (
-    assoc,
-)
-
 from web3.datastructures import (
     AttributeDict,
 )
@@ -33,21 +29,18 @@ if TYPE_CHECKING:
 
 
 def _handle_async_response(response: "RPCResponse") -> "RPCResponse":
+    """
+    Process the RPC response by converting nested dictionaries into AttributeDict.
+    """
     if "result" in response:
-        return assoc(response, "result", AttributeDict.recursive(response["result"]))
+        response["result"] = AttributeDict.recursive(response["result"])
     elif "params" in response and "result" in response["params"]:
-        # this is a subscription response
-        return assoc(
-            response,
-            "params",
-            assoc(
-                response["params"],
-                "result",
-                AttributeDict.recursive(response["params"]["result"]),
-            ),
+        # subscription response
+        response["params"]["result"] = AttributeDict.recursive(
+            response["params"]["result"]
         )
-    else:
-        return response
+
+    return response
 
 
 class AttributeDictMiddleware(Web3Middleware, ABC):
@@ -60,11 +53,9 @@ class AttributeDictMiddleware(Web3Middleware, ABC):
 
     def response_processor(self, method: "RPCEndpoint", response: "RPCResponse") -> Any:
         if "result" in response:
-            return assoc(
-                response, "result", AttributeDict.recursive(response["result"])
-            )
-        else:
-            return response
+            new_result = AttributeDict.recursive(response["result"])
+            response = {**response, "result": new_result}
+        return response
 
     # -- async -- #
 
@@ -72,7 +63,6 @@ class AttributeDictMiddleware(Web3Middleware, ABC):
         self, method: "RPCEndpoint", response: "RPCResponse"
     ) -> Any:
         if self._w3.provider.has_persistent_connection:
-            # asynchronous response processing
             provider = cast("PersistentConnectionProvider", self._w3.provider)
             provider._request_processor.append_middleware_response_processor(
                 response, _handle_async_response

web3/middleware/base.py

@@ -62,15 +62,19 @@ class Web3Middleware:
     ) -> "MakeBatchRequestFn":
         def middleware(
             requests_info: List[Tuple["RPCEndpoint", Any]]
-        ) -> List["RPCResponse"]:
+        ) -> Union[List["RPCResponse"], "RPCResponse"]:
             req_processed = [
                 self.request_processor(method, params)
                 for (method, params) in requests_info
             ]
-            responses = make_batch_request(req_processed)
+            response = make_batch_request(req_processed)
+            if not isinstance(response, list):
+                # RPC errors return only one response with the error object
+                return response
+
             methods, _params = zip(*req_processed)
             formatted_responses = [
-                self.response_processor(m, r) for m, r in zip(methods, responses)
+                self.response_processor(m, r) for m, r in zip(methods, response)
             ]
             return formatted_responses
 
@@ -103,16 +107,20 @@ class Web3Middleware:
     ) -> "AsyncMakeBatchRequestFn":
         async def middleware(
             requests_info: List[Tuple["RPCEndpoint", Any]]
-        ) -> List["RPCResponse"]:
+        ) -> Union[List["RPCResponse"], "RPCResponse"]:
             req_processed = [
                 await self.async_request_processor(method, params)
                 for (method, params) in requests_info
             ]
-            responses = await make_batch_request(req_processed)
+            response = await make_batch_request(req_processed)
+            if not isinstance(response, list):
+                # RPC errors return only one response with the error object
+                return response
+
             methods, _params = zip(*req_processed)
             formatted_responses = [
                 await self.async_response_processor(m, r)
-                for m, r in zip(methods, responses)
+                for m, r in zip(methods, response)
             ]
             return formatted_responses
 

web3/module.py

@@ -32,6 +32,7 @@ from web3.providers.persistent import (
     PersistentConnectionProvider,
 )
 from web3.types import (
+    FormattedEthSubscriptionResponse,
     RPCEndpoint,
     RPCResponse,
 )
@@ -74,7 +75,7 @@ def retrieve_request_information_for_batching(
         )
         if isinstance(w3.provider, PersistentConnectionProvider):
             w3.provider._request_processor.cache_request_information(
-                cast(RPCEndpoint, method_str), params, response_formatters
+                None, cast(RPCEndpoint, method_str), params, response_formatters
             )
         return (cast(RPCEndpoint, method_str), params), response_formatters
 
@@ -121,8 +122,17 @@ def retrieve_async_method_call_fn(
     async_w3: "AsyncWeb3",
     module: "Module",
     method: Method[Callable[..., Any]],
-) -> Callable[..., Coroutine[Any, Any, Optional[Union[RPCResponse, AsyncLogFilter]]]]:
-    async def caller(*args: Any, **kwargs: Any) -> Union[RPCResponse, AsyncLogFilter]:
+) -> Callable[
+    ...,
+    Coroutine[
+        Any,
+        Any,
+        Optional[Union[RPCResponse, FormattedEthSubscriptionResponse, AsyncLogFilter]],
+    ],
+]:
+    async def caller(
+        *args: Any, **kwargs: Any
+    ) -> Union[RPCResponse, FormattedEthSubscriptionResponse, AsyncLogFilter]:
         try:
             (method_str, params), response_formatters = method.process_params(
                 module, *args, **kwargs
@@ -131,31 +141,17 @@ def retrieve_async_method_call_fn(
             return AsyncLogFilter(eth_module=module, filter_id=err.filter_id)
 
         if isinstance(async_w3.provider, PersistentConnectionProvider):
-            provider = async_w3.provider
-            cache_key = provider._request_processor.cache_request_information(
-                cast(RPCEndpoint, method_str), params, response_formatters
+            return await async_w3.manager.socket_request(
+                cast(RPCEndpoint, method_str),
+                params,
+                response_formatters=response_formatters,
             )
-
-            try:
-                method_str = cast(RPCEndpoint, method_str)
-                return await async_w3.manager.socket_request(method_str, params)
-            except Exception as e:
-                if (
-                    cache_key is not None
-                    and cache_key
-                    in provider._request_processor._request_information_cache
-                ):
-                    provider._request_processor.pop_cached_request_information(
-                        cache_key
-                    )
-                raise e
         else:
             (
                 result_formatters,
                 error_formatters,
                 null_result_formatters,
             ) = response_formatters
-
             result = await async_w3.manager.coro_request(
                 method_str, params, error_formatters, null_result_formatters
             )