✨ Add AsyncIPCProvider

.circleci/config.yml

@@ -288,6 +288,13 @@ jobs:
     environment:
       TOXENV: py38-integration-goethereum-ipc
 
+  py38-integration-goethereum-ipc_async:
+    <<: *geth_steps
+    docker:
+      - image: cimg/python:3.8
+    environment:
+      TOXENV: py38-integration-goethereum-ipc_async
+
   py38-integration-goethereum-ipc_flaky:
     <<: *geth_steps
     docker:
@@ -427,6 +434,13 @@ jobs:
     environment:
       TOXENV: py39-integration-goethereum-ipc
 
+  py39-integration-goethereum-ipc_async:
+    <<: *geth_steps
+    docker:
+      - image: cimg/python:3.9
+    environment:
+      TOXENV: py39-integration-goethereum-ipc_async
+
   py39-integration-goethereum-ipc_flaky:
     <<: *geth_steps
     docker:
@@ -566,6 +580,13 @@ jobs:
     environment:
       TOXENV: py310-integration-goethereum-ipc
 
+  py310-integration-goethereum-ipc_async:
+    <<: *geth_steps
+    docker:
+      - image: cimg/python:3.10
+    environment:
+      TOXENV: py310-integration-goethereum-ipc_async
+
   py310-integration-goethereum-ipc_flaky:
     <<: *geth_steps
     docker:
@@ -711,6 +732,13 @@ jobs:
     environment:
       TOXENV: py311-integration-goethereum-ipc
 
+  py311-integration-goethereum-ipc_async:
+    <<: *geth_steps
+    docker:
+      - image: cimg/python:3.11
+    environment:
+      TOXENV: py311-integration-goethereum-ipc_async
+
   py311-integration-goethereum-ipc_flaky:
     <<: *geth_steps
     docker:
@@ -824,6 +852,7 @@ workflows:
       - py38-ensip15
       - py38-ethpm
       - py38-integration-goethereum-ipc
+      - py38-integration-goethereum-ipc_async
       - py38-integration-goethereum-ipc_flaky
       - py38-integration-goethereum-http
       - py38-integration-goethereum-http_async
@@ -841,6 +870,7 @@ workflows:
       - py39-ensip15
       - py39-ethpm
       - py39-integration-goethereum-ipc
+      - py39-integration-goethereum-ipc_async
       - py39-integration-goethereum-ipc_flaky
       - py39-integration-goethereum-http
       - py39-integration-goethereum-http_async
@@ -858,6 +888,7 @@ workflows:
       - py310-ensip15
       - py310-ethpm
       - py310-integration-goethereum-ipc
+      - py310-integration-goethereum-ipc_async
       - py310-integration-goethereum-ipc_flaky
       - py310-integration-goethereum-http
       - py310-integration-goethereum-http_async
@@ -875,6 +906,7 @@ workflows:
       - py311-ensip15
       - py311-ethpm
       - py311-integration-goethereum-ipc
+      - py311-integration-goethereum-ipc_async
       - py311-integration-goethereum-ipc_flaky
       - py311-integration-goethereum-http
       - py311-integration-goethereum-http_async

.gitignore

@@ -51,6 +51,7 @@ docs/web3.providers.eth_tester.rst
 docs/web3.providers.rst
 docs/web3.providers.rpc.rst
 docs/web3.providers.websocket.rst
+docs/web3.providers.persistent.rst
 docs/web3.rst
 docs/web3.scripts.release.rst
 docs/web3.scripts.rst

docs/conf.py

@@ -88,6 +88,7 @@
     "web3.providers.rst",
     "web3.providers.rpc.rst",
     "web3.providers.websocket.rst",
+    "web3.providers.persistent.rst",
     "web3.providers.eth_tester.rst",
     "web3.scripts.*",
     "web3.testing.rst",

docs/internals.rst

@@ -304,12 +304,12 @@ implemented in the Middleware layer.
 Request Processing for Persistent Connection Providers
 ------------------------------------------------------
 
-.. py:class:: web3.providers.websocket.request_processor.RequestProcessor
+.. py:class:: web3.providers.persistent.request_processor.RequestProcessor
 
 The ``RequestProcessor`` class is responsible for the storing and syncing up of
 asynchronous requests to responses for a ``PersistentConnectionProvider``. The best
 example of one such provider is the
-:class:`~web3.providers.websocket.WebsocketProviderV2`. In order to send a websocket
+:class:`~web3.providers.persistent.WebsocketProviderV2`. In order to send a websocket
 message and receive a response to that particular request,
 ``PersistentConnectionProvider`` instances have to match request *id* values to
 response *id* values coming back from the websocket connection. Any provider that does
