Move HTTPProvider into its own feature

Author: fjarri

docs/api.rst

@@ -23,10 +23,20 @@ Providers
 .. autoclass:: Provider
    :show-inheritance:
 
-.. autoclass:: HTTPProvider
+.. autoclass:: ProviderPath()
+
+
+HTTP
+^^^^
+
+Install the feature ``http-provider`` for the ``http_provider`` module to be available.
+
+.. autoclass:: pons.http_provider.HTTPProvider
    :show-inheritance:
 
-.. autoclass:: ProviderPath()
+.. autoclass:: pons.http_provider.HTTPError()
+   :show-inheritance:
+   :members:
 
 
 Fallback providers
@@ -70,8 +80,6 @@ Provider level
 .. autoclass:: ProtocolError
    :show-inheritance:
 
-.. autoclass:: HTTPError
-   :show-inheritance:
 
 Client level
 ^^^^^^^^^^^^

docs/changelog.rst

@@ -9,6 +9,7 @@ Changed
 ^^^^^^^
 
 - ``ContractABI`` interface modified to allow for methods, errors, and events with arbitrary anonymous parameters and fields. Instead of returning ``dict[str, Any]`` as a parsed struct we now return a ``FieldValues`` object. Signatures of methods and fields of errors are exposed as ``Fields``, fields of events are exposed as ``EventFields`` objects. (PR_92_)
+- ``HTTPProvider`` and ``HTTPError`` are moved to ``http_provider`` submodule, which is optional and gated under the ``http-provider`` feature. (PR_94_)
 
 
 Added
@@ -29,6 +30,7 @@ Fixed
 .. _PR_91: https://github.com/fjarri-eth/pons/pull/91
 .. _PR_92: https://github.com/fjarri-eth/pons/pull/92
 .. _PR_93: https://github.com/fjarri-eth/pons/pull/93
+.. _PR_94: https://github.com/fjarri-eth/pons/pull/94
 
 
 0.10.0 (2025-10-19)

pdm.lock

