Docs updates for session caching; exception retry tweaks along the way.

Author: fselmo

docs/internals.rst

@@ -144,6 +144,29 @@ options on the provider instance:
 Retry Requests for HTTP Providers
 `````````````````````````````````
 
+.. py:class:: web3.providers.rpc.utils.ExceptionRetryConfiguration
+
+    .. py:attribute:: errors
+
+        A tuple of exceptions that the provider should retry on. The default is
+        ``HTTPProvider``: ``(ConnectionError, requests.HTTPError, requests.Timeout)``
+        and ``AsyncHTTPProvider``: ``(aiohttp.ClientError, asyncio.TimeoutError)``.
+
+    .. py:attribute:: retries
+
+        The number of retries to attempt. The default is 5.
+
+    .. py:attribute:: backoff_factor
+
+        The initial delay multiplier, which doubles with each retry attempt. The default
+        is 0.125.
+
+    .. py:attribute:: method_allowlist
+
+        A list of retryable methods. The default is an in-house list of deemed-safe-to-
+        retry methods.
+
+
 ``HTTPProvider`` and ``AsyncHTTPProvider`` instances retry certain requests by default
 on exceptions. This can be configured via configuration options on the provider
 instance. The retry mechanism employs an exponential backoff strategy, starting from

docs/providers.rst

@@ -107,7 +107,7 @@ local and remote JSON-RPC servers.
 HTTPProvider
 ~~~~~~~~~~~~
 
-.. py:class:: web3.providers.rpc.HTTPProvider(endpoint_uri[, request_kwargs, session])
+.. py:class:: web3.providers.rpc.HTTPProvider(endpoint_uri, request_kwargs={}, session=None, exception_retry_configuration=ExceptionRetryConfiguration())
 
     This provider handles interactions with an HTTP or HTTPS based JSON-RPC server.
 
@@ -119,6 +119,11 @@ HTTPProvider
       will be passed onto each http/https POST request made to your node.
     * ``session`` allows you to pass a ``requests.Session`` object initialized
       as desired.
+    * ``exception_retry_configuration`` is an instance of the
+      :class:`~web3.providers.rpc.utils.ExceptionRetryConfiguration`
+      class which allows you to configure how the provider should handle exceptions
+      when making certain requests. Setting this to ``None`` will disable
+      exception retries.
 
     .. code-block:: python
 
@@ -180,7 +185,7 @@ IPCProvider
 AsyncHTTPProvider
 ~~~~~~~~~~~~~~~~~
 
-.. py:class:: web3.providers.async_rpc.AsyncHTTPProvider(endpoint_uri[, request_kwargs])
+.. py:class:: web3.providers.rpc.AsyncHTTPProvider(endpoint_uri, request_kwargs={}, exception_retry_configuration=ExceptionRetryConfiguration())
 
     This provider handles interactions with an HTTP or HTTPS based JSON-RPC server asynchronously.
 
@@ -190,7 +195,14 @@ AsyncHTTPProvider
       be omitted from the URI.
     * ``request_kwargs`` should be a dictionary of keyword arguments which
       will be passed onto each http/https POST request made to your node.
-    * the ``cache_async_session()`` method allows you to use your own ``aiohttp.ClientSession`` object. This is an async method and not part of the constructor
+    * ``exception_retry_configuration`` is an instance of the
+      :class:`~web3.providers.rpc.utils.ExceptionRetryConfiguration`
+      class which allows you to configure how the provider should handle exceptions
+      when making certain requests. Setting this to ``None`` will disable
+      exception retries.
+
+    The ``cache_async_session()`` method allows you to use your own
+    ``aiohttp.ClientSession`` object.
 
     .. code-block:: python
 

newsfragments/3412.bugfix.rst

@@ -0,0 +1 @@
+Change the ``exception_retry_configuration`` typing on http providers to be an ``Optional``, as setting this property to ``None`` effectively turns off retries on exceptions for requests.

newsfragments/3412.internal.rst

@@ -0,0 +1 @@
+Use a ``RequestSessionManager`` to manage sessions for http providers, rather than have them share a single session manager / cache.

web3/providers/rpc/async_rpc.py

@@ -61,8 +61,8 @@ def __init__(
         self,
         endpoint_uri: Optional[Union[URI, str]] = None,
         request_kwargs: Optional[Any] = None,
-        exception_retry_configuration: Union[
-            ExceptionRetryConfiguration, Empty
+        exception_retry_configuration: Optional[
+            Union[ExceptionRetryConfiguration, Empty]
         ] = empty,
         **kwargs: Any,
     ) -> None:

web3/providers/rpc/rpc.py

@@ -65,8 +65,8 @@ def __init__(
         endpoint_uri: Optional[Union[URI, str]] = None,
         request_kwargs: Optional[Any] = None,
         session: Optional[Any] = None,
-        exception_retry_configuration: Union[
-            ExceptionRetryConfiguration, Empty
+        exception_retry_configuration: Optional[
+            Union[ExceptionRetryConfiguration, Empty]
         ] = empty,
         **kwargs: Any,
     ) -> None: