diff --git a/docs/overview.rst b/docs/overview.rst index b6e43d9002..0a40f6ebae 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -13,28 +13,28 @@ greater detail. Configuration ~~~~~~~~~~~~~ -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. +After installing web3.py (via ``pip install web3``), you'll need to configure +a provider endpoint and any middleware you want to use beyond the defaults. Providers --------- -Providers are how web3.py connects to the blockchain. The library comes with the +:doc:`providers` are how web3.py connects to a blockchain. The library comes with the 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. +- :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. -Synchronous Provider Examples: ------------------------------- +Examples +^^^^^^^^ + .. code-block:: python - >>> from web3 import Web3 + >>> from web3 import Web3, AsyncWeb3 # IPCProvider: >>> w3 = Web3(Web3.IPCProvider('./path/to/geth.ipc')) @@ -48,33 +48,19 @@ Synchronous Provider Examples: >>> 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 - + # AsyncHTTPProvider: >>> 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. +For more context, see the :doc:`providers` documentation. Middleware ---------- -Your web3.py instance may be further configured via middleware. +Your web3.py instance may be further configured via :doc:`middleware`. web3.py middleware is described using an onion metaphor, where each layer of middleware may affect both the incoming request and outgoing response from your @@ -88,8 +74,8 @@ Several middleware are :ref:`included by default `. You may :meth:`clear `) any of these middleware. -Your Keys -~~~~~~~~~ +Accounts and Private Keys +~~~~~~~~~~~~~~~~~~~~~~~~~ Private keys are required to approve any transaction made on your behalf. The manner in which your key is secured will determine how you create and send transactions in web3.py. @@ -103,6 +89,7 @@ In this case, you'll need to have your private key available locally for signing transactions. Full documentation on the distinction between keys can be found :ref:`here `. +The separate guide to :doc:`transactions` may also help clarify how to manage keys. Base API @@ -148,8 +135,8 @@ web3.eth API ~~~~~~~~~~~~ The most commonly used APIs for interacting with Ethereum can be found under the -``web3.eth`` namespace. As a reminder, the :ref:`Examples ` page will -demonstrate how to use several of these methods. +``web3.eth`` namespace. As a reminder, the :doc:`examples` page will demonstrate +how to use several of these methods. Fetching Data @@ -177,13 +164,14 @@ API - :meth:`web3.eth.get_uncle_count() ` -Making Transactions -------------------- +Sending Transactions +-------------------- The most common use cases will be satisfied with :meth:`send_transaction ` or the combination of :meth:`sign_transaction ` and -:meth:`send_raw_transaction `. +:meth:`send_raw_transaction `. For more context, +see the full guide to :doc:`transactions`. .. note:: @@ -213,13 +201,12 @@ API Contracts --------- -The two most common use cases involving smart contracts are deploying and executing -functions on a deployed contract. +web3.py can help you deploy, read from, or execute functions on a deployed contract. Deployment requires that the contract already be compiled, with its bytecode and ABI available. This compilation step can be done within `Remix `_ or one of the many contract development -frameworks, such as `Brownie `_. +frameworks, such as `Ape `_. Once the contract object is instantiated, calling ``transact`` on the :meth:`constructor ` method will deploy an @@ -233,8 +220,8 @@ instance of the contract: >>> tx_receipt.contractAddress '0x8a22225eD7eD460D7ee3842bce2402B9deaD23D3' -Once loaded into a Contract object, the functions of a deployed contract are available -on the ``functions`` namespace: +Once a deployed contract is loaded into a Contract object, the functions of that +contract are available on the ``functions`` namespace: .. code-block:: python @@ -295,7 +282,7 @@ a contract, you can leverage web3.py filters. >>> new_filter.get_new_entries() More complex patterns for creating filters and polling for logs can be found in the -:ref:`Filtering ` documentation. +:doc:`filters` documentation. API diff --git a/docs/web3.eth.account.rst b/docs/web3.eth.account.rst index 1891907100..33bcff2541 100644 --- a/docs/web3.eth.account.rst +++ b/docs/web3.eth.account.rst @@ -1,12 +1,12 @@ .. _eth-account: Working with Local Private Keys -========================================== +=============================== .. _local_vs_hosted: Local vs Hosted Nodes ---------------------------------- +--------------------- Local Node A local node is started and controlled by you. It is as safe as you keep it. @@ -17,7 +17,7 @@ Hosted Node connected to a hosted node. Local vs Hosted Keys ---------------------------------- +-------------------- Local Private Key A key is 32 :class:`bytes` of data that you can use to sign transactions and messages, @@ -165,7 +165,7 @@ This will print:: .. _extract_geth_pk: Extract private key from geth keyfile ---------------------------------------------- +------------------------------------- .. NOTE:: The amount of available ram should be greater than 1GB. @@ -178,7 +178,7 @@ Extract private key from geth keyfile # tip: do not save the key or password anywhere, especially into a shared source file Sign a Message ---------------- +-------------- .. WARNING:: There is no single message format that is broadly adopted with community consensus. Keep an eye on several options, @@ -208,7 +208,7 @@ is provided by :meth:`w3.eth.sign() `. signature=HexBytes('0xe6ca9bba58c88611fad66a6ce8f996908195593807c4b38bd528d2cff09d4eb33e5bfbbf4d3e39b1a2fd816a7680c19ebebaf3a141b239934ad43cb33fcec8ce1c')) Verify a Message ------------------------------------------------- +---------------- With the original message text and a signature: @@ -219,7 +219,7 @@ With the original message text and a signature: '0x5ce9454909639D2D17A3F753ce7d93fa0b9aB12E' Prepare message for ecrecover in Solidity --------------------------------------------- +----------------------------------------- Let's say you want a contract to validate a signed message, like if you're making payment channels, and you want to @@ -288,7 +288,7 @@ this will prepare it for Solidity: Verify a message with ecrecover in Solidity ---------------------------------------------- +------------------------------------------- Create a simple ecrecover contract in `Remix `_: @@ -312,7 +312,7 @@ the message back in response: ``0x5ce9454909639d2d17a3f753ce7d93fa0b9ab12e``. .. _local-sign-transaction: Sign a Transaction ------------------------- +------------------ Create a transaction, sign it locally, and then send it to your node for broadcasting, with :meth:`~web3.eth.Eth.send_raw_transaction`. @@ -360,7 +360,7 @@ with :meth:`~web3.eth.Eth.send_raw_transaction`. '0xe85ce7efa52c16cb5c469c7bde54fbd4911639fdfde08003f65525a85076d915' Sign a Contract Transaction ------------------------------------ +--------------------------- To sign a transaction locally that will invoke a smart contract: diff --git a/newsfragments/2938.doc.rst b/newsfragments/2938.doc.rst new file mode 100644 index 0000000000..ef2a0d305f --- /dev/null +++ b/newsfragments/2938.doc.rst @@ -0,0 +1 @@ +Cleanup Overview page links and context