web3 7.12.1__py3-none-any.whl → 7.14.0__py3-none-any.whl

web3/middleware/formatting.py

@@ -16,6 +16,7 @@ from eth_utils.toolz import (
 )
 
 from web3.exceptions import (
+    BadResponseFormat,
     Web3ValueError,
 )
 from web3.middleware.base import (
@@ -77,7 +78,12 @@ def _apply_response_formatters(
                 response, response_type, method_response_formatter(appropriate_response)
             )
 
-    if response.get("result") is not None and method in result_formatters:
+    if not isinstance(response, dict):
+        raise BadResponseFormat(
+            "Malformed response: expected a valid JSON-RPC response object, got: "
+            "`{}`".format(response)
+        )
+    elif response.get("result") is not None and method in result_formatters:
         return _format_response("result", result_formatters[method])
     elif (
         # eth_subscription responses
@@ -94,7 +100,7 @@ def _apply_response_formatters(
 
 SYNC_FORMATTERS_BUILDER = Callable[["Web3", RPCEndpoint], FormattersDict]
 ASYNC_FORMATTERS_BUILDER = Callable[
-    ["AsyncWeb3", RPCEndpoint], Coroutine[Any, Any, FormattersDict]
+    ["AsyncWeb3[Any]", RPCEndpoint], Coroutine[Any, Any, FormattersDict]
 ]
 
 
@@ -108,7 +114,7 @@ class FormattingMiddlewareBuilder(Web3MiddlewareBuilder):
     @staticmethod
     @curry
     def build(
-        w3: Union["AsyncWeb3", "Web3"],
+        w3: Union["Web3", "AsyncWeb3[Any]"],
         # formatters option:
         request_formatters: Optional[Formatters] = None,
         result_formatters: Optional[Formatters] = None,
@@ -180,7 +186,7 @@ class FormattingMiddlewareBuilder(Web3MiddlewareBuilder):
             formatters = merge(
                 FORMATTER_DEFAULTS,
                 await self.async_formatters_builder(
-                    cast("AsyncWeb3", self._w3), method
+                    cast("AsyncWeb3[Any]", self._w3), method
                 ),
             )
             self.request_formatters = formatters.pop("request_formatters")
@@ -198,7 +204,7 @@ class FormattingMiddlewareBuilder(Web3MiddlewareBuilder):
             formatters = merge(
                 FORMATTER_DEFAULTS,
                 await self.async_formatters_builder(
-                    cast("AsyncWeb3", self._w3), method
+                    cast("AsyncWeb3[Any]", self._w3), method
                 ),
             )
             self.result_formatters = formatters["result_formatters"]

web3/middleware/gas_price_strategy.py

@@ -106,7 +106,7 @@ class GasPriceStrategyMiddleware(Web3Middleware):
     async def async_request_processor(self, method: RPCEndpoint, params: Any) -> Any:
         if method == "eth_sendTransaction":
             transaction = params[0]
-            w3 = cast("AsyncWeb3", self._w3)
+            w3 = cast("AsyncWeb3[Any]", self._w3)
             generated_gas_price = w3.eth.generate_gas_price(transaction)
             latest_block = await w3.eth.get_block("latest")
             transaction = validate_transaction_params(

web3/middleware/names.py

@@ -53,7 +53,7 @@ def _is_logs_subscription_with_optional_args(method: RPCEndpoint, params: Any) -
 
 
 async def async_format_all_ens_names_to_address(
-    async_web3: "AsyncWeb3",
+    async_web3: "AsyncWeb3[Any]",
     abi_types_for_method: Sequence[Any],
     data: Sequence[Any],
 ) -> Sequence[Any]:
@@ -69,7 +69,7 @@ async def async_format_all_ens_names_to_address(
 
 
 async def async_apply_ens_to_address_conversion(
-    async_web3: "AsyncWeb3",
+    async_web3: "AsyncWeb3[Any]",
     params: Any,
     abi_types_for_method: Union[Sequence[str], Dict[str, str]],
 ) -> Any:
@@ -125,7 +125,7 @@ class ENSNameToAddressMiddleware(Web3Middleware):
                 # eth_subscribe optional logs params are unique.
                 # Handle them separately here.
                 (formatted_dict,) = await async_apply_ens_to_address_conversion(
-                    cast("AsyncWeb3", self._w3),
+                    cast("AsyncWeb3[Any]", self._w3),
                     (params[1],),
                     {
                         "address": "address",
@@ -136,7 +136,7 @@ class ENSNameToAddressMiddleware(Web3Middleware):
 
             else:
                 params = await async_apply_ens_to_address_conversion(
-                    cast("AsyncWeb3", self._w3),
+                    cast("AsyncWeb3[Any]", self._w3),
                     params,
                     abi_types_for_method,
                 )

web3/middleware/signing.py

@@ -93,7 +93,7 @@ _PrivateKey = Union[LocalAccount, PrivateKey, HexStr, bytes]
 
 @to_dict
 def gen_normalized_accounts(
-    val: Union[_PrivateKey, Collection[_PrivateKey]]
+    val: Union[_PrivateKey, Collection[_PrivateKey]],
 ) -> Iterable[Tuple[ChecksumAddress, LocalAccount]]:
     if isinstance(
         val,
@@ -158,7 +158,7 @@ class SignAndSendRawMiddlewareBuilder(Web3MiddlewareBuilder):
     @curry
     def build(
         private_key_or_account: Union[_PrivateKey, Collection[_PrivateKey]],
-        w3: Union["Web3", "AsyncWeb3"],
+        w3: Union["Web3", "AsyncWeb3[Any]"],
     ) -> "SignAndSendRawMiddlewareBuilder":
         middleware = SignAndSendRawMiddlewareBuilder(w3)
         middleware._accounts = gen_normalized_accounts(private_key_or_account)
@@ -199,7 +199,7 @@ class SignAndSendRawMiddlewareBuilder(Web3MiddlewareBuilder):
             return method, params
 
         else:
-            w3 = cast("AsyncWeb3", self._w3)
+            w3 = cast("AsyncWeb3[Any]", self._w3)
 
             formatted_transaction = format_transaction(params[0])
             filled_transaction = await async_fill_transaction_defaults(

web3/middleware/stalecheck.py

@@ -51,7 +51,7 @@ class StalecheckMiddlewareBuilder(Web3MiddlewareBuilder):
     @curry
     def build(
         allowable_delay: int,
-        w3: Union["Web3", "AsyncWeb3"],
+        w3: Union["Web3", "AsyncWeb3[Any]"],
         skip_stalecheck_for_methods: Collection[str] = SKIP_STALECHECK_FOR_METHODS,
     ) -> Web3Middleware:
         if allowable_delay <= 0:
@@ -82,7 +82,7 @@ class StalecheckMiddlewareBuilder(Web3MiddlewareBuilder):
     async def async_request_processor(self, method: "RPCEndpoint", params: Any) -> Any:
         if method not in self.skip_stalecheck_for_methods:
             if not _is_fresh(self.cache["latest"], self.allowable_delay):
-                w3 = cast("AsyncWeb3", self._w3)
+                w3 = cast("AsyncWeb3[Any]", self._w3)
                 latest = await w3.eth.get_block("latest")
 
                 if _is_fresh(latest, self.allowable_delay):

web3/middleware/validation.py

@@ -121,7 +121,7 @@ def _chain_id_validator(web3_chain_id: int) -> Callable[..., Any]:
 
 
 def _build_formatters_dict(
-    request_formatters: Dict[RPCEndpoint, Any]
+    request_formatters: Dict[RPCEndpoint, Any],
 ) -> FormattersDict:
     return dict(
         request_formatters=request_formatters,
@@ -149,7 +149,7 @@ def build_method_validators(w3: "Web3", method: RPCEndpoint) -> FormattersDict:
 
 
 async def async_build_method_validators(
-    async_w3: "AsyncWeb3", method: RPCEndpoint
+    async_w3: "AsyncWeb3[Any]", method: RPCEndpoint
 ) -> FormattersDict:
     request_formatters: Formatters = {}
     if RPCEndpoint(method) in METHODS_TO_VALIDATE:

web3/module.py

@@ -60,7 +60,7 @@ TReturn = TypeVar("TReturn")
 
 @curry
 def retrieve_request_information_for_batching(
-    w3: Union["AsyncWeb3", "Web3"],
+    w3: Union["AsyncWeb3[Any]", "Web3"],
     module: "Module",
     method: Method[Callable[..., Any]],
 ) -> Union[
@@ -119,7 +119,7 @@ def retrieve_blocking_method_call_fn(
 
 @curry
 def retrieve_async_method_call_fn(
-    async_w3: "AsyncWeb3",
+    async_w3: "AsyncWeb3[Any]",
     module: "Module",
     method: Method[Callable[..., Any]],
 ) -> Callable[
@@ -167,7 +167,7 @@ def retrieve_async_method_call_fn(
 class Module:
     is_async = False
 
-    def __init__(self, w3: Union["AsyncWeb3", "Web3"]) -> None:
+    def __init__(self, w3: Union["AsyncWeb3[Any]", "Web3"]) -> None:
         if self.is_async:
             self.retrieve_caller_fn = retrieve_async_method_call_fn(w3, self)
         else:

web3/providers/async_base.py

@@ -112,7 +112,7 @@ class AsyncBaseProvider:
         return self._batching_context.get() is not None
 
     async def request_func(
-        self, async_w3: "AsyncWeb3", middleware_onion: MiddlewareOnion
+        self, async_w3: "AsyncWeb3[Any]", middleware_onion: MiddlewareOnion
     ) -> Callable[..., Coroutine[Any, Any, RPCResponse]]:
         middleware: Tuple[Middleware, ...] = middleware_onion.as_tuple_of_middleware()
 
@@ -129,7 +129,7 @@ class AsyncBaseProvider:
         return self._request_func_cache[-1]
 
     async def batch_request_func(
-        self, async_w3: "AsyncWeb3", middleware_onion: MiddlewareOnion
+        self, async_w3: "AsyncWeb3[Any]", middleware_onion: MiddlewareOnion
     ) -> Callable[..., Coroutine[Any, Any, Union[List[RPCResponse], RPCResponse]]]:
         middleware: Tuple[Middleware, ...] = middleware_onion.as_tuple_of_middleware()
 

web3/providers/base.py

@@ -192,9 +192,9 @@ class JSONBaseProvider(BaseProvider):
                 # type ignore bc in order to wrap the method, we have to call
                 # `wrap_make_batch_request` with the accumulator_fn as the argument
                 # which breaks the type hinting for this particular case.
-                accumulator_fn = initialized.wrap_make_batch_request(
+                accumulator_fn = initialized.wrap_make_batch_request(  # type: ignore
                     accumulator_fn
-                )  # type: ignore  # noqa: E501
+                )
             self._batch_request_func_cache = (middleware, accumulator_fn)
 
         return self._batch_request_func_cache[-1]

web3/providers/eth_tester/defaults.py

@@ -116,7 +116,7 @@ def call_eth_tester(
 
 
 def without_eth_tester(
-    fn: Callable[[TParams], TReturn]
+    fn: Callable[[TParams], TReturn],
 ) -> Callable[["EthereumTester", TParams], TReturn]:
     # workaround for: https://github.com/pytoolz/cytoolz/issues/103
     # @functools.wraps(fn)
@@ -127,7 +127,7 @@ def without_eth_tester(
 
 
 def without_params(
-    fn: Callable[[TParams], TReturn]
+    fn: Callable[[TParams], TReturn],
 ) -> Callable[["EthereumTester", TParams], TReturn]:
     # workaround for: https://github.com/pytoolz/cytoolz/issues/103
     # @functools.wraps(fn)

web3/providers/eth_tester/main.py

@@ -82,7 +82,7 @@ class AsyncEthereumTesterProvider(AsyncBaseProvider):
         self.api_endpoints = API_ENDPOINTS
 
     async def request_func(
-        self, async_w3: "AsyncWeb3", middleware_onion: "MiddlewareOnion"
+        self, async_w3: "AsyncWeb3[Any]", middleware_onion: "MiddlewareOnion"
     ) -> Callable[..., Coroutine[Any, Any, RPCResponse]]:
         # override the request_func to add the ethereum_tester_middleware
 

web3/providers/eth_tester/middleware.py

@@ -376,7 +376,7 @@ def fill_default(
 
 
 async def async_guess_from(
-    async_w3: "AsyncWeb3", _: TxParams
+    async_w3: "AsyncWeb3[Any]", _: TxParams
 ) -> Optional[ChecksumAddress]:
     accounts = await async_w3.eth.accounts
     if accounts is not None and len(accounts) > 0:
@@ -388,7 +388,7 @@ async def async_guess_from(
 async def async_fill_default(
     field: str,
     guess_func: Callable[..., Any],
-    async_w3: "AsyncWeb3",
+    async_w3: "AsyncWeb3[Any]",
     transaction: TxParams,
 ) -> TxParams:
     # type ignored b/c TxParams keys must be string literal types

web3/providers/persistent/persistent.py

@@ -106,7 +106,7 @@ class PersistentConnectionProvider(AsyncJSONBaseProvider, ABC):
     # -- cached middleware request/response functions -- #
 
     async def send_func(
-        self, async_w3: "AsyncWeb3", middleware_onion: "MiddlewareOnion"
+        self, async_w3: "AsyncWeb3[Any]", middleware_onion: "MiddlewareOnion"
     ) -> Callable[..., Coroutine[Any, Any, RPCRequest]]:
         """
         Cache the middleware chain for `send`.
@@ -130,7 +130,7 @@ class PersistentConnectionProvider(AsyncJSONBaseProvider, ABC):
         return self._send_func_cache[1]
 
     async def recv_func(
-        self, async_w3: "AsyncWeb3", middleware_onion: "MiddlewareOnion"
+        self, async_w3: "AsyncWeb3[Any]", middleware_onion: "MiddlewareOnion"
     ) -> Any:
         """
         Cache and compose the middleware stack for `recv`.
@@ -156,7 +156,7 @@ class PersistentConnectionProvider(AsyncJSONBaseProvider, ABC):
         return self._recv_func_cache[1]
 
     async def send_batch_func(
-        self, async_w3: "AsyncWeb3", middleware_onion: "MiddlewareOnion"
+        self, async_w3: "AsyncWeb3[Any]", middleware_onion: "MiddlewareOnion"
     ) -> Callable[..., Coroutine[Any, Any, List[RPCRequest]]]:
         middleware = middleware_onion.as_tuple_of_middleware()
         cache_key = hash(tuple(id(mw) for mw in middleware))
@@ -164,7 +164,7 @@ class PersistentConnectionProvider(AsyncJSONBaseProvider, ABC):
         if cache_key != self._send_batch_func_cache[0]:
 
             async def send_func(
-                requests: List[Tuple[RPCEndpoint, Any]]
+                requests: List[Tuple[RPCEndpoint, Any]],
             ) -> List[RPCRequest]:
                 for mw in middleware:
                     initialized = mw(async_w3)
@@ -179,7 +179,7 @@ class PersistentConnectionProvider(AsyncJSONBaseProvider, ABC):
         return self._send_batch_func_cache[1]
 
     async def recv_batch_func(
-        self, async_w3: "AsyncWeb3", middleware_onion: "MiddlewareOnion"
+        self, async_w3: "AsyncWeb3[Any]", middleware_onion: "MiddlewareOnion"
     ) -> Callable[..., Coroutine[Any, Any, List[RPCResponse]]]:
         middleware = middleware_onion.as_tuple_of_middleware()
         cache_key = hash(tuple(id(mw) for mw in middleware))
@@ -376,11 +376,12 @@ class PersistentConnectionProvider(AsyncJSONBaseProvider, ABC):
     ) -> None:
         # Puts a `TaskNotRunning` in appropriate queues to signal the end of the
         # listener task to any listeners relying on the queues.
+        message = "Message listener task has ended."
         self._request_processor._subscription_response_queue.put_nowait(
-            TaskNotRunning(message_listener_task)
+            TaskNotRunning(message_listener_task, message=message)
         )
         self._request_processor._handler_subscription_queue.put_nowait(
-            TaskNotRunning(message_listener_task)
+            TaskNotRunning(message_listener_task, message=message)
         )
 
     def _raise_stray_errors_from_cache(self) -> None:

web3/providers/persistent/persistent_connection.py

@@ -30,7 +30,7 @@ class PersistentConnection:
     via a `AsyncWeb3` instance instantiated with a `PersistentConnectionProvider` class.
     """
 
-    def __init__(self, w3: "AsyncWeb3"):
+    def __init__(self, w3: "AsyncWeb3[Any]"):
         self._manager = w3.manager
         self.provider = cast("PersistentConnectionProvider", self._manager.provider)
 

web3/providers/persistent/subscription_manager.py

@@ -5,6 +5,7 @@ from typing import (
     Any,
     List,
     Sequence,
+    Set,
     Union,
     cast,
     overload,
@@ -15,6 +16,7 @@ from eth_typing import (
 )
 
 from web3.exceptions import (
+    SubscriptionHandlerTaskException,
     SubscriptionProcessingFinished,
     TaskNotRunning,
     Web3TypeError,
@@ -50,19 +52,26 @@ class SubscriptionManager:
     logger: logging.Logger = logging.getLogger(
         "web3.providers.persistent.subscription_manager"
     )
-    total_handler_calls: int = 0
 
-    def __init__(self, w3: "AsyncWeb3") -> None:
+    def __init__(self, w3: "AsyncWeb3[Any]") -> None:
         self._w3 = w3
         self._provider = cast("PersistentConnectionProvider", w3.provider)
         self._subscription_container = SubscriptionContainer()
 
+        # parallelize all subscription handler calls
+        self.parallelize = False
+        self.task_timeout = 1
+        # TODO: can remove quotes from type hints once Python 3.8 support is dropped
+        self._tasks: Set["asyncio.Task[None]"] = set()
+
         # share the subscription container with the request processor so it can separate
         # subscriptions into different queues based on ``sub._handler`` presence
         self._provider._request_processor._subscription_container = (
             self._subscription_container
         )
 
+        self.total_handler_calls: int = 0
+
     def _add_subscription(self, subscription: EthSubscription[Any]) -> None:
         self._subscription_container.add_subscription(subscription)
 
@@ -86,6 +95,35 @@ class SubscriptionManager:
                     f"labels.\n    label: {subscription._label}"
                 )
 
+    # TODO: can remove quotes from type hints once Python 3.8 support is dropped
+    def _handler_task_callback(self, task: "asyncio.Task[None]") -> None:
+        """
+        Callback when a handler task completes. Similar to _message_listener_callback.
+        Puts handler exceptions into the queue to be raised in the main loop, else
+        removes the task from the set of active tasks.
+        """
+        if task.done() and not task.cancelled():
+            try:
+                task.result()
+                self._tasks.discard(task)
+            except Exception as e:
+                self.logger.exception("Subscription handler task raised an exception.")
+                self._provider._request_processor._handler_subscription_queue.put_nowait(  # noqa: E501
+                    SubscriptionHandlerTaskException(task, message=str(e))
+                )
+
+    async def _cleanup_remaining_tasks(self) -> None:
+        """Cancel and clean up all remaining tasks."""
+        if not self._tasks:
+            return
+
+        self.logger.debug("Cleaning up %d remaining tasks...", len(self._tasks))
+        for task in self._tasks:
+            if not task.done():
+                task.cancel()
+
+        self._tasks.clear()
+
     @property
     def subscriptions(self) -> List[EthSubscription[Any]]:
         return self._subscription_container.subscriptions
@@ -281,14 +319,23 @@ class SubscriptionManager:
                     sub_id
                 )
                 if sub:
-                    await sub._handler(
-                        EthSubscriptionContext(
-                            self._w3,
-                            sub,
-                            formatted_sub_response["result"],
-                            **sub._handler_context,
-                        )
+                    sub_context = EthSubscriptionContext(
+                        self._w3,
+                        sub,
+                        formatted_sub_response["result"],
+                        **sub._handler_context,
                     )
+                    if sub.parallelize is True or (
+                        sub.parallelize is None and self.parallelize
+                    ):
+                        # run the handler in a task to allow parallel processing
+                        task = asyncio.create_task(sub._handler(sub_context))
+                        self._tasks.add(task)
+                        task.add_done_callback(self._handler_task_callback)
+                    else:
+                        # await the handler in the main loop to ensure order
+                        await sub._handler(sub_context)
+
             except SubscriptionProcessingFinished:
                 if not run_forever:
                     self.logger.info(
@@ -296,14 +343,20 @@ class SubscriptionManager:
                         "Stopping subscription handling."
                     )
                     break
-            except TaskNotRunning:
-                await asyncio.sleep(0)
-                self._provider._handle_listener_task_exceptions()
+            except SubscriptionHandlerTaskException:
                 self.logger.error(
-                    "Message listener background task for the provider has stopped "
-                    "unexpectedly. Stopping subscription handling."
+                    "An exception occurred in a subscription handler task. "
+                    "Stopping subscription handling."
                 )
+                await self._cleanup_remaining_tasks()
+                raise
+            except TaskNotRunning as e:
+                self.logger.error("Stopping subscription handling: %s", e.message)
+                self._provider._handle_listener_task_exceptions()
                 break
 
         # no active handler subscriptions, clear the handler subscription queue
         self._provider._request_processor._reset_handler_subscription_queue()
+
+        if self._tasks:
+            await self._cleanup_remaining_tasks()

web3/providers/persistent/utils.py

@@ -26,7 +26,7 @@ def persistent_connection_provider_method(message: str = None) -> Callable[...,
 
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
         @functools.wraps(func)
-        def inner(self: "AsyncWeb3", *args: Any, **kwargs: Any) -> Any:
+        def inner(self: "AsyncWeb3[Any]", *args: Any, **kwargs: Any) -> Any:
             nonlocal message
             if message is None:
                 message = (

web3/types.py

@@ -62,6 +62,19 @@ ABIElementIdentifier = Union[str, Type[FallbackFn], Type[ReceiveFn]]
 
 # bytes, hexbytes, or hexstr representing a 32 byte hash
 _Hash32 = Union[Hash32, HexBytes, HexStr]
+
+# --- ``TopicFilter`` type for event log filtering with AND/OR patterns --- #
+# - ``None``: wildcard, matches any value at this position
+# - ``_Hash32``: single topic that must match exactly
+# - ``Sequence[Union[None, _Hash32]]``: OR condition, at least one must match
+# - ``Sequence[Sequence[...]]``: nested OR conditions
+TopicFilter = Union[
+    None,
+    _Hash32,
+    Sequence[Union[None, _Hash32]],
+    Sequence["TopicFilter"],
+]
+
 EnodeURI = NewType("EnodeURI", str)
 ENS = NewType("ENS", str)
 Nonce = NewType("Nonce", int)
@@ -345,7 +358,7 @@ class FilterParams(TypedDict, total=False):
     blockHash: HexBytes
     fromBlock: BlockIdentifier
     toBlock: BlockIdentifier
-    topics: Sequence[Optional[Union[_Hash32, Sequence[_Hash32]]]]
+    topics: Sequence[TopicFilter]
 
 
 class FeeHistory(TypedDict):
@@ -367,7 +380,7 @@ StateOverride = Dict[Union[str, Address, ChecksumAddress], StateOverrideParams]
 
 
 GasPriceStrategy = Union[
-    Callable[["Web3", TxParams], Wei], Callable[["AsyncWeb3", TxParams], Wei]
+    Callable[["Web3", TxParams], Wei], Callable[["AsyncWeb3[Any]", TxParams], Wei]
 ]
 
 
@@ -667,4 +680,4 @@ class LogsSubscriptionArg(TypedDict, total=False):
         ENS,
         Sequence[Union[Address, ChecksumAddress, ENS]],
     ]
-    topics: Sequence[Union[HexStr, Sequence[HexStr]]]
+    topics: Sequence[TopicFilter]