@@ -55,8 +55,6 @@
 )
 from ._multicall import BoundMultiMethodCall, BoundMultiMethodValueCall, Multicall
 from ._provider import (
-    HTTPError,
-    HTTPProvider,
     InvalidResponse,
     ProtocolError,
     Provider,

pons/__init__.py

@@ -2,13 +2,8 @@
 from collections.abc import AsyncIterator, Iterable, Mapping, Sequence
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
-from http import HTTPStatus
-from json import JSONDecodeError
-from typing import cast
 
-import httpx
-from compages import StructuringError
-from ethereum_rpc import RPCError, structure
+from ethereum_rpc import RPCError
 
 RPC_JSON = None | bool | int | float | str | Sequence["RPC_JSON"] | Mapping[str, "RPC_JSON"]
 """RPC requests and responses serializable to JSON."""
@@ -31,33 +26,6 @@ class ProtocolError(ABC, Exception):
     """
 
 
-class HTTPError(ProtocolError):
-    """
-    Raised when the provider returns a response with a status code other than 200,
-    and no ``"error"`` field in the associated JSON data.
-    """
-
-    status: HTTPStatus
-    """The HTTP status of the response."""
-
-    message: str
-    """The response body."""
-
-    def __init__(self, status_code: int, message: str):
-        try:
-            status = HTTPStatus(status_code)
-        except ValueError:  # pragma: no cover
-            # How to handle it better? Ideally, `httpx` should have returned a parsed status
-            # in the first place, but, alas, it just gives us an integer.
-            status = HTTPStatus.INTERNAL_SERVER_ERROR
-
-        self.status = status
-        self.message = message
-
-    def __str__(self) -> str:
-        return f"HTTP status {self.status}: {self.message}"
-
-
 @dataclass
 class ProviderError(Exception):
     """Describes an error on the provider's side."""
@@ -149,68 +117,3 @@ async def rpc_at_pin(self, path: ProviderPath, method: str, *args: RPC_JSON) ->
         if not path.is_empty():
             raise ValueError(f"Expected an empty provider path, got: `{path}`")
         return await self.rpc(method, *args)
-
-
-class HTTPProvider(Provider):
-    """A provider for RPC via HTTP(S)."""
-
-    def __init__(self, url: str):
-        self._url = url
-
-    @asynccontextmanager
-    async def session(self) -> AsyncIterator["HTTPSession"]:
-        async with httpx.AsyncClient() as client:
-            yield HTTPSession(self._url, client)
-
-
-class HTTPSession(ProviderSession):
-    def __init__(self, url: str, http_client: httpx.AsyncClient):
-        self._url = url
-        self._client = http_client
-
-    def _prepare_request(self, method: str, *args: RPC_JSON) -> RPC_JSON:
-        return {"jsonrpc": "2.0", "method": method, "params": args, "id": 0}
-
-    async def rpc(self, method: str, *args: RPC_JSON) -> RPC_JSON:
-        json = self._prepare_request(method, *args)
-        try:
-            response = await self._client.post(self._url, json=json)
-        except httpx.ConnectError as exc:
-            raise ProviderError(Unreachable(str(exc))) from exc
-
-        status = response.status_code
-
-        try:
-            response_json = response.json()
-        except JSONDecodeError as exc:
-            content = response.content.decode()
-            raise ProviderError(
-                InvalidResponse(f"Expected a JSON response, got HTTP status {status}: {content}")
-            ) from exc
-
-        if not isinstance(response_json, Mapping):
-            raise ProviderError(
-                InvalidResponse(f"RPC response must be a dictionary, got: {response_json}")
-            )
-        response_json = cast("Mapping[str, RPC_JSON]", response_json)
-
-        # Note that the Eth-side errors (e.g. transaction having been reverted)
-        # will have the HTTP status 200, so we are checking for the "error" field first.
-        if "error" in response_json:
-            try:
-                error = structure(RPCError, response_json["error"])
-            except StructuringError as exc:
-                raise ProviderError(
-                    InvalidResponse(f"Failed to parse an error response: {response_json}")
-                ) from exc
-
-            raise ProviderError(error)
-
-        if status == HTTPStatus.OK:
-            if "result" in response_json:
-                return response_json["result"]
-            raise ProviderError(
-                InvalidResponse(f"`result` is not present in the response: {response_json}")
-            )
-
-        raise ProviderError(HTTPError(status, response.content.decode()))

pons/_provider.py

@@ -0,0 +1,115 @@
+"""HTTP provider based on `httpx`."""
+
+from collections.abc import AsyncIterator, Mapping
+from contextlib import asynccontextmanager
+from http import HTTPStatus
+from json import JSONDecodeError
+from typing import cast
+
+import httpx
+from compages import StructuringError
+from ethereum_rpc import RPCError, structure
+
+from ._provider import (
+    RPC_JSON,
+    InvalidResponse,
+    ProtocolError,
+    Provider,
+    ProviderError,
+    ProviderSession,
+    Unreachable,
+)
+
+__all__ = ["HTTPError", "HTTPProvider"]
+
+
+class HTTPError(ProtocolError):
+    """
+    Raised when the provider returns a response with a status code other than 200,
+    and no ``"error"`` field in the associated JSON data.
+    """
+
+    status: HTTPStatus
+    """The HTTP status of the response."""
+
+    message: str
+    """The response body."""
+
+    def __init__(self, status_code: int, message: str):
+        try:
+            status = HTTPStatus(status_code)
+        except ValueError:  # pragma: no cover
+            # How to handle it better? Ideally, `httpx` should have returned a parsed status
+            # in the first place, but, alas, it just gives us an integer.
+            status = HTTPStatus.INTERNAL_SERVER_ERROR
+
+        self.status = status
+        self.message = message
+
+    def __str__(self) -> str:  # noqa: D105
+        return f"HTTP status {self.status}: {self.message}"
+
+
+class HTTPProvider(Provider):
+    """A provider for RPC via HTTP(S)."""
+
+    def __init__(self, url: str):
+        self._url = url
+
+    @asynccontextmanager
+    async def session(self) -> AsyncIterator["HTTPProviderSession"]:  # noqa: D102
+        async with httpx.AsyncClient() as client:
+            yield HTTPProviderSession(self._url, client)
+
+
+class HTTPProviderSession(ProviderSession):
+    def __init__(self, url: str, http_client: httpx.AsyncClient):
+        self._url = url
+        self._client = http_client
+
+    def _prepare_request(self, method: str, *args: RPC_JSON) -> RPC_JSON:
+        return {"jsonrpc": "2.0", "method": method, "params": args, "id": 0}
+
+    async def rpc(self, method: str, *args: RPC_JSON) -> RPC_JSON:
+        json = self._prepare_request(method, *args)
+        try:
+            response = await self._client.post(self._url, json=json)
+        except httpx.ConnectError as exc:
+            raise ProviderError(Unreachable(str(exc))) from exc
+
+        status = response.status_code
+
+        try:
+            response_json = response.json()
+        except JSONDecodeError as exc:
+            content = response.content.decode()
+            raise ProviderError(
+                InvalidResponse(f"Expected a JSON response, got HTTP status {status}: {content}")
+            ) from exc
+
+        if not isinstance(response_json, Mapping):
+            raise ProviderError(
+                InvalidResponse(f"RPC response must be a dictionary, got: {response_json}")
+            )
+        response_json = cast("Mapping[str, RPC_JSON]", response_json)
+
+        # Note that the Eth-side errors (e.g. transaction having been reverted)
+        # will have the HTTP status 200, so we are checking for the "error" field first.
+        if "error" in response_json:
+            try:
+                error = structure(RPCError, response_json["error"])
+            except StructuringError as exc:
+                raise ProviderError(
+                    InvalidResponse(f"Failed to parse an error response: {response_json}")
+                ) from exc
+
+            raise ProviderError(error)
+
+        if status == HTTPStatus.OK:
+            if "result" in response_json:
+                return response_json["result"]
+            raise ProviderError(
+                InvalidResponse(f"`result` is not present in the response: {response_json}")
+            )
+
+        raise ProviderError(HTTPError(status, response.content.decode()))

pons/http_provider.py

@@ -16,7 +16,8 @@
 from starlette.responses import JSONResponse, Response
 from starlette.routing import Route
 
-from ._provider import RPC_JSON, HTTPProvider, Provider
+from ._provider import RPC_JSON, Provider
+from .http_provider import HTTPProvider
 
 __all__ = ["HTTPProviderServer"]
 
@@ -88,7 +89,7 @@ def make_app(provider: Provider) -> ASGIFramework:
 
 class HTTPProviderServer:
     """
-    A server counterpart of :py:class:`pons.HTTPProvider`.
+    A server counterpart of :py:class:`pons.http_provider.HTTPProvider`.
     Intended for testing, not production-ready.
     """
 

pons/http_provider_server.py

@@ -6,7 +6,6 @@ authors = [
     {name = "Bogdan Opanchuk", email = "bogdan@opanchuk.net"},
 ]
 dependencies = [
-    "httpx>=0.22",
     "eth-account>=0.13",
     "eth-utils>=2",
     "eth-abi>=5.0.1",
@@ -29,6 +28,9 @@ compiler = [
 local-provider = [
     "alysis>=0.6.1",
 ]
+http-provider = [
+    "httpx>=0.22",
+]
 http-provider-server = [
     "starlette>=0.48",
     "hypercorn>=0.17",

pyproject.toml

@@ -10,7 +10,6 @@
 from pons import (
     CycleFallback,
     FallbackProvider,
-    HTTPError,
     InvalidResponse,
     PriorityFallback,
     ProtocolError,
@@ -21,6 +20,7 @@
 )
 from pons._fallback_provider import PriorityFallbackStrategy
 from pons._provider import RPC_JSON, ProviderSession
+from pons.http_provider import HTTPError
 
 
 def random_request() -> str: