web3 7.7.0__py3-none-any.whl → 7.9.0__py3-none-any.whl

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/providers/async_base.py

@@ -77,7 +77,8 @@ class AsyncBaseProvider:
 
     _is_batching: bool = False
     _batch_request_func_cache: Tuple[
-        Tuple[Middleware, ...], Callable[..., Coroutine[Any, Any, List[RPCResponse]]]
+        Tuple[Middleware, ...],
+        Callable[..., Coroutine[Any, Any, Union[List[RPCResponse], RPCResponse]]],
     ] = (None, None)
 
     is_async = True
@@ -119,7 +120,7 @@ class AsyncBaseProvider:
 
     async def batch_request_func(
         self, async_w3: "AsyncWeb3", middleware_onion: MiddlewareOnion
-    ) -> Callable[..., Coroutine[Any, Any, List[RPCResponse]]]:
+    ) -> Callable[..., Coroutine[Any, Any, Union[List[RPCResponse], RPCResponse]]]:
         middleware: Tuple[Middleware, ...] = middleware_onion.as_tuple_of_middleware()
 
         cache_key = self._batch_request_func_cache[0]
@@ -141,8 +142,8 @@ class AsyncBaseProvider:
 
     async def make_batch_request(
         self, requests: List[Tuple[RPCEndpoint, Any]]
-    ) -> List[RPCResponse]:
-        raise NotImplementedError("Only AsyncHTTPProvider supports this method")
+    ) -> Union[List[RPCResponse], RPCResponse]:
+        raise NotImplementedError("Providers must implement this method")
 
     async def is_connected(self, show_traceback: bool = False) -> bool:
         raise NotImplementedError("Providers must implement this method")

web3/providers/base.py

@@ -118,7 +118,7 @@ class JSONBaseProvider(BaseProvider):
 
     _is_batching: bool = False
     _batch_request_func_cache: Tuple[
-        Tuple[Middleware, ...], Callable[..., List[RPCResponse]]
+        Tuple[Middleware, ...], Callable[..., Union[List[RPCResponse], RPCResponse]]
     ] = (None, None)
 
     def __init__(self, **kwargs: Any) -> None:
@@ -168,7 +168,7 @@ class JSONBaseProvider(BaseProvider):
 
     def batch_request_func(
         self, w3: "Web3", middleware_onion: MiddlewareOnion
-    ) -> Callable[..., List[RPCResponse]]:
+    ) -> Callable[..., Union[List[RPCResponse], RPCResponse]]:
         middleware: Tuple[Middleware, ...] = middleware_onion.as_tuple_of_middleware()
 
         cache_key = self._batch_request_func_cache[0]
@@ -199,5 +199,5 @@ class JSONBaseProvider(BaseProvider):
 
     def make_batch_request(
         self, requests: List[Tuple[RPCEndpoint, Any]]
-    ) -> List[RPCResponse]:
+    ) -> Union[List[RPCResponse], RPCResponse]:
         raise NotImplementedError("Providers must implement this method")

web3/providers/persistent/persistent.py

@@ -33,6 +33,9 @@ from web3._utils.caching.caching_utils import (
     async_handle_recv_caching,
     async_handle_send_caching,
 )
+from web3._utils.validation import (
+    validate_rpc_response_and_raise_if_error,
+)
 from web3.exceptions import (
     PersistentConnectionClosedOK,
     ProviderConnectionError,
@@ -302,6 +305,27 @@ class PersistentConnectionProvider(AsyncJSONBaseProvider, ABC):
             TaskNotRunning(message_listener_task)
         )
 
