web3 6.20.2__py3-none-any.whl → 7.0.0__py3-none-any.whl

web3/method.py

@@ -10,7 +10,6 @@ from typing import (
     Sequence,
     Tuple,
     Type,
-    TypeVar,
     Union,
 )
 import warnings
@@ -22,6 +21,9 @@ from eth_utils.toolz import (
     pipe,
 )
 
+from web3._utils.batching import (
+    RPC_METHODS_UNSUPPORTED_DURING_BATCH,
+)
 from web3._utils.method_formatters import (
     get_error_formatters,
     get_null_result_formatters,
@@ -32,15 +34,22 @@ from web3._utils.rpc_abi import (
     RPC,
 )
 from web3.exceptions import (
+    MethodNotSupported,
+    Web3TypeError,
     Web3ValidationError,
+    Web3ValueError,
 )
 from web3.types import (
     RPCEndpoint,
+    TFunc,
     TReturn,
 )
 
 if TYPE_CHECKING:
-    from web3 import Web3  # noqa: F401
+    from web3 import (  # noqa: F401
+        PersistentConnectionProvider,
+        Web3,
+    )
     from web3.module import Module  # noqa: F401
 
 
@@ -82,11 +91,9 @@ def default_root_munger(_module: "Module", *args: Any) -> List[Any]:
     return [*args]
 
 
-TFunc = TypeVar("TFunc", bound=Callable[..., Any])
-
-
 class Method(Generic[TFunc]):
-    """Method object for web3 module methods
+    """
+    Method object for web3 module methods
 
     Calls to the Method go through these steps:
 
@@ -146,15 +153,31 @@ class Method(Generic[TFunc]):
         self.is_property = is_property
 
     def __get__(
-        self, obj: Optional["Module"] = None, obj_type: Optional[Type["Module"]] = None
+        self,
+        module: Optional["Module"] = None,
+        _type: Optional[Type["Module"]] = None,
     ) -> TFunc:
-        if obj is None:
-            raise TypeError(
+        self._module = module
+        if module is None:
+            raise Web3TypeError(
                 "Direct calls to methods are not supported. "
-                "Methods must be called from an module instance, "
+                "Methods must be called from a module instance, "
                 "usually attached to a web3 instance."
             )
-        return obj.retrieve_caller_fn(self)
+
+        provider = module.w3.provider
+        if hasattr(provider, "_is_batching") and provider._is_batching:
+            if self.json_rpc_method in RPC_METHODS_UNSUPPORTED_DURING_BATCH:
+                raise MethodNotSupported(
+                    f"Method `{self.json_rpc_method}` is not supported within a batch "
+                    "request."
+                )
+            return module.retrieve_request_information(self)
+        else:
+            return module.retrieve_caller_fn(self)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self.__get__(self._module)(*args, **kwargs)
 
     @property
     def method_selector_fn(
@@ -165,7 +188,7 @@ class Method(Generic[TFunc]):
             return self.json_rpc_method
         elif isinstance(self.json_rpc_method, (str,)):
             return lambda *_: self.json_rpc_method
-        raise ValueError(
+        raise Web3ValueError(
             "``json_rpc_method`` config invalid.  May be a string or function"
         )
 
@@ -218,34 +241,18 @@ class Method(Generic[TFunc]):
 
 class DeprecatedMethod:
     def __init__(
-        self,
-        method: Method[Callable[..., Any]],
-        old_name: Optional[str] = None,
-        new_name: Optional[str] = None,
-        msg: Optional[str] = None,
+        self, method: Method[Callable[..., Any]], old_name: str, new_name: str
     ) -> None:
         self.method = method
         self.old_name = old_name
         self.new_name = new_name
-        self.msg = msg
 
     def __get__(
         self, obj: Optional["Module"] = None, obj_type: Optional[Type["Module"]] = None
     ) -> Any:
-        if self.old_name is not None and self.new_name is not None:
-            if self.msg is not None:
-                raise ValueError(
-                    "Cannot specify `old_name` and `new_name` along with `msg`"
-                )
-
-            message = f"{self.old_name} is deprecated in favor of {self.new_name}"
-        elif self.msg is not None:
-            message = self.msg
-        else:
-            raise ValueError("Must provide either `old_name` and `new_name` or `msg`")
-
         warnings.warn(
-            message,
+            f"{self.old_name} is deprecated in favor of {self.new_name}",
             category=DeprecationWarning,
+            stacklevel=2,
         )
         return self.method.__get__(obj, obj_type)

web3/middleware/__init__.py

@@ -1,133 +1,111 @@
-import functools
 from typing import (
-    Coroutine,
     TYPE_CHECKING,
     Any,
     Callable,
+    Coroutine,
     Sequence,
 )
 
-from web3.types import (
-    AsyncMiddleware,
-    Middleware,
-    RPCEndpoint,
-    RPCResponse,
-)
-
-from .abi import (
-    abi_middleware,
-)
-from .async_cache import (
-    _async_simple_cache_middleware as async_simple_cache_middleware,
-    async_construct_simple_cache_middleware,
-)
 from .attrdict import (
-    async_attrdict_middleware,
-    attrdict_middleware,
-)
-from .buffered_gas_estimate import (
-    async_buffered_gas_estimate_middleware,
-    buffered_gas_estimate_middleware,
+    AttributeDictMiddleware,
 )
-from .cache import (
-    _latest_block_based_cache_middleware as latest_block_based_cache_middleware,
-    _simple_cache_middleware as simple_cache_middleware,
-    _time_based_cache_middleware as time_based_cache_middleware,
-    construct_latest_block_based_cache_middleware,
-    construct_simple_cache_middleware,
-    construct_time_based_cache_middleware,
-)
-from .exception_handling import (
-    construct_exception_handler_middleware,
+from .base import (
+    Middleware,
+    Web3Middleware,
 )
-from .exception_retry_request import (
-    async_http_retry_request_middleware,
-    http_retry_request_middleware,
+from .buffered_gas_estimate import (
+    BufferedGasEstimateMiddleware,
 )
 from .filter import (
-    async_local_filter_middleware,
-    local_filter_middleware,
-)
-from .fixture import (
-    async_construct_error_generator_middleware,
-    async_construct_result_generator_middleware,
-    construct_error_generator_middleware,
-    construct_fixture_middleware,
-    construct_result_generator_middleware,
+    LocalFilterMiddleware,
 )
 from .formatting import (
-    construct_formatting_middleware,
+    FormattingMiddlewareBuilder,
 )
 from .gas_price_strategy import (
-    async_gas_price_strategy_middleware,
-    gas_price_strategy_middleware,
-)
-from .geth_poa import (
-    async_geth_poa_middleware,
-    geth_poa_middleware,
+    GasPriceStrategyMiddleware,
 )
 from .names import (
-    async_name_to_address_middleware,
-    name_to_address_middleware,
+    ENSNameToAddressMiddleware,
 )
-from .normalize_request_parameters import (
-    request_parameter_normalizer,
+from .proof_of_authority import (
+    ExtraDataToPOAMiddleware,
 )
 from .pythonic import (
-    pythonic_middleware,
+    PythonicMiddleware,
 )
 from .signing import (
-    construct_sign_and_send_raw_middleware,
+    SignAndSendRawMiddlewareBuilder,
 )
 from .stalecheck import (
-    async_make_stalecheck_middleware,
-    make_stalecheck_middleware,
+    StalecheckMiddlewareBuilder,
 )
 from .validation import (
-    async_validation_middleware,
-    validation_middleware,
+    ValidationMiddleware,
 )
+from ..types import (
+    AsyncMakeRequestFn,
+    MakeRequestFn,
+)
+
 
 if TYPE_CHECKING:
-    from web3 import AsyncWeb3, Web3
+    from web3 import (
+        AsyncWeb3,
+        Web3,
+    )
+    from web3.types import (
+        RPCResponse,
+    )
 
 
-def combine_middlewares(
-    middlewares: Sequence[Middleware],
+def combine_middleware(
+    middleware: Sequence[Middleware],
     w3: "Web3",
-    provider_request_fn: Callable[[RPCEndpoint, Any], Any],
-) -> Callable[..., RPCResponse]:
+    provider_request_fn: MakeRequestFn,
+) -> Callable[..., "RPCResponse"]:
     """
-    Returns a callable function which will call the provider.provider_request
-    function wrapped with all of the middlewares.
+    Returns a callable function which takes method and params as positional arguments
+    and passes these args through the request processors, makes the request, and passes
+    the response through the response processors.
     """
-    return functools.reduce(
-        lambda request_fn, middleware: middleware(request_fn, w3),
-        reversed(middlewares),
-        provider_request_fn,
-    )
+    accumulator_fn = provider_request_fn
+    for mw in reversed(middleware):
+        # initialize the middleware and wrap the accumulator function down the stack
+        accumulator_fn = mw(w3).wrap_make_request(accumulator_fn)
+    return accumulator_fn
 
 
-async def async_combine_middlewares(
-    middlewares: Sequence[AsyncMiddleware],
+async def async_combine_middleware(
+    middleware: Sequence[Middleware],
     async_w3: "AsyncWeb3",
-    provider_request_fn: Callable[[RPCEndpoint, Any], Any],
-) -> Callable[..., Coroutine[Any, Any, RPCResponse]]:
+    provider_request_fn: AsyncMakeRequestFn,
+) -> Callable[..., Coroutine[Any, Any, "RPCResponse"]]:
     """
-    Returns a callable function which will call the provider.provider_request
-    function wrapped with all of the middlewares.
+    Returns a callable function which takes method and params as positional arguments
+    and passes these args through the request processors, makes the request, and passes
+    the response through the response processors.
     """
     accumulator_fn = provider_request_fn
-    for middleware in reversed(middlewares):
-        accumulator_fn = await construct_middleware(
-            middleware, accumulator_fn, async_w3
-        )
+    for mw in reversed(middleware):
+        # initialize the middleware and wrap the accumulator function down the stack
+        initialized = mw(async_w3)
+        accumulator_fn = await initialized.async_wrap_make_request(accumulator_fn)
     return accumulator_fn
 
 
-async def construct_middleware(
-    async_middleware: AsyncMiddleware,
-    fn: Callable[..., RPCResponse],
-    async_w3: "AsyncWeb3",
-) -> Callable[[RPCEndpoint, Any], RPCResponse]:
-    return await async_middleware(fn, async_w3)
+__all__ = [
+    "AttributeDictMiddleware",
+    "Middleware",
+    "Web3Middleware",
+    "BufferedGasEstimateMiddleware",
+    "LocalFilterMiddleware",
+    "FormattingMiddlewareBuilder",
+    "GasPriceStrategyMiddleware",
+    "ENSNameToAddressMiddleware",
+    "ExtraDataToPOAMiddleware",
+    "PythonicMiddleware",
+    "SignAndSendRawMiddlewareBuilder",
+    "StalecheckMiddlewareBuilder",
+    "ValidationMiddleware",
+]

web3/middleware/attrdict.py

@@ -1,8 +1,9 @@
+from abc import (
+    ABC,
+)
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
-    Optional,
     cast,
 )
 
@@ -13,10 +14,8 @@ from eth_utils.toolz import (
 from web3.datastructures import (
     AttributeDict,
 )
-from web3.types import (
-    AsyncMiddlewareCoroutine,
-    RPCEndpoint,
-    RPCResponse,
+from web3.middleware.base import (
+    Web3Middleware,
 )
 
 if TYPE_CHECKING:
@@ -27,11 +26,31 @@ if TYPE_CHECKING:
     from web3.providers import (  # noqa: F401
         PersistentConnectionProvider,
     )
+    from web3.types import (  # noqa: F401
+        RPCEndpoint,
+        RPCResponse,
+    )
 
 
-def attrdict_middleware(
-    make_request: Callable[[RPCEndpoint, Any], Any], _w3: "Web3"
-) -> Callable[[RPCEndpoint, Any], RPCResponse]:
+def _handle_async_response(response: "RPCResponse") -> "RPCResponse":
+    if "result" in response:
+        return assoc(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"]),
+            ),
+        )
+    else:
+        return response
+
+
+class AttributeDictMiddleware(Web3Middleware, ABC):
     """
     Converts any result which is a dictionary into an `AttributeDict`.
 
@@ -39,9 +58,7 @@ def attrdict_middleware(
         (e.g. my_attribute_dict.property1) will not preserve typing.
     """
 
-    def middleware(method: RPCEndpoint, params: Any) -> RPCResponse:
-        response = make_request(method, params)
-
+    def response_processor(self, method: "RPCEndpoint", response: "RPCResponse") -> Any:
         if "result" in response:
             return assoc(
                 response, "result", AttributeDict.recursive(response["result"])
@@ -49,27 +66,14 @@ def attrdict_middleware(
         else:
             return response
 
-    return middleware
-
-
-# --- async --- #
-
+    # -- async -- #
 
-async def async_attrdict_middleware(
-    make_request: Callable[[RPCEndpoint, Any], Any], async_w3: "AsyncWeb3"
-) -> AsyncMiddlewareCoroutine:
-    """
-    Converts any result which is a dictionary into an `AttributeDict`.
-
-    Note: Accessing `AttributeDict` properties via attribute
-        (e.g. my_attribute_dict.property1) will not preserve typing.
-    """
-
-    async def middleware(method: RPCEndpoint, params: Any) -> Optional[RPCResponse]:
-        response = await make_request(method, params)
-        if async_w3.provider.has_persistent_connection:
+    async def async_response_processor(
+        self, method: "RPCEndpoint", response: "RPCResponse"
+    ) -> Any:
+        if self._w3.provider.has_persistent_connection:
             # asynchronous response processing
-            provider = cast("PersistentConnectionProvider", async_w3.provider)
+            provider = cast("PersistentConnectionProvider", self._w3.provider)
             provider._request_processor.append_middleware_response_processor(
                 response, _handle_async_response
             )
@@ -77,22 +81,5 @@ async def async_attrdict_middleware(
         else:
             return _handle_async_response(response)
 
-    return middleware
-
 
-def _handle_async_response(response: RPCResponse) -> RPCResponse:
-    if "result" in response:
-        return assoc(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"]),
-            ),
-        )
-    else:
-        return response
+AttributeDictMiddleware = AttributeDictMiddleware

web3/middleware/base.py

@@ -0,0 +1,174 @@
+from abc import (
+    abstractmethod,
+)
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    List,
+    Tuple,
+    Type,
+    Union,
+)
+
+from web3.datastructures import (
+    NamedElementOnion,
+)
+
+if TYPE_CHECKING:
+    from web3 import (  # noqa: F401
+        AsyncWeb3,
+        Web3,
+    )
+    from web3.types import (  # noqa: F401
+        AsyncMakeBatchRequestFn,
+        AsyncMakeRequestFn,
+        MakeBatchRequestFn,
+        MakeRequestFn,
+        RPCEndpoint,
+        RPCResponse,
+    )
+
+
+class Web3Middleware:
+    """
+    Base class for web3.py middleware. This class is not meant to be used directly,
+    but instead inherited from.
+    """
+
+    _w3: Union["AsyncWeb3", "Web3"]
+
+    def __init__(self, w3: Union["AsyncWeb3", "Web3"]) -> None:
+        self._w3 = w3
+
+    # -- sync -- #
+
+    def wrap_make_request(self, make_request: "MakeRequestFn") -> "MakeRequestFn":
+        def middleware(method: "RPCEndpoint", params: Any) -> "RPCResponse":
+            method, params = self.request_processor(method, params)
+            return self.response_processor(method, make_request(method, params))
+
+        return middleware
+
+    def wrap_make_batch_request(
+        self, make_batch_request: "MakeBatchRequestFn"
+    ) -> "MakeBatchRequestFn":
+        def middleware(
+            requests_info: List[Tuple["RPCEndpoint", Any]]
+        ) -> List["RPCResponse"]:
+            req_processed = [
+                self.request_processor(method, params)
+                for (method, params) in requests_info
+            ]
+            responses = make_batch_request(req_processed)
+            methods, _params = zip(*req_processed)
+            formatted_responses = [
+                self.response_processor(m, r) for m, r in zip(methods, responses)
+            ]
+            return formatted_responses
+
+        return middleware
+
+    def request_processor(self, method: "RPCEndpoint", params: Any) -> Any:
+        return method, params
+
+    def response_processor(
+        self, method: "RPCEndpoint", response: "RPCResponse"
+    ) -> "RPCResponse":
+        return response
+
+    # -- async -- #
+
+    async def async_wrap_make_request(
+        self, make_request: "AsyncMakeRequestFn"
+    ) -> "AsyncMakeRequestFn":
+        async def middleware(method: "RPCEndpoint", params: Any) -> "RPCResponse":
+            method, params = await self.async_request_processor(method, params)
+            return await self.async_response_processor(
+                method,
+                await make_request(method, params),
+            )
+
+        return middleware
+
+    async def async_wrap_make_batch_request(
+        self, make_batch_request: "AsyncMakeBatchRequestFn"
+    ) -> "AsyncMakeBatchRequestFn":
+        async def middleware(
+            requests_info: List[Tuple["RPCEndpoint", Any]]
+        ) -> List["RPCResponse"]:
+            req_processed = [
+                await self.async_request_processor(method, params)
+                for (method, params) in requests_info
+            ]
+            responses = await make_batch_request(req_processed)
+            methods, _params = zip(*req_processed)
+            formatted_responses = [
+                await self.async_response_processor(m, r)
+                for m, r in zip(methods, responses)
+            ]
+            return formatted_responses
+
+        return middleware
+
+    async def async_request_processor(
+        self,
+        method: "RPCEndpoint",
+        params: Any,
+    ) -> Any:
+        return method, params
+
+    async def async_response_processor(
+        self,
+        method: "RPCEndpoint",
+        response: "RPCResponse",
+    ) -> "RPCResponse":
+        return response
+
+
+class Web3MiddlewareBuilder(Web3Middleware):
+    @staticmethod
+    @abstractmethod
+    def build(
+        w3: Union["AsyncWeb3", "Web3"],
+        *args: Any,
+        **kwargs: Any,
+    ) -> Web3Middleware:
+        """
+        Implementation should initialize the middleware class that implements it,
+        load it with any of the necessary properties that it needs for processing,
+        and curry for the ``w3`` argument since it isn't initially present when building
+        the middleware.
+
+        example implementation:
+
+        ```py
+        class MyMiddleware(Web3BuilderMiddleware):
+            internal_property: str = None
+
+            @staticmethod
+            @curry
+            def builder(user_provided_argument, w3):
+                middleware = MyMiddleware(w3)
+                middleware.internal_property = user_provided_argument
+                return middleware
+
+            def request_processor(self, method, params):
+                ...
+
+            def response_processor(self, method, response):
+                ...
+
+        construct_my_middleware = MyMiddleware.builder
+
+        w3 = Web3(provider)
+        my_middleware = construct_my_middleware("my argument")
+        w3.middleware_onion.inject(my_middleware, layer=0)
+        ```
+        """
+        raise NotImplementedError("Must be implemented by subclasses")
+
+
+# --- type definitions --- #
+
+Middleware = Type[Web3Middleware]
+MiddlewareOnion = NamedElementOnion[str, Middleware]