Async web3 docs

docs/overview.rst

@@ -13,8 +13,9 @@ greater detail.
 Configuration
 ~~~~~~~~~~~~~
 
-After installing web3.py (via ``pip install web3``), you'll need to specify the
-provider and any middleware you want to use beyond the defaults.
+After installing web3.py (via ``pip install web3``), you'll need to specify
+async or sync web3, the provider, and any middleware you want to use
+beyond the defaults.
 
 
 Providers
@@ -26,7 +27,11 @@ following built-in providers:
 - ``Web3.IPCProvider`` for connecting to ipc socket based JSON-RPC servers.
 - ``Web3.HTTPProvider`` for connecting to http and https based JSON-RPC servers.
 - ``Web3.WebsocketProvider`` for connecting to ws and wss websocket based JSON-RPC servers.
+- ``AsyncWeb3.AsyncHTTPProvider`` for connecting to http and https based JSON-RPC servers.
 
+
+Synchronous Provider Examples:
+------------------------------
 .. code-block:: python
 
    >>> from web3 import Web3
@@ -43,6 +48,25 @@ following built-in providers:
    >>> w3.is_connected()
    True
 
+
+Asynchronous Provider Example:
+------------------------------
+
+.. note::
+
+   The AsyncHTTPProvider is still under active development. Not all JSON-RPC
+   methods and middleware are available yet. The list of available methods and
+   middleware can be seen on the :class:`~web3.providers.async_rpc.AsyncHTTPProvider` docs
+
+.. code-block:: python
+
+   >>> from web3 import AsyncWeb3
+
+   >>> w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider('http://127.0.0.1:8545'))
+
+   >>> await w3.is_connected()
+   True
+
 For more information, (e.g., connecting to remote nodes, provider auto-detection,
 using a test provider) see the :ref:`Providers <providers>` documentation.
 

docs/providers.rst

@@ -49,6 +49,7 @@ See:
 - :class:`~web3.providers.ipc.IPCProvider`
 - :class:`~web3.providers.websocket.WebsocketProvider`
 - :class:`~web3.providers.rpc.HTTPProvider`
+- :class:`~web3.providers.async_rpc.AsyncHTTPProvider`
 
 Once you have configured your provider, for example:
 
@@ -220,33 +221,6 @@ WebsocketProvider
         >>> from web3 import Web3
         >>> w3 = Web3(Web3.WebsocketProvider("ws://127.0.0.1:8546", websocket_timeout=60))
 
-.. py:currentmodule:: web3.providers.eth_tester
-
-EthereumTesterProvider
-~~~~~~~~~~~~~~~~~~~~~~
-
-.. warning:: Experimental:  This provider is experimental. There are still significant gaps in
-    functionality. However it is being actively developed and supported.
-
-.. py:class:: EthereumTesterProvider(eth_tester=None)
-
-    This provider integrates with the ``eth-tester`` library.  The ``eth_tester`` constructor
-    argument should be an instance of the :class:`~eth_tester.EthereumTester` or a subclass of
-    :class:`~eth_tester.backends.base.BaseChainBackend` class provided by the ``eth-tester`` library.
-    If you would like a custom eth-tester instance to test with, see the
-    ``eth-tester`` library `documentation <https://github.com/ethereum/eth-tester>`_ for details.
-
-    .. code-block:: python
-
-        >>> from web3 import Web3, EthereumTesterProvider
-        >>> w3 = Web3(EthereumTesterProvider())
-
-.. NOTE:: To install the needed dependencies to use EthereumTesterProvider, you can install the
-    pip extras package that has the correct interoperable versions of the ``eth-tester``
-    and ``py-evm`` dependencies needed to do testing: e.g. ``pip install web3[tester]``
-
-
-
 AutoProvider
 ~~~~~~~~~~~~
 
@@ -255,7 +229,6 @@ AutoProvider
 explicitly.
 
 
-
 AsyncHTTPProvider
 ~~~~~~~~~~~~~~~~~
 
@@ -277,9 +250,9 @@ AsyncHTTPProvider
     .. code-block:: python
 
         >>> from aiohttp import ClientSession
-        >>> from web3 import Web3, AsyncHTTPProvider
+        >>> from web3 import AsyncWeb3, AsyncHTTPProvider
 
-        >>> w3 = Web3(AsyncHTTPProvider(endpoint_uri))
+        >>> w3 = AsyncWeb3(AsyncHTTPProvider(endpoint_uri))
 
         >>> # If you want to pass in your own session:
         >>> custom_session = ClientSession()
@@ -370,3 +343,29 @@ Supported Middleware
 - :meth:`Validation Middleware <web3.middleware.validation>`
 - :ref:`Geth POA Middleware <geth-poa>`
 - :meth:`Simple Cache Middleware <web3.middleware.simple_cache_middleware>`
+
+
+.. py:currentmodule:: web3.providers.eth_tester
+
+EthereumTesterProvider
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning:: Experimental:  This provider is experimental. There are still significant gaps in
+    functionality. However it is being actively developed and supported.
+
+.. py:class:: EthereumTesterProvider(eth_tester=None)
+
+    This provider integrates with the ``eth-tester`` library.  The ``eth_tester`` constructor
+    argument should be an instance of the :class:`~eth_tester.EthereumTester` or a subclass of
+    :class:`~eth_tester.backends.base.BaseChainBackend` class provided by the ``eth-tester`` library.
+    If you would like a custom eth-tester instance to test with, see the
+    ``eth-tester`` library `documentation <https://github.com/ethereum/eth-tester>`_ for details.
+
+    .. code-block:: python
+
+        >>> from web3 import Web3, EthereumTesterProvider
+        >>> w3 = Web3(EthereumTesterProvider())
+
+.. NOTE:: To install the needed dependencies to use EthereumTesterProvider, you can install the
+    pip extras package that has the correct interoperable versions of the ``eth-tester``
+    and ``py-evm`` dependencies needed to do testing: e.g. ``pip install web3[tester]``

docs/quickstart.rst

@@ -59,15 +59,15 @@ Local Providers
 ***************
 
 The hardware requirements are `steep <https://ethereum.org/en/developers/docs/nodes-and-clients/run-a-node/#top>`_,
-but the safest way to interact with Ethereum is to run an Ethereum client on your own hardware. 
+but the safest way to interact with Ethereum is to run an Ethereum client on your own hardware.
 For locally run nodes, an IPC connection is the most secure option, but HTTP and
 websocket configurations are also available. By default, the popular `Geth client <https://geth.ethereum.org/>`_
 exposes port ``8545`` to serve HTTP requests and ``8546`` for websocket requests. Connecting
 to this local node can be done as follows:
 
 .. code-block:: python
 
-   >>> from web3 import Web3
+   >>> from web3 import Web3, AsyncWeb3
 
    # IPCProvider:
    >>> w3 = Web3(Web3.IPCProvider('./path/to/geth.ipc'))
@@ -81,6 +81,17 @@ to this local node can be done as follows:
    >>> w3.is_connected()
    True
 
+   # AsyncHTTPProvider:
+   >>> w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider('http://127.0.0.1:8545'))
+
+   >>> await w3.is_connected()
+   True
+
+.. note::
+
+   The AsyncHTTPProvider is still under active development. Not all JSON-RPC
+   methods and middleware are available yet. The list of available methods and
+   middleware can be seen on the :class:`~web3.providers.async_rpc.AsyncHTTPProvider` docs
 
 Remote Providers
 ****************
@@ -91,14 +102,22 @@ You can connect to a remote node by specifying the endpoint, just like the previ
 
 .. code-block:: python
 
-   >>> from web3 import Web3
+   >>> from web3 import Web3, AsyncWeb3
 
    >>> w3 = Web3(Web3.HTTPProvider('https://<your-provider-url>'))
 
+   >>> w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider('https://<your-provider-url>'))
+
    >>> w3 = Web3(Web3.WebsocketProvider('wss://<your-provider-url>'))
 
 This endpoint is provided by the remote node service after you create an account.
 
+.. note::
+
+   The AsyncHTTPProvider is still under active development. Not all JSON-RPC
+   methods and middleware are available yet. The list of available methods and
+   middleware can be seen on the :class:`~web3.providers.async_rpc.AsyncHTTPProvider` docs
+
 .. _first_w3_use:
 
 

newsfragments/2821.doc.rst

@@ -0,0 +1 @@
+Add/cleanup docs for the ``AsyncHTTPProvider`` in light of the new ``AsyncWeb3`` class