diff --git a/docs/overview.rst b/docs/overview.rst index a2deb7266b..b6e43d9002 100644 --- a/docs/overview.rst +++ b/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 ` documentation. diff --git a/docs/providers.rst b/docs/providers.rst index 700dc79c69..535c6e88fe 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 ~~~~~~~~~~~~ @@ -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 ` - :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 1e66ede6ca..61a88bee82 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')) @@ -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://')) + >>> w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider('https://')) + >>> w3 = Web3(Web3.WebsocketProvider('wss://')) 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: 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