@@ -339,7 +339,7 @@ back. An example is using the ``eth`` module API to request the latest block num
 .. code-block:: python
 
     >>> async def wsV2_one_to_one_example():
-    ...     async with AsyncWeb3.persistent_websocket(
+    ...     async with AsyncWeb3.persistent_connection(
     ...         WebsocketProviderV2(f"ws://127.0.0.1:8546")
     ...     ) as w3:
     ...         # make a request and expect a single response returned on the same line
@@ -414,23 +414,24 @@ subscription *id* value, but it also expects to receive many ``eth_subscription`
 messages if and when the request is successful. For this reason, the original request
 is considered a one-to-one request so that a subscription *id* can be returned to the
 user on the same line, but the ``process_subscriptions()`` method on the
-:class:`~web3.providers.websocket.WebsocketConnection` class, the public API for
+:class:`~web3.providers.persistent.PersistentConnection` class, the public API for
 interacting with the active websocket connection, is set up to receive
 ``eth_subscription`` responses over an asynchronous interator pattern.
 
 .. code-block:: python
 
     >>> async def ws_v2_subscription_example():
-    ...     async with AsyncWeb3.persistent_websocket(
+    ...     async with AsyncWeb3.persistent_connection(
     ...         WebsocketProviderV2(f"ws://127.0.0.1:8546")
     ...     ) as w3:
     ...         # Subscribe to new block headers and receive the subscription_id.
     ...         # A one-to-one call with a trigger for many responses
     ...         subscription_id = await w3.eth.subscribe("newHeads")
     ...
-    ...         # Listen to the websocket for the many responses utilizing the ``w3.ws``
-    ...         # ``WebsocketConnection`` public API method ``process_subscriptions()``
-    ...         async for response in w3.ws.process_subscriptions():
+    ...         # Listen to the websocket for the many responses utilizing the
+    ...         # ``w3.socket`` ``PersistentConnection`` public API method
+    ...         # ``process_subscriptions()``
+    ...         async for response in w3.socket.process_subscriptions():
     ...             # Receive only one-to-many responses here so that we don't
     ...             # accidentally return the response for a one-to-one request in this
     ...             # block
@@ -450,7 +451,7 @@ are stored in an internal ``asyncio.Queue`` instance, isolated from any one-to-o
 responses. When the ``PersistentConnectionProvider`` is looking for one-to-many
 responses internally, it will expect the message listener task to store these messages
 in this queue. Since the order of the messages is important, the queue is a FIFO queue.
-The ``process_subscriptions()`` method on the ``WebsocketConnection`` class is set up
+The ``process_subscriptions()`` method on the ``PersistentConnection`` class is set up
 to pop messages from this queue as FIFO over an asynchronous iterator pattern.
 
 If the stream of messages from the websocket is not being interrupted by any other

docs/overview.rst

@@ -26,8 +26,9 @@ following built-in providers:
 - :class:`~web3.providers.ipc.IPCProvider` for connecting to ipc socket based JSON-RPC servers.
 - :class:`~web3.providers.rpc.HTTPProvider` for connecting to http and https based JSON-RPC servers.
 - :class:`~web3.providers.websocket.WebsocketProvider` for connecting to ws and wss websocket based JSON-RPC servers.
-- :class:`~web3.providers.async_rpc.AsyncHTTPProvider` for connecting to http and https based JSON-RPC servers.
-
+- :class:`~web3.providers.async_rpc.AsyncHTTPProvider` for connecting to http and https based JSON-RPC servers asynchronously.
+- :class:`~web3.providers.persistent.WebsocketProviderV2` (beta) for connecting to websocket based JSON-RPC servers asynchronously.
+- :class:`~web3.providers.persistent.AsyncIPCProvider` (beta) for connecting to ipc socket based JSON-RPC servers asynchronously.
 
 Examples
 ^^^^^^^^
@@ -323,7 +324,7 @@ ENS
 
 `Ethereum Name Service (ENS) <https://ens.domains/>`_ provides the infrastructure
 for human-readable addresses. If an address is registered with the ENS registry,
-the domain name can be used in place of the address itself. For example, the registered domain 
+the domain name can be used in place of the address itself. For example, the registered domain
 name ``ethereum.eth`` will resolve to the address
 ``0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe``. web3.py has support for ENS, documented
 :ref:`here <ens_overview>`.