+    def _raise_stray_errors_from_cache(self) -> None:
+        """
+        Check the request response cache for any errors not tied to current requests
+        and raise them if found.
+        """
+        if not self._is_batching:
+            for (
+                response
+            ) in self._request_processor._request_response_cache._data.values():
+                request = (
+                    self._request_processor._request_information_cache.get_cache_entry(
+                        generate_cache_key(response["id"])
+                    )
+                )
+                if "error" in response and request is None:
+                    # if we find an error response in the cache without a corresponding
+                    # request, raise the error
+                    validate_rpc_response_and_raise_if_error(
+                        response, None, logger=self.logger
+                    )
+
     async def _message_listener(self) -> None:
         self.logger.info(
             f"{self.__class__.__qualname__} listener background task started. Storing "
@@ -327,6 +351,7 @@ class PersistentConnectionProvider(AsyncJSONBaseProvider, ABC):
                 await self._request_processor.cache_raw_response(
                     response, subscription=subscription
                 )
+                self._raise_stray_errors_from_cache()
             except PersistentConnectionClosedOK as e:
                 self.logger.info(
                     "Message listener background task has ended gracefully: "
@@ -376,6 +401,10 @@ class PersistentConnectionProvider(AsyncJSONBaseProvider, ABC):
             request_cache_key = generate_cache_key(request_id)
 
             while True:
+                # check if an exception was recorded in the listener task and raise
+                # it in the main loop if so
+                self._handle_listener_task_exceptions()
+
                 if request_cache_key in self._request_processor._request_response_cache:
                     self.logger.debug(
                         f"Popping response for id {request_id} from cache."
@@ -385,9 +414,6 @@ class PersistentConnectionProvider(AsyncJSONBaseProvider, ABC):
                     )
                     return popped_response
                 else:
-                    # check if an exception was recorded in the listener task and raise
-                    # it in the main loop if so
-                    self._handle_listener_task_exceptions()
                     await asyncio.sleep(0)
 
         try:

web3/providers/persistent/request_processor.py

@@ -6,6 +6,7 @@ from typing import (
     Callable,
     Dict,
     Generic,
+    List,
     Optional,
     Tuple,
     TypeVar,
@@ -270,6 +271,15 @@ class RequestProcessor:
 
     # raw response cache
 
+    def _is_batch_response(
+        self, raw_response: Union[List[RPCResponse], RPCResponse]
+    ) -> bool:
+        return isinstance(raw_response, list) or (
+            isinstance(raw_response, dict)
+            and raw_response.get("id") is None
+            and self._provider._is_batching
+        )
+
     async def cache_raw_response(
         self, raw_response: Any, subscription: bool = False
     ) -> None:
@@ -296,7 +306,7 @@ class RequestProcessor:
                 # otherwise, put it in the subscription response queue so a response
                 # can be yielded by the message stream
                 await self._subscription_response_queue.put(raw_response)
-        elif isinstance(raw_response, list):
+        elif self._is_batch_response(raw_response):
             # Since only one batch should be in the cache at all times, we use a
             # constant cache key for the batch response.
             cache_key = generate_cache_key(BATCH_REQUEST_ID)

web3/providers/persistent/subscription_manager.py

@@ -69,6 +69,23 @@ class SubscriptionManager:
     def _remove_subscription(self, subscription: EthSubscription[Any]) -> None:
         self._subscription_container.remove_subscription(subscription)
 
+    def _validate_and_normalize_label(self, subscription: EthSubscription[Any]) -> None:
+        if subscription.label == subscription._default_label:
+            # if no custom label was provided, generate a unique label
+            i = 2
+            while self.get_by_label(subscription._label) is not None:
+                subscription._label = f"{subscription._default_label}#{i}"
+                i += 1
+        else:
+            if (
+                subscription._label
+                in self._subscription_container.subscriptions_by_label
+            ):
+                raise Web3ValueError(
+                    "Subscription label already exists. Subscriptions must have unique "
+                    f"labels.\n    label: {subscription._label}"
+                )
+
     @property
     def subscriptions(self) -> List[EthSubscription[Any]]:
         return self._subscription_container.subscriptions
@@ -100,16 +117,8 @@ class SubscriptionManager:
         :return:
         """
         if isinstance(subscriptions, EthSubscription):
-            if (
-                subscriptions.label
-                in self._subscription_container.subscriptions_by_label
-            ):
-                raise Web3ValueError(
-                    "Subscription label already exists. Subscriptions must have "
-                    f"unique labels.\n    label: {subscriptions.label}"
-                )
-
             subscriptions.manager = self
+            self._validate_and_normalize_label(subscriptions)
             sub_id = await self._w3.eth._subscribe(*subscriptions.subscription_params)
             subscriptions._id = sub_id
             self._add_subscription(subscriptions)
@@ -124,34 +133,91 @@ class SubscriptionManager:
 
             sub_ids: List[HexStr] = []
             for sub in subscriptions:
-                await self.subscribe(sub)
+                sub_ids.append(await self.subscribe(sub))
             return sub_ids
         raise Web3TypeError("Expected a Subscription or a sequence of Subscriptions.")
 
-    async def unsubscribe(self, subscription: EthSubscription[Any]) -> bool:
+    @overload
+    async def unsubscribe(self, subscriptions: EthSubscription[Any]) -> bool:
+        ...
+
+    @overload
+    async def unsubscribe(self, subscriptions: HexStr) -> bool:
+        ...
+
+    @overload
+    async def unsubscribe(
+        self,
+        subscriptions: Sequence[Union[EthSubscription[Any], HexStr]],
+    ) -> bool:
+        ...
+
+    async def unsubscribe(
+        self,
+        subscriptions: Union[
+            EthSubscription[Any],
+            HexStr,
+            Sequence[Union[EthSubscription[Any], HexStr]],
+        ],
+    ) -> bool:
         """
-        Used to unsubscribe from a subscription.
+        Used to unsubscribe from one or multiple subscriptions.
 
-        :param subscription: The subscription to unsubscribe from.
-        :type subscription: EthSubscription
-        :return: ``True`` if unsubscribing was successful, ``False`` otherwise.
+        :param subscriptions: The subscription(s) to unsubscribe from.
+        :type subscriptions: Union[EthSubscription, Sequence[EthSubscription], HexStr,
+            Sequence[HexStr]]
+        :return: ``True`` if unsubscribing to all was successful, ``False`` otherwise
+            with a warning.
         :rtype: bool
         """
-        if subscription not in self.subscriptions:
-            raise Web3ValueError(
-                "Subscription not found or is not being managed by the subscription "
-                f"manager.\n    label: {subscription.label}\n    id: {subscription._id}"
-            )
-        if await self._w3.eth._unsubscribe(subscription.id):
-            self._remove_subscription(subscription)
-            self.logger.info(
-                "Successfully unsubscribed from subscription:\n    "
-                f"label: {subscription.label}\n    id: {subscription.id}"
-            )
-            if len(self._subscription_container.handler_subscriptions) == 0:
-                queue = self._provider._request_processor._handler_subscription_queue
-                await queue.put(SubscriptionProcessingFinished())
-            return True
+        if isinstance(subscriptions, EthSubscription) or isinstance(subscriptions, str):
+            if isinstance(subscriptions, str):
+                subscription_id = subscriptions
+                subscriptions = self.get_by_id(subscription_id)
+                if subscriptions is None:
+                    raise Web3ValueError(
+                        "Subscription not found or is not being managed by the "
+                        f"subscription manager.\n    id: {subscription_id}"
+                    )
+
+            if subscriptions not in self.subscriptions:
+                raise Web3ValueError(
+                    "Subscription not found or is not being managed by the "
+                    "subscription manager.\n    "
+                    f"label: {subscriptions.label}\n    id: {subscriptions._id}"
+                )
+
+            if await self._w3.eth._unsubscribe(subscriptions.id):
+                self._remove_subscription(subscriptions)
+                self.logger.info(
+                    "Successfully unsubscribed from subscription:\n    "
+                    f"label: {subscriptions.label}\n    id: {subscriptions.id}"
+                )
+
+                if len(self._subscription_container.handler_subscriptions) == 0:
+                    queue = (
+                        self._provider._request_processor._handler_subscription_queue
+                    )
+                    await queue.put(SubscriptionProcessingFinished())
+                return True
+
+        elif isinstance(subscriptions, Sequence):
+            if len(subscriptions) == 0:
+                raise Web3ValueError("No subscriptions provided.")
+
+            unsubscribed: List[bool] = []
+            # re-create the subscription list to prevent modifying the original list
+            # in case ``subscription_manager.subscriptions`` was passed in directly
+            subs = [sub for sub in subscriptions]
+            for sub in subs:
+                if isinstance(sub, str):
+                    sub = HexStr(sub)
+                unsubscribed.append(await self.unsubscribe(sub))
+            return all(unsubscribed)
+
+        self.logger.warning(
+            f"Failed to unsubscribe from subscription\n    subscription={subscriptions}"
+        )
         return False
 
     async def unsubscribe_all(self) -> bool:
@@ -163,7 +229,9 @@ class SubscriptionManager:
         :rtype: bool
         """
         unsubscribed = [
-            await self.unsubscribe(sub) for sub in self.subscriptions.copy()
+            await self.unsubscribe(sub)
+            # use copy to prevent modifying the list while iterating over it
+            for sub in self.subscriptions.copy()
         ]
         if all(unsubscribed):
             self.logger.info("Successfully unsubscribed from all subscriptions.")
@@ -186,15 +254,15 @@ class SubscriptionManager:
         :type run_forever: bool
         :return: None
         """
-        if not self._subscription_container.handler_subscriptions:
+        if not self._subscription_container.handler_subscriptions and not run_forever:
             self.logger.warning(
                 "No handler subscriptions found. Subscription handler did not run."
             )
             return
 
         queue = self._provider._request_processor._handler_subscription_queue
-        try:
-            while run_forever or self._subscription_container.handler_subscriptions:
+        while run_forever or self._subscription_container.handler_subscriptions:
+            try:
                 response = cast(RPCResponse, await queue.get())
                 formatted_sub_response = cast(
                     FormattedEthSubscriptionResponse,
@@ -216,18 +284,20 @@ class SubscriptionManager:
                             **sub._handler_context,
                         )
                     )
-        except SubscriptionProcessingFinished:
-            self.logger.info(
-                "All handler subscriptions have been unsubscribed from. "
-                "Stopping subscription handling."
-            )
-        except TaskNotRunning:
-            await asyncio.sleep(0)
-            self._provider._handle_listener_task_exceptions()
-            self.logger.error(
-                "Message listener background task for the provider has stopped "
-                "unexpectedly. Stopping subscription handling."
-            )
+            except SubscriptionProcessingFinished:
+                if not run_forever:
+                    self.logger.info(
+                        "All handler subscriptions have been unsubscribed from. "
+                        "Stopping subscription handling."
+                    )
+                    break
+            except TaskNotRunning:
+                await asyncio.sleep(0)
+                self._provider._handle_listener_task_exceptions()
+                self.logger.error(
+                    "Message listener background task for the provider has stopped "
+                    "unexpectedly. Stopping subscription handling."
+                )
 
         # no active handler subscriptions, clear the handler subscription queue
         self._provider._request_processor._reset_handler_subscription_queue()

web3/providers/persistent/websocket.py

@@ -63,6 +63,8 @@ class WebSocketProvider(PersistentConnectionProvider):
         self,
         endpoint_uri: Optional[Union[URI, str]] = None,
         websocket_kwargs: Optional[Dict[str, Any]] = None,
+        # uses binary frames by default
+        use_text_frames: Optional[bool] = False,
         # `PersistentConnectionProvider` kwargs can be passed through
         **kwargs: Any,
     ) -> None:
@@ -71,6 +73,7 @@ class WebSocketProvider(PersistentConnectionProvider):
             URI(endpoint_uri) if endpoint_uri is not None else get_default_endpoint()
         )
         super().__init__(**kwargs)
+        self.use_text_frames = use_text_frames
         self._ws: Optional[WebSocketClientProtocol] = None
 
         if not any(
@@ -118,9 +121,11 @@ class WebSocketProvider(PersistentConnectionProvider):
                 "Connection to websocket has not been initiated for the provider."
             )
 
-        await asyncio.wait_for(
-            self._ws.send(request_data), timeout=self.request_timeout
-        )
+        payload: Union[bytes, str] = request_data
+        if self.use_text_frames:
+            payload = request_data.decode("utf-8")
+
+        await asyncio.wait_for(self._ws.send(payload), timeout=self.request_timeout)
 
     async def socket_recv(self) -> RPCResponse:
         raw_response = await self._ws.recv()

web3/providers/rpc/async_rpc.py

@@ -168,15 +168,20 @@ class AsyncHTTPProvider(AsyncJSONBaseProvider):
 
     async def make_batch_request(
         self, batch_requests: List[Tuple[RPCEndpoint, Any]]
-    ) -> List[RPCResponse]:
+    ) -> Union[List[RPCResponse], RPCResponse]:
         self.logger.debug(f"Making batch request HTTP - uri: `{self.endpoint_uri}`")
         request_data = self.encode_batch_rpc_request(batch_requests)
         raw_response = await self._request_session_manager.async_make_post_request(
             self.endpoint_uri, request_data, **self.get_request_kwargs()
         )
         self.logger.debug("Received batch response HTTP.")
-        responses_list = cast(List[RPCResponse], self.decode_rpc_response(raw_response))
-        return sort_batch_response_by_response_ids(responses_list)
+        response = self.decode_rpc_response(raw_response)
+        if not isinstance(response, list):
+            # RPC errors return only one response with the error object
+            return response
+        return sort_batch_response_by_response_ids(
+            cast(List[RPCResponse], sort_batch_response_by_response_ids(response))
+        )
 
     async def disconnect(self) -> None:
         cache = self._request_session_manager.session_cache

web3/providers/rpc/rpc.py

@@ -176,12 +176,17 @@ class HTTPProvider(JSONBaseProvider):
 
     def make_batch_request(
         self, batch_requests: List[Tuple[RPCEndpoint, Any]]
-    ) -> List[RPCResponse]:
+    ) -> Union[List[RPCResponse], RPCResponse]:
         self.logger.debug(f"Making batch request HTTP, uri: `{self.endpoint_uri}`")
         request_data = self.encode_batch_rpc_request(batch_requests)
         raw_response = self._request_session_manager.make_post_request(
             self.endpoint_uri, request_data, **self.get_request_kwargs()
         )
         self.logger.debug("Received batch response HTTP.")
-        responses_list = cast(List[RPCResponse], self.decode_rpc_response(raw_response))
-        return sort_batch_response_by_response_ids(responses_list)
+        response = self.decode_rpc_response(raw_response)
+        if not isinstance(response, list):
+            # RPC errors return only one response with the error object
+            return response
+        return sort_batch_response_by_response_ids(
+            cast(List[RPCResponse], sort_batch_response_by_response_ids(response))
+        )

web3/types.py

@@ -36,13 +36,9 @@ from web3._utils.compat import (
 )
 
 if TYPE_CHECKING:
-    from web3.contract.async_contract import (  # noqa: F401
-        AsyncContractEvent,
-        AsyncContractFunction,
-    )
-    from web3.contract.contract import (  # noqa: F401
-        ContractEvent,
-        ContractFunction,
+    from web3.contract.base_contract import (
+        BaseContractEvent,
+        BaseContractFunction,
     )
     from web3.main import (  # noqa: F401
         AsyncWeb3,
@@ -201,10 +197,10 @@ class LogReceipt(TypedDict):
     blockNumber: BlockNumber
     data: HexBytes
     logIndex: int
+    removed: bool
     topics: Sequence[HexBytes]
     transactionHash: HexBytes
     transactionIndex: int
-    removed: bool
 
 
 class SubscriptionResponse(TypedDict):
@@ -301,10 +297,13 @@ class CreateAccessListResponse(TypedDict):
 
 
 MakeRequestFn = Callable[[RPCEndpoint, Any], RPCResponse]
-MakeBatchRequestFn = Callable[[List[Tuple[RPCEndpoint, Any]]], List[RPCResponse]]
+MakeBatchRequestFn = Callable[
+    [List[Tuple[RPCEndpoint, Any]]], Union[List[RPCResponse], RPCResponse]
+]
 AsyncMakeRequestFn = Callable[[RPCEndpoint, Any], Coroutine[Any, Any, RPCResponse]]
 AsyncMakeBatchRequestFn = Callable[
-    [List[Tuple[RPCEndpoint, Any]]], Coroutine[Any, Any, List[RPCResponse]]
+    [List[Tuple[RPCEndpoint, Any]]],
+    Coroutine[Any, Any, Union[List[RPCResponse], RPCResponse]],
 ]
 
 
@@ -337,7 +336,7 @@ class StateOverrideParams(TypedDict, total=False):
     stateDiff: Optional[Dict[HexStr, HexStr]]
 
 
-StateOverride = Dict[ChecksumAddress, StateOverrideParams]
+StateOverride = Dict[Union[str, Address, ChecksumAddress], StateOverrideParams]
 
 
 GasPriceStrategy = Union[
@@ -568,6 +567,30 @@ class OpcodeTrace(TypedDict, total=False):
     structLogs: List[StructLog]
 
 
+class BlockStateCallV1(TypedDict):
+    blockOverrides: NotRequired[BlockData]
+    stateOverrides: NotRequired[StateOverride]
+    calls: Sequence[TxParams]
+
+
+class SimulateV1Payload(TypedDict):
+    blockStateCalls: Sequence[BlockStateCallV1]
+    validation: NotRequired[bool]
+    traceTransfers: NotRequired[bool]
+
+
+class SimulateV1CallResult(TypedDict):
+    returnData: HexBytes
+    logs: Sequence[LogReceipt]
+    gasUsed: int
+    status: int
+    error: NotRequired[RPCError]
+
+
+class SimulateV1Result(BlockData):
+    calls: Sequence[SimulateV1CallResult]
+
+
 #
 # web3.geth types
 #
@@ -581,8 +604,8 @@ class GethWallet(TypedDict):
 
 # Contract types
 
-TContractFn = TypeVar("TContractFn", "ContractFunction", "AsyncContractFunction")
-TContractEvent = TypeVar("TContractEvent", "ContractEvent", "AsyncContractEvent")
+TContractFn = TypeVar("TContractFn", bound="BaseContractFunction")
+TContractEvent = TypeVar("TContractEvent", bound="BaseContractEvent")
 
 
 # Tracing types

web3/utils/subscriptions.py

@@ -114,6 +114,10 @@ class EthSubscription(Generic[TSubscriptionResult]):
         self._label = label
         self.handler_call_count = 0
 
+    @property
+    def _default_label(self) -> str:
+        return f"{self.__class__.__name__}{self.subscription_params}"
+
     @classmethod
     def _create_type_aware_subscription(
         cls,
@@ -170,7 +174,7 @@ class EthSubscription(Generic[TSubscriptionResult]):
     @property
     def label(self) -> str:
         if not self._label:
-            self._label = f"{self.__class__.__name__}{self.subscription_params}"
+            self._label = self._default_label
         return self._label
 
     @property

{web3-7.7.0.dist-info → web3-7.9.0.dist-info}/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016-2024 The Ethereum Foundation
+Copyright (c) 2016-2025 The Ethereum Foundation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal