diff --git a/docs/internals.rst b/docs/internals.rst index 8672ada3b2..aeb3b62aae 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -186,6 +186,7 @@ The Manager acts as a gatekeeper for the request/response lifecycle. It is unlikely that you will need to change the Manager as most functionality can be implemented in the Middleware layer. +.. _internals__persistent_connection_providers: Request Processing for Persistent Connection Providers ------------------------------------------------------ diff --git a/docs/providers.rst b/docs/providers.rst index 290806c795..8be2f90710 100644 --- a/docs/providers.rst +++ b/docs/providers.rst @@ -219,14 +219,38 @@ WebsocketProvider >>> w3 = Web3(Web3.WebsocketProvider("ws://127.0.0.1:8546", websocket_timeout=60)) +Persistent Connection Providers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. py:class:: web3.providers.persistent.PersistentConnectionProvider(endpoint_uri: str, request_timeout: float = 50.0, subscription_response_queue_size: int = 500) + + This is a base provider class, currently inherited by the ``WebsocketProviderV2``. + It handles interactions with a persistent connection to a JSON-RPC server. Among + its configuration, it houses all of the + :class:`~web3.providers.websocket.request_processor.RequestProcessor` logic for + handling the asynchronous sending and receiving of requests and responses. See + the :ref:`internals__persistent_connection_providers` section for more details on + the internals of persistent connection providers. + + * ``request_timeout`` is the timeout in seconds, used when sending data over the + connection and waiting for a response to be received from the listener task. + Defaults to ``50.0``. + + * ``subscription_response_queue_size`` is the size of the queue used to store + subscription responses, defaults to ``500``. While messages are being consumed, + this queue should never fill up as it is a transient queue and meant to handle + asynchronous receiving and processing of responses. When in sync with the + websocket stream, this queue should only ever store 1 to a few messages at a time. + + WebsocketProviderV2 (beta) -~~~~~~~~~~~~~~~~~~~~~~~~~~ +`````````````````````````` .. warning:: This provider is still in beta. However, it is being actively developed and supported and is expected to be stable in the next major version of *web3.py* (v7). -.. py:class:: web3.providers.websocket.WebsocketProviderV2(endpoint_uri, websocket_kwargs, call_timeout) +.. py:class:: web3.providers.websocket.WebsocketProviderV2(endpoint_uri: str, websocket_kwargs: Dict[str, Any] = {}, silence_listener_task_exceptions: bool = False) This provider handles interactions with an WS or WSS based JSON-RPC server. @@ -234,8 +258,14 @@ WebsocketProviderV2 (beta) ``'ws://localhost:8546'``. * ``websocket_kwargs`` this should be a dictionary of keyword arguments which will be passed onto the ws/wss websocket connection. - * ``request_timeout`` is the timeout in seconds, as a float. Used when receiving or - sending data over the connection. This value defaults to 20 seconds. + * ``silence_listener_task_exceptions`` is a boolean that determines whether + exceptions raised by the listener task are silenced. Defaults to ``False``, + raising any exceptions that occur in the listener task. + + This provider inherits from the + :class:`~web3.providers.persistent.PersistentConnectionProvider` class. Refer to + the :class:`~web3.providers.persistent.PersistentConnectionProvider` documentation + for details on additional configuration options available for this provider. Under the hood, the ``WebsocketProviderV2`` uses the python websockets library for making requests. If you would like to modify how requests are made, you can @@ -244,7 +274,7 @@ WebsocketProviderV2 (beta) Usage -~~~~~ ++++++ The ``AsyncWeb3`` class may be used as a context manager, utilizing the ``async with`` syntax, when connecting via ``persistent_websocket()`` using the @@ -363,7 +393,7 @@ one-to-many request-to-response requests. Refer to the documentation for details. _PersistentConnectionWeb3 via AsyncWeb3.persistent_websocket() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ When an ``AsyncWeb3`` class is connected to a persistent websocket connection, via the ``persistent_websocket()`` method, it becomes an instance of the diff --git a/web3/providers/persistent.py b/web3/providers/persistent.py index fcd92b05fc..1dd059f6a3 100644 --- a/web3/providers/persistent.py +++ b/web3/providers/persistent.py @@ -18,12 +18,13 @@ RequestProcessor, ) -DEFAULT_PERSISTENT_CONNECTION_TIMEOUT = 50 +DEFAULT_PERSISTENT_CONNECTION_TIMEOUT = 50.0 class PersistentConnectionProvider(AsyncJSONBaseProvider, ABC): logger = logging.getLogger("web3.providers.PersistentConnectionProvider") has_persistent_connection = True + endpoint_uri: Optional[str] = None _ws: Optional[WebSocketClientProtocol] = None _request_processor: RequestProcessor @@ -32,12 +33,10 @@ class PersistentConnectionProvider(AsyncJSONBaseProvider, ABC): def __init__( self, - endpoint_uri: str, request_timeout: float = DEFAULT_PERSISTENT_CONNECTION_TIMEOUT, subscription_response_queue_size: int = 500, ) -> None: super().__init__() - self.endpoint_uri = endpoint_uri self._request_processor = RequestProcessor( self, subscription_response_queue_size=subscription_response_queue_size, diff --git a/web3/providers/websocket/websocket_v2.py b/web3/providers/websocket/websocket_v2.py index a22df15447..bf7e76e14d 100644 --- a/web3/providers/websocket/websocket_v2.py +++ b/web3/providers/websocket/websocket_v2.py @@ -95,7 +95,7 @@ def __init__( self.websocket_kwargs = merge(DEFAULT_WEBSOCKET_KWARGS, websocket_kwargs or {}) self.silence_listener_task_exceptions = silence_listener_task_exceptions - super().__init__(endpoint_uri, **kwargs) + super().__init__(**kwargs) def __str__(self) -> str: return f"Websocket connection: {self.endpoint_uri}"