From 56954eacf2ce5bd1dee052d1466e41351432ed2c Mon Sep 17 00:00:00 2001 From: kclowes Date: Thu, 16 Feb 2023 16:37:31 -0700 Subject: [PATCH 1/6] Add some docs about the AsyncWeb3 --- docs/overview.rst | 34 ++++++++++++++++++++++++++++++---- docs/providers.rst | 5 +++-- 2 files changed, 33 insertions(+), 6 deletions(-) diff --git a/docs/overview.rst b/docs/overview.rst index a2deb7266b..6ba70097c4 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -13,12 +13,13 @@ 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 ---------- +Sync Providers +-------------- Providers are how web3.py connects to the blockchain. The library comes with the following built-in providers: @@ -47,6 +48,31 @@ For more information, (e.g., connecting to remote nodes, provider auto-detection using a test provider) see the :ref:`Providers ` documentation. +AsyncProvider +------------- + +- ``AsyncWeb3.AsyncHTTPProvider`` for connecting to http and https based JSON-RPC servers. + +.. 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 :ref:`AsyncHTTPProvider` docs + +.. code-block:: python + + >>> from web3 import AsyncWeb3 + + # AsyncHTTPProvider: + >>> w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider('http://127.0.0.1:8545')) + + >>> w3.is_connected() + True + +For more information, (e.g., connecting to remote nodes, provider auto-detection, +using a test provider) see the :ref:`Providers ` documentation. + + Middleware ---------- diff --git a/docs/providers.rst b/docs/providers.rst index 700dc79c69..d48a2fd173 100644 --- a/docs/providers.rst +++ b/docs/providers.rst @@ -255,6 +255,7 @@ AutoProvider explicitly. +.. _AsyncHTTPProvider: AsyncHTTPProvider ~~~~~~~~~~~~~~~~~ @@ -277,9 +278,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() From f460d506f594e69993f176c0f7ef15d750a0aa80 Mon Sep 17 00:00:00 2001 From: kclowes Date: Thu, 16 Feb 2023 16:41:21 -0700 Subject: [PATCH 2/6] Add AsyncWeb3 to quickstart --- docs/quickstart.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 1e66ede6ca..5116da625d 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -59,7 +59,7 @@ Local Providers *************** The hardware requirements are `steep `_, -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 `_ exposes port ``8545`` to serve HTTP requests and ``8546`` for websocket requests. Connecting @@ -67,7 +67,7 @@ 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')) @@ -75,6 +75,9 @@ to this local node can be done as follows: # HTTPProvider: >>> w3 = Web3(Web3.HTTPProvider('http://127.0.0.1:8545')) + # AsyncHTTPProvider: + >>> w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider('http://127.0.0.1:8545')) + # WebsocketProvider: >>> w3 = Web3(Web3.WebsocketProvider('wss://127.0.0.1:8546')) @@ -91,10 +94,12 @@ 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://')) + >>> w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider('https://')) + >>> w3 = Web3(Web3.WebsocketProvider('wss://')) This endpoint is provided by the remote node service after you create an account. From 504d014b0b5a3132804ed86a48a9e46ebb3d68d8 Mon Sep 17 00:00:00 2001 From: kclowes Date: Thu, 16 Feb 2023 16:50:32 -0700 Subject: [PATCH 3/6] Add note about AsyncHTTPProvider --- docs/quickstart.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 5116da625d..33b91f11d3 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -84,6 +84,11 @@ to this local node can be done as follows: >>> 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 :ref:`AsyncHTTPProvider` docs Remote Providers **************** @@ -104,6 +109,12 @@ You can connect to a remote node by specifying the endpoint, just like the previ 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 :ref:`AsyncHTTPProvider` docs + .. _first_w3_use: From 3493f13ce587681a417e7c662a045f03da6419b7 Mon Sep 17 00:00:00 2001 From: kclowes Date: Wed, 22 Feb 2023 14:14:29 -0700 Subject: [PATCH 4/6] Add more docs on AsyncHTTPProvider --- docs/overview.rst | 20 ++++++++--------- docs/providers.rst | 54 ++++++++++++++++++++++----------------------- docs/quickstart.rst | 9 +++++--- 3 files changed, 42 insertions(+), 41 deletions(-) diff --git a/docs/overview.rst b/docs/overview.rst index 6ba70097c4..9d702bcdb4 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -18,8 +18,8 @@ async or sync web3, the provider, and any middleware you want to use beyond the defaults. -Sync Providers --------------- +Providers +--------- Providers are how web3.py connects to the blockchain. The library comes with the following built-in providers: @@ -27,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 @@ -44,14 +48,9 @@ following built-in providers: >>> w3.is_connected() True -For more information, (e.g., connecting to remote nodes, provider auto-detection, -using a test provider) see the :ref:`Providers ` documentation. - -AsyncProvider -------------- - -- ``AsyncWeb3.AsyncHTTPProvider`` for connecting to http and https based JSON-RPC servers. +Asynchronous Provider Example: +------------------------------ .. note:: @@ -63,10 +62,9 @@ AsyncProvider >>> from web3 import AsyncWeb3 - # AsyncHTTPProvider: >>> w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider('http://127.0.0.1:8545')) - >>> w3.is_connected() + >>> await w3.is_connected() True For more information, (e.g., connecting to remote nodes, provider auto-detection, diff --git a/docs/providers.rst b/docs/providers.rst index d48a2fd173..56c7352d81 100644 --- a/docs/providers.rst +++ b/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 `_ 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 ~~~~~~~~~~~~ @@ -371,3 +345,29 @@ Supported Middleware - :meth:`Validation Middleware ` - :ref:`Geth POA Middleware ` - :meth:`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 `_ 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]`` diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 33b91f11d3..f5a46e889d 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -75,15 +75,18 @@ to this local node can be done as follows: # HTTPProvider: >>> w3 = Web3(Web3.HTTPProvider('http://127.0.0.1:8545')) - # AsyncHTTPProvider: - >>> w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider('http://127.0.0.1:8545')) - # WebsocketProvider: >>> w3 = Web3(Web3.WebsocketProvider('wss://127.0.0.1:8546')) >>> 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 From daa96f9f3917d5de5f23691020064e446bdf4b69 Mon Sep 17 00:00:00 2001 From: kclowes Date: Wed, 22 Feb 2023 14:23:04 -0700 Subject: [PATCH 5/6] Remove unneeded ref --- docs/overview.rst | 2 +- docs/providers.rst | 2 -- docs/quickstart.rst | 4 ++-- 3 files changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/overview.rst b/docs/overview.rst index 9d702bcdb4..b6e43d9002 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -56,7 +56,7 @@ Asynchronous Provider Example: 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 :ref:`AsyncHTTPProvider` docs + middleware can be seen on the :class:`~web3.providers.async_rpc.AsyncHTTPProvider` docs .. code-block:: python diff --git a/docs/providers.rst b/docs/providers.rst index 56c7352d81..535c6e88fe 100644 --- a/docs/providers.rst +++ b/docs/providers.rst @@ -229,8 +229,6 @@ AutoProvider explicitly. -.. _AsyncHTTPProvider: - AsyncHTTPProvider ~~~~~~~~~~~~~~~~~ diff --git a/docs/quickstart.rst b/docs/quickstart.rst index f5a46e889d..61a88bee82 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -91,7 +91,7 @@ to this local node can be done as follows: 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 :ref:`AsyncHTTPProvider` docs + middleware can be seen on the :class:`~web3.providers.async_rpc.AsyncHTTPProvider` docs Remote Providers **************** @@ -116,7 +116,7 @@ This endpoint is provided by the remote node service after you create an account 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 :ref:`AsyncHTTPProvider` docs + middleware can be seen on the :class:`~web3.providers.async_rpc.AsyncHTTPProvider` docs .. _first_w3_use: From 5e3af1adc3c5560d4bcda0037dcddd9302f5dc3f Mon Sep 17 00:00:00 2001 From: kclowes Date: Wed, 22 Feb 2023 14:24:53 -0700 Subject: [PATCH 6/6] Add newsfragment --- newsfragments/2821.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 newsfragments/2821.doc.rst diff --git a/newsfragments/2821.doc.rst b/newsfragments/2821.doc.rst new file mode 100644 index 0000000000..b8f15f8aeb --- /dev/null +++ b/newsfragments/2821.doc.rst @@ -0,0 +1 @@ +Add/cleanup docs for the ``AsyncHTTPProvider`` in light of the new ``AsyncWeb3`` class