From 498400848a56b539469440e1d54d1f4edf7a490b Mon Sep 17 00:00:00 2001 From: Marc Garreau Date: Thu, 9 Jul 2020 12:35:39 -0600 Subject: [PATCH] Overview documentation overhaul (#1681) * relocate Web3 Base API content from Overview * introduce new Overview content * plug the Overview in index.rst * add newsfragment + small copy cleanup * address PR feedback --- docs/ens_overview.rst | 2 + docs/ethpm.rst | 2 + docs/examples.rst | 2 + docs/filters.rst | 2 + docs/index.rst | 11 +- docs/middleware.rst | 2 + docs/overview.rst | 489 ++++++++++++++++--------------------- docs/web3.main.rst | 317 +++++++++++++++++++++++- newsfragments/1681.doc.rst | 1 + 9 files changed, 543 insertions(+), 285 deletions(-) create mode 100644 newsfragments/1681.doc.rst diff --git a/docs/ens_overview.rst b/docs/ens_overview.rst index 89ae116f16..3a11be01b6 100644 --- a/docs/ens_overview.rst +++ b/docs/ens_overview.rst @@ -1,3 +1,5 @@ +.. _ens_overview: + Ethereum Name Service ================================ diff --git a/docs/ethpm.rst b/docs/ethpm.rst index f8178ee049..32f5d4b6cb 100644 --- a/docs/ethpm.rst +++ b/docs/ethpm.rst @@ -1,3 +1,5 @@ +.. _ethpm: + ethPM ===== diff --git a/docs/examples.rst b/docs/examples.rst index d065d9dcc0..4c4b0b5725 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -1,3 +1,5 @@ +.. _examples: + Examples ======== diff --git a/docs/filters.rst b/docs/filters.rst index 61ad211865..efa363c2e7 100644 --- a/docs/filters.rst +++ b/docs/filters.rst @@ -1,3 +1,5 @@ +.. _filtering: + Filtering ========= diff --git a/docs/index.rst b/docs/index.rst index 03ba0f65a9..01e6d920ff 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,11 +16,12 @@ Getting Started Your next steps depend on where you're standing: -- Unfamiliar with Ethereum? `ethereum.org`_ -- Looking for Ethereum Python tutorials? `ethereum.org/python`_ -- Ready to code? :ref:`quickstart` -- Need help debugging? `StackExchange`_ -- Want to chat? `Gitter`_ +- Unfamiliar with Ethereum? → `ethereum.org`_ +- Looking for Ethereum Python tutorials? → `ethereum.org/python`_ +- Ready to code? → :ref:`quickstart` +- Interested in a quick tour? → :ref:`overview` +- Need help debugging? → `StackExchange`_ +- Want to chat? → `Gitter`_ Table of Contents ----------------- diff --git a/docs/middleware.rst b/docs/middleware.rst index e1bded2720..349241471f 100644 --- a/docs/middleware.rst +++ b/docs/middleware.rst @@ -15,6 +15,8 @@ that are in deeper layers). More information is available in the "Internals: :ref:`internals__middlewares`" section. +.. _default_middleware: + Default Middleware ------------------ diff --git a/docs/overview.rst b/docs/overview.rst index c5e1bed7e8..b4e4288399 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -1,380 +1,317 @@ +.. _overview: + Overview ======== -.. contents:: :local: +The purpose of this page is to give you a sense of everything Web3.py can do +and to serve as a quick reference guide. You'll find a summary of each feature +with links to learn more. You may also be interested in the +:ref:`Examples ` page, which demonstrates some of these features in +greater detail. + + +Configuration +~~~~~~~~~~~~~ -The common entrypoint for interacting with the Web3 library is the ``Web3`` -object. The web3 object provides APIs for interacting with the ethereum -blockchain, typically by connecting to a JSON-RPC server. +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. Providers --------- -*Providers* are how web3 connects to the blockchain. The Web3 library comes -with the following built-in providers that should be suitable for most normal -use cases. +Providers are how Web3.py connects to the blockchain. The library comes with the +following built-in providers: -- ``Web3.HTTPProvider`` for connecting to http and https based JSON-RPC servers. - ``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. -The ``HTTPProvider`` takes the full URI where the server can be found. For -local development this would be something like ``http://localhost:8545``. - -The ``IPCProvider`` takes the filesystem path where the IPC socket can be -found. If no argument is provided it will use the *default* path for your -operating system. - -The ``WebsocketProvider`` takes the full URI where the server can be found. For -local development this would be something like ``ws://127.0.0.1:8546``. - .. code-block:: python - >>> from web3 import Web3, HTTPProvider, IPCProvider, WebsocketProvider + >>> from web3 import Web3 - # Note that you should create only one RPCProvider per - # process, as it recycles underlying TCP/IP network connections between - # your process and Ethereum node - >>> w3 = Web3(HTTPProvider('http://localhost:8545')) + # IPCProvider: + >>> w3 = Web3(Web3.IPCProvider('./path/to/geth.ipc')) - # or for an IPC based connection - >>> w3 = Web3(IPCProvider()) + # HTTPProvider: + >>> w3 = Web3(Web3.HTTPProvider('http://127.0.0.1:8545')) - # or for Websocket based connection - >>> w3 = Web3(WebsocketProvider('ws://127.0.0.1:8546')) + # WebsocketProvider: + >>> w3 = Web3(Web3.WebsocketProvider('ws://127.0.0.1:8546')) + >>> w3.isConnected() + True -Base API --------- +For more information, (e.g., connecting to remote nodes, provider auto-detection, +using a test provider) see the :ref:`Providers ` documentation. -The ``Web3`` class exposes the following convenient APIs. +Middleware +---------- -.. _overview_type_conversions: +Your Web3.py instance may be further configured via middleware. -Type Conversions -~~~~~~~~~~~~~~~~ - -.. py:method:: Web3.toHex(primitive=None, hexstr=None, text=None) - - Takes a variety of inputs and returns it in its hexadecimal representation. - It follows the rules for converting to hex in the - `JSON-RPC spec`_ - - .. code-block:: python - - >>> Web3.toHex(0) - '0x0' - >>> Web3.toHex(1) - '0x1' - >>> Web3.toHex(0x0) - '0x0' - >>> Web3.toHex(0x000F) - '0xf' - >>> Web3.toHex(b'') - '0x' - >>> Web3.toHex(b'\x00\x0F') - '0x000f' - >>> Web3.toHex(False) - '0x0' - >>> Web3.toHex(True) - '0x1' - >>> Web3.toHex(hexstr='0x000F') - '0x000f' - >>> Web3.toHex(hexstr='000F') - '0x000f' - >>> Web3.toHex(text='') - '0x' - >>> Web3.toHex(text='cowmö') - '0x636f776dc3b6' +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 +provider. The documentation includes a :ref:`visualization ` +of this idea. -.. _JSON-RPC spec: https://github.com/ethereum/wiki/wiki/JSON-RPC#hex-value-encoding +Several middleware are :ref:`included by default `. You may add to +(:meth:`add `, :meth:`inject `, +:meth:`replace `) or disable +(:meth:`remove `, +:meth:`clear `) any of these middleware. -.. py:method:: Web3.toText(primitive=None, hexstr=None, text=None) - Takes a variety of inputs and returns its string equivalent. - Text gets decoded as UTF-8. +Your 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. - .. code-block:: python +A local node, like `Geth `_, may manage your keys for you. +You can reference those keys using the :attr:`web3.eth.accounts ` +property. - >>> Web3.toText(0x636f776dc3b6) - 'cowmö' - >>> Web3.toText(b'cowm\xc3\xb6') - 'cowmö' - >>> Web3.toText(hexstr='0x636f776dc3b6') - 'cowmö' - >>> Web3.toText(hexstr='636f776dc3b6') - 'cowmö' - >>> Web3.toText(text='cowmö') - 'cowmö' +A hosted node, like `Infura `_, will have no knowledge of your keys. +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 `. -.. py:method:: Web3.toBytes(primitive=None, hexstr=None, text=None) - Takes a variety of inputs and returns its bytes equivalent. - Text gets encoded as UTF-8. - - - .. code-block:: python +Base API +~~~~~~~~ - >>> Web3.toBytes(0) - b'\x00' - >>> Web3.toBytes(0x000F) - b'\x0f' - >>> Web3.toBytes(b'') - b'' - >>> Web3.toBytes(b'\x00\x0F') - b'\x00\x0f' - >>> Web3.toBytes(False) - b'\x00' - >>> Web3.toBytes(True) - b'\x01' - >>> Web3.toBytes(hexstr='0x000F') - b'\x00\x0f' - >>> Web3.toBytes(hexstr='000F') - b'\x00\x0f' - >>> Web3.toBytes(text='') - b'' - >>> Web3.toBytes(text='cowmö') - b'cowm\xc3\xb6' +The :ref:`Web3 ` class includes a number of convenient utility functions: -.. py:method:: Web3.toInt(primitive=None, hexstr=None, text=None) +Encoding and Decoding Helpers +----------------------------- - Takes a variety of inputs and returns its integer equivalent. +- :meth:`Web3.is_encodable() ` +- :meth:`Web3.toBytes() ` +- :meth:`Web3.toHex() ` +- :meth:`Web3.toInt() ` +- :meth:`Web3.toJSON() ` +- :meth:`Web3.toText() ` - .. code-block:: python +Address Helpers +--------------- - >>> Web3.toInt(0) - 0 - >>> Web3.toInt(0x000F) - 15 - >>> Web3.toInt(b'\x00\x0F') - 15 - >>> Web3.toInt(False) - 0 - >>> Web3.toInt(True) - 1 - >>> Web3.toInt(hexstr='0x000F') - 15 - >>> Web3.toInt(hexstr='000F') - 15 - -.. py:method:: Web3.toJSON(obj) - - Takes a variety of inputs and returns its JSON equivalent. - - - .. code-block:: python - - >>> Web3.toJSON(3) - '3' - >>> Web3.toJSON({'one': 1}) - '{"one": 1}' +- :meth:`Web3.isAddress() ` +- :meth:`Web3.isChecksumAddress() ` +- :meth:`Web3.toChecksumAddress() ` -.. _overview_currency_conversions: Currency Conversions -~~~~~~~~~~~~~~~~~~~~~ - -.. py:method:: Web3.toWei(value, currency) - - Returns the value in the denomination specified by the ``currency`` argument - converted to wei. - - - .. code-block:: python - - >>> Web3.toWei(1, 'ether') - 1000000000000000000 +-------------------- +- :meth:`Web3.fromWei() ` +- :meth:`Web3.toWei() ` -.. py:method:: Web3.fromWei(value, currency) - Returns the value in wei converted to the given currency. The value is returned - as a ``Decimal`` to ensure precision down to the wei. - - - .. code-block:: python - - >>> Web3.fromWei(1000000000000000000, 'ether') - Decimal('1') - - -.. _overview_addresses: - -Addresses -~~~~~~~~~~~~~~~~ - -.. py:method:: Web3.isAddress(value) - - Returns ``True`` if the value is one of the recognized address formats. - - * Allows for both ``0x`` prefixed and non-prefixed values. - * If the address contains mixed upper and lower cased characters this function also - checks if the address checksum is valid according to `EIP55`_ +Cryptographic Hashing +--------------------- - .. code-block:: python +- :meth:`Web3.keccak() ` +- :meth:`Web3.solidityKeccak() ` - >>> Web3.isAddress('0xd3CdA913deB6f67967B99D67aCDFa1712C293601') - True +web3.eth API +~~~~~~~~~~~~ -.. py:method:: Web3.isChecksumAddress(value) +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. - Returns ``True`` if the value is a valid `EIP55`_ checksummed address +Fetching Data +------------- - .. code-block:: python +Viewing account balances (:meth:`getBalance `), transactions +(:meth:`getTransaction `), and block data +(:meth:`getBlock `) are some of the most common starting +points in Web3.py. - >>> Web3.isChecksumAddress('0xd3CdA913deB6f67967B99D67aCDFa1712C293601') - True - >>> Web3.isChecksumAddress('0xd3cda913deb6f67967b99d67acdfa1712c293601') - False +API +^^^ -.. py:method:: Web3.toChecksumAddress(value) +- :meth:`web3.eth.getBalance() ` +- :meth:`web3.eth.getBlock() ` +- :meth:`web3.eth.getBlockTransactionCount() ` +- :meth:`web3.eth.getCode() ` +- :meth:`web3.eth.getProof() ` +- :meth:`web3.eth.getStorageAt() ` +- :meth:`web3.eth.getTransaction() ` +- :meth:`web3.eth.getTransactionByBlock() ` +- :meth:`web3.eth.getTransactionCount() ` +- :meth:`web3.eth.getUncleByBlock() ` +- :meth:`web3.eth.getUncleCount() ` - Returns the given address with an `EIP55`_ checksum. +Making Transactions +------------------- - .. code-block:: python +The most common use cases will be satisfied with +:meth:`sendTransaction ` or the combination of +:meth:`signTransaction ` and +:meth:`sendRawTransaction `. - >>> Web3.toChecksumAddress('0xd3cda913deb6f67967b99d67acdfa1712c293601') - '0xd3CdA913deB6f67967B99D67aCDFa1712C293601' +.. note:: -.. _EIP55: https://github.com/ethereum/EIPs/issues/55 + If interacting with a smart contract, a dedicated API exists. See the next + section, :ref:`Contracts `. -.. _overview_hashing: +API +^^^ -Cryptographic Hashing -~~~~~~~~~~~~~~~~~~~~~ +- :meth:`web3.eth.sendTransaction() ` +- :meth:`web3.eth.signTransaction() ` +- :meth:`web3.eth.sendRawTransaction() ` +- :meth:`web3.eth.replaceTransaction() ` +- :meth:`web3.eth.modifyTransaction() ` +- :meth:`web3.eth.waitForTransactionReceipt() ` +- :meth:`web3.eth.getTransactionReceipt() ` +- :meth:`web3.eth.sign() ` +- :meth:`web3.eth.signTypedData() ` +- :meth:`web3.eth.estimateGas() ` +- :meth:`web3.eth.generateGasPrice() ` +- :meth:`web3.eth.setGasPriceStrategy() ` -.. py:classmethod:: Web3.keccak(primitive=None, hexstr=None, text=None) - Returns the Keccak-256 of the given value. Text is encoded to UTF-8 before - computing the hash, just like Solidity. Any of the following are - valid and equivalent: +.. _overview_contracts: - .. code-block:: python +Contracts +--------- - >>> Web3.keccak(0x747874) - >>> Web3.keccak(b'\x74\x78\x74') - >>> Web3.keccak(hexstr='0x747874') - >>> Web3.keccak(hexstr='747874') - >>> Web3.keccak(text='txt') - HexBytes('0xd7278090a36507640ea6b7a0034b69b0d240766fa3f98e3722be93c613b29d2e') +The two most common use cases involving smart contracts are deploying and executing +functions on a deployed contract. -.. py:classmethod:: Web3.solidityKeccak(abi_types, value) +Deployment requires that the contract already be compiled, with its bytecode and ABI +available. This compilation step can done within +`Remix `_ or one of the many contract development +frameworks, such as `Brownie `_. - Returns the Keccak-256 as it would be computed by the solidity ``keccak`` - function on the provided ``value`` and ``abi_types``. The ``abi_types`` - value should be a list of solidity type strings which correspond to each - of the provided values. +Once the contract object is instantiated, calling ``transact`` on the +:meth:`constructor ` method will deploy an +instance of the contract: +.. code-block:: python - .. code-block:: python + >>> ExampleContract = w3.eth.contract(abi=abi, bytecode=bytecode) + >>> tx_hash = ExampleContract.constructor().transact() + >>> tx_receipt = w3.eth.waitForTransactionReceipt(tx_hash) + >>> tx_receipt.contractAddress + '0x8a22225eD7eD460D7ee3842bce2402B9deaD23D3' - >>> Web3.solidityKeccak(['bool'], [True]) - HexBytes("0x5fe7f977e71dba2ea1a68e21057beebb9be2ac30c6410aa38d4f3fbe41dcffd2") +Once loaded into a Contract object, the functions of a deployed contract are available +on the ``functions`` namespace: - >>> Web3.solidityKeccak(['uint8', 'uint8', 'uint8'], [97, 98, 99]) - HexBytes("0x4e03657aea45a94fc7d47ba826c8d667c0d1e6e33a64a036ec44f58fa12d6c45") +.. code-block:: python - >>> Web3.solidityKeccak(['uint8[]'], [[97, 98, 99]]) - HexBytes("0x233002c671295529bcc50b76a2ef2b0de2dac2d93945fca745255de1a9e4017e") + >>> deployed_contract = w3.eth.contract(address=tx_receipt.contractAddress, abi=abi) + >>> deployed_contract.functions.myFunction(42).transact() - >>> Web3.solidityKeccak(['address'], ["0x49EdDD3769c0712032808D86597B84ac5c2F5614"]) - HexBytes("0x2ff37b5607484cd4eecf6d13292e22bd6e5401eaffcc07e279583bc742c68882") +If you want to read data from a contract (or see the result of transaction locally, +without executing it on the network), you can use the +:meth:`ContractFunction.call ` method, or the +more concise :attr:`ContractCaller ` syntax: - >>> Web3.solidityKeccak(['address'], ["ethereumfoundation.eth"]) - HexBytes("0x913c99ea930c78868f1535d34cd705ab85929b2eaaf70fcd09677ecd6e5d75e9") +.. code-block:: python -.. py:classmethod:: Web3.sha3(primitive=None, hexstr=None, text=None) + # Using ContractFunction.call + >>> deployed_contract.functions.getMyValue().call() + 42 - .. WARNING:: - This method has been deprecated for :meth:`~Web3.keccak` + # Using ContractCaller + >>> deployed_contract.caller().getMyValue() + 42 - Returns the Keccak SHA256 of the given value. Text is encoded to UTF-8 before - computing the hash, just like Solidity. Any of the following are - valid and equivalent: +For more, see the full :ref:`Contracts` documentation. - .. code-block:: python - >>> Web3.sha3(0x747874) - >>> Web3.sha3(b'\x74\x78\x74') - >>> Web3.sha3(hexstr='0x747874') - >>> Web3.sha3(hexstr='747874') - >>> Web3.sha3(text='txt') - HexBytes('0xd7278090a36507640ea6b7a0034b69b0d240766fa3f98e3722be93c613b29d2e') +API +^^^ -.. py:classmethod:: Web3.soliditySha3(abi_types, value) +- :meth:`web3.eth.contract() ` +- :attr:`Contract.address ` +- :attr:`Contract.abi ` +- :attr:`Contract.bytecode ` +- :attr:`Contract.bytecode_runtime ` +- :attr:`Contract.functions ` +- :attr:`Contract.events ` +- :attr:`Contract.fallback ` +- :meth:`Contract.constructor() ` +- :meth:`Contract.encodeABI() ` +- :attr:`web3.contract.ContractFunction ` +- :attr:`web3.contract.ContractEvents ` - .. WARNING:: - This method has been deprecated for :meth:`~Web3.solidityKeccak` +Logs and Filters +---------------- - Returns the sha3 as it would be computed by the solidity ``sha3`` function - on the provided ``value`` and ``abi_types``. The ``abi_types`` value - should be a list of solidity type strings which correspond to each of the - provided values. +If you want to react to new blocks being mined or specific events being emitted by +a contract, you can leverage Web3.py filters. +.. code-block:: python - .. code-block:: python + # Use case: filter for new blocks + >>> new_filter = web3.eth.filter('latest') - >>> Web3.soliditySha3(['bool'], [True]) - HexBytes("0x5fe7f977e71dba2ea1a68e21057beebb9be2ac30c6410aa38d4f3fbe41dcffd2") + # Use case: filter for contract event "MyEvent" + >>> new_filter = deployed_contract.events.MyEvent.createFilter(fromBlock='latest') - >>> Web3.soliditySha3(['uint8', 'uint8', 'uint8'], [97, 98, 99]) - HexBytes("0x4e03657aea45a94fc7d47ba826c8d667c0d1e6e33a64a036ec44f58fa12d6c45") + # retrieve filter results: + >>> new_filter.get_all_entries() + >>> new_filter.get_new_entries() - >>> Web3.soliditySha3(['uint8[]'], [[97, 98, 99]]) - HexBytes("0x233002c671295529bcc50b76a2ef2b0de2dac2d93945fca745255de1a9e4017e") +More complex patterns for creating filters and polling for logs can be found in the +:ref:`Filtering ` documentation. - >>> Web3.soliditySha3(['address'], ["0x49EdDD3769c0712032808D86597B84ac5c2F5614"]) - HexBytes("0x2ff37b5607484cd4eecf6d13292e22bd6e5401eaffcc07e279583bc742c68882") - >>> Web3.soliditySha3(['address'], ["ethereumfoundation.eth"]) - HexBytes("0x913c99ea930c78868f1535d34cd705ab85929b2eaaf70fcd09677ecd6e5d75e9") +API +^^^ -Check Encodability -~~~~~~~~~~~~~~~~~~~~ +- :meth:`web3.eth.filter() ` +- :meth:`web3.eth.getFilterChanges() ` +- :meth:`web3.eth.getFilterLogs() ` +- :meth:`web3.eth.uninstallFilter() ` +- :meth:`web3.eth.getLogs() ` +- :meth:`Contract.events.your_event_name.createFilter() ` +- :meth:`Contract.events.your_event_name.build_filter() ` +- :meth:`Filter.get_new_entries() ` +- :meth:`Filter.get_all_entries() ` +- :meth:`Filter.format_entry() ` +- :meth:`Filter.is_valid_entry() ` -.. py:method:: w3.is_encodable(_type, value) - Returns ``True`` if a value can be encoded as the given type. Otherwise returns ``False``. +Net API +~~~~~~~ - .. code-block:: python +Some basic network properties are available on the ``web3.net`` object: - >>> from web3.auto.gethdev import w3 - >>> w3.is_encodable('bytes2', b'12') - True - >>> w3.is_encodable('bytes2', b'1') - True - >>> w3.is_encodable('bytes2', '0x1234') - True - >>> w3.is_encodable('bytes2', b'123') - False +- :attr:`web3.net.listening` +- :attr:`web3.net.peer_count` +- :attr:`web3.net.version` -.. py:method:: w3.enable_strict_bytes_type_checking() - Enables stricter bytes type checking. For more examples see :ref:`enable-strict-byte-check` +ethPM +~~~~~ - .. doctest:: +ethPM allows you to package up your contracts for reuse or use contracts from +another trusted registry. See the full details :ref:`here `. - >>> from web3.auto.gethdev import w3 - >>> w3.enable_strict_bytes_type_checking() - >>> w3.is_encodable('bytes2', b'12') - True - >>> w3.is_encodable('bytes2', b'1') - False -Modules -------- +ENS +~~~ -The JSON-RPC functionality is split across multiple modules which *loosely* -correspond to the namespaces of the underlying JSON-RPC methods. +`Ethereum Name Service (ENS) `_ provides the infrastructure +for human-readable addresses. As an example, instead of +``0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359``, you can send funds to +``ethereumfoundation.eth``. Web3.py has support for ENS, documented +:ref:`here `. diff --git a/docs/web3.main.rst b/docs/web3.main.rst index 92c5fd1a30..55112256e3 100644 --- a/docs/web3.main.rst +++ b/docs/web3.main.rst @@ -1,3 +1,5 @@ +.. _web3_base: + Web3 API ======== @@ -52,26 +54,333 @@ Attributes 'Geth/v1.4.11-stable-fed692f6/darwin/go1.7' +.. _overview_type_conversions: + Encoding and Decoding Helpers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See :ref:`overview_type_conversions` +.. py:method:: Web3.toHex(primitive=None, hexstr=None, text=None) + + Takes a variety of inputs and returns it in its hexadecimal representation. + It follows the rules for converting to hex in the + `JSON-RPC spec`_ + + .. code-block:: python + + >>> Web3.toHex(0) + '0x0' + >>> Web3.toHex(1) + '0x1' + >>> Web3.toHex(0x0) + '0x0' + >>> Web3.toHex(0x000F) + '0xf' + >>> Web3.toHex(b'') + '0x' + >>> Web3.toHex(b'\x00\x0F') + '0x000f' + >>> Web3.toHex(False) + '0x0' + >>> Web3.toHex(True) + '0x1' + >>> Web3.toHex(hexstr='0x000F') + '0x000f' + >>> Web3.toHex(hexstr='000F') + '0x000f' + >>> Web3.toHex(text='') + '0x' + >>> Web3.toHex(text='cowmö') + '0x636f776dc3b6' + +.. _JSON-RPC spec: https://github.com/ethereum/wiki/wiki/JSON-RPC#hex-value-encoding + +.. py:method:: Web3.toText(primitive=None, hexstr=None, text=None) + + Takes a variety of inputs and returns its string equivalent. + Text gets decoded as UTF-8. + + + .. code-block:: python + + >>> Web3.toText(0x636f776dc3b6) + 'cowmö' + >>> Web3.toText(b'cowm\xc3\xb6') + 'cowmö' + >>> Web3.toText(hexstr='0x636f776dc3b6') + 'cowmö' + >>> Web3.toText(hexstr='636f776dc3b6') + 'cowmö' + >>> Web3.toText(text='cowmö') + 'cowmö' + + +.. py:method:: Web3.toBytes(primitive=None, hexstr=None, text=None) + + Takes a variety of inputs and returns its bytes equivalent. + Text gets encoded as UTF-8. + + + .. code-block:: python + + >>> Web3.toBytes(0) + b'\x00' + >>> Web3.toBytes(0x000F) + b'\x0f' + >>> Web3.toBytes(b'') + b'' + >>> Web3.toBytes(b'\x00\x0F') + b'\x00\x0f' + >>> Web3.toBytes(False) + b'\x00' + >>> Web3.toBytes(True) + b'\x01' + >>> Web3.toBytes(hexstr='0x000F') + b'\x00\x0f' + >>> Web3.toBytes(hexstr='000F') + b'\x00\x0f' + >>> Web3.toBytes(text='') + b'' + >>> Web3.toBytes(text='cowmö') + b'cowm\xc3\xb6' + + +.. py:method:: Web3.toInt(primitive=None, hexstr=None, text=None) + + Takes a variety of inputs and returns its integer equivalent. + + + .. code-block:: python + + >>> Web3.toInt(0) + 0 + >>> Web3.toInt(0x000F) + 15 + >>> Web3.toInt(b'\x00\x0F') + 15 + >>> Web3.toInt(False) + 0 + >>> Web3.toInt(True) + 1 + >>> Web3.toInt(hexstr='0x000F') + 15 + >>> Web3.toInt(hexstr='000F') + 15 + +.. py:method:: Web3.toJSON(obj) + + Takes a variety of inputs and returns its JSON equivalent. + + + .. code-block:: python + + >>> Web3.toJSON(3) + '3' + >>> Web3.toJSON({'one': 1}) + '{"one": 1}' +.. _overview_currency_conversions: + Currency Conversions ~~~~~~~~~~~~~~~~~~~~~ -See :ref:`overview_currency_conversions` +.. py:method:: Web3.toWei(value, currency) + + Returns the value in the denomination specified by the ``currency`` argument + converted to wei. + + + .. code-block:: python + + >>> Web3.toWei(1, 'ether') + 1000000000000000000 + + +.. py:method:: Web3.fromWei(value, currency) + + Returns the value in wei converted to the given currency. The value is returned + as a ``Decimal`` to ensure precision down to the wei. + + + .. code-block:: python + + >>> Web3.fromWei(1000000000000000000, 'ether') + Decimal('1') + +.. _overview_addresses: Addresses ~~~~~~~~~ -See :ref:`overview_addresses` +.. py:method:: Web3.isAddress(value) + + Returns ``True`` if the value is one of the recognized address formats. + + * Allows for both ``0x`` prefixed and non-prefixed values. + * If the address contains mixed upper and lower cased characters this function also + checks if the address checksum is valid according to `EIP55`_ + + .. code-block:: python + + >>> Web3.isAddress('0xd3CdA913deB6f67967B99D67aCDFa1712C293601') + True + + +.. py:method:: Web3.isChecksumAddress(value) + + Returns ``True`` if the value is a valid `EIP55`_ checksummed address + + + .. code-block:: python + + >>> Web3.isChecksumAddress('0xd3CdA913deB6f67967B99D67aCDFa1712C293601') + True + >>> Web3.isChecksumAddress('0xd3cda913deb6f67967b99d67acdfa1712c293601') + False + + +.. py:method:: Web3.toChecksumAddress(value) + + Returns the given address with an `EIP55`_ checksum. + + + .. code-block:: python + + >>> Web3.toChecksumAddress('0xd3cda913deb6f67967b99d67acdfa1712c293601') + '0xd3CdA913deB6f67967B99D67aCDFa1712C293601' + +.. _EIP55: https://github.com/ethereum/EIPs/issues/55 + + +.. _overview_hashing: + +Cryptographic Hashing +~~~~~~~~~~~~~~~~~~~~~ + +.. py:classmethod:: Web3.keccak(primitive=None, hexstr=None, text=None) + + Returns the Keccak-256 of the given value. Text is encoded to UTF-8 before + computing the hash, just like Solidity. Any of the following are + valid and equivalent: + + .. code-block:: python + + >>> Web3.keccak(0x747874) + >>> Web3.keccak(b'\x74\x78\x74') + >>> Web3.keccak(hexstr='0x747874') + >>> Web3.keccak(hexstr='747874') + >>> Web3.keccak(text='txt') + HexBytes('0xd7278090a36507640ea6b7a0034b69b0d240766fa3f98e3722be93c613b29d2e') + +.. py:classmethod:: Web3.solidityKeccak(abi_types, value) + + Returns the Keccak-256 as it would be computed by the solidity ``keccak`` + function on the provided ``value`` and ``abi_types``. The ``abi_types`` + value should be a list of solidity type strings which correspond to each + of the provided values. + + + .. code-block:: python + + >>> Web3.solidityKeccak(['bool'], [True]) + HexBytes("0x5fe7f977e71dba2ea1a68e21057beebb9be2ac30c6410aa38d4f3fbe41dcffd2") + + >>> Web3.solidityKeccak(['uint8', 'uint8', 'uint8'], [97, 98, 99]) + HexBytes("0x4e03657aea45a94fc7d47ba826c8d667c0d1e6e33a64a036ec44f58fa12d6c45") + + >>> Web3.solidityKeccak(['uint8[]'], [[97, 98, 99]]) + HexBytes("0x233002c671295529bcc50b76a2ef2b0de2dac2d93945fca745255de1a9e4017e") + + >>> Web3.solidityKeccak(['address'], ["0x49EdDD3769c0712032808D86597B84ac5c2F5614"]) + HexBytes("0x2ff37b5607484cd4eecf6d13292e22bd6e5401eaffcc07e279583bc742c68882") + + >>> Web3.solidityKeccak(['address'], ["ethereumfoundation.eth"]) + HexBytes("0x913c99ea930c78868f1535d34cd705ab85929b2eaaf70fcd09677ecd6e5d75e9") + +.. py:classmethod:: Web3.sha3(primitive=None, hexstr=None, text=None) + + .. WARNING:: + This method has been deprecated for :meth:`~Web3.keccak` + + Returns the Keccak SHA256 of the given value. Text is encoded to UTF-8 before + computing the hash, just like Solidity. Any of the following are + valid and equivalent: + + .. code-block:: python + + >>> Web3.sha3(0x747874) + >>> Web3.sha3(b'\x74\x78\x74') + >>> Web3.sha3(hexstr='0x747874') + >>> Web3.sha3(hexstr='747874') + >>> Web3.sha3(text='txt') + HexBytes('0xd7278090a36507640ea6b7a0034b69b0d240766fa3f98e3722be93c613b29d2e') + +.. py:classmethod:: Web3.soliditySha3(abi_types, value) + + .. WARNING:: + This method has been deprecated for :meth:`~Web3.solidityKeccak` + + + Returns the sha3 as it would be computed by the solidity ``sha3`` function + on the provided ``value`` and ``abi_types``. The ``abi_types`` value + should be a list of solidity type strings which correspond to each of the + provided values. + + + .. code-block:: python + + >>> Web3.soliditySha3(['bool'], [True]) + HexBytes("0x5fe7f977e71dba2ea1a68e21057beebb9be2ac30c6410aa38d4f3fbe41dcffd2") + + >>> Web3.soliditySha3(['uint8', 'uint8', 'uint8'], [97, 98, 99]) + HexBytes("0x4e03657aea45a94fc7d47ba826c8d667c0d1e6e33a64a036ec44f58fa12d6c45") + + >>> Web3.soliditySha3(['uint8[]'], [[97, 98, 99]]) + HexBytes("0x233002c671295529bcc50b76a2ef2b0de2dac2d93945fca745255de1a9e4017e") + + >>> Web3.soliditySha3(['address'], ["0x49EdDD3769c0712032808D86597B84ac5c2F5614"]) + HexBytes("0x2ff37b5607484cd4eecf6d13292e22bd6e5401eaffcc07e279583bc742c68882") + + >>> Web3.soliditySha3(['address'], ["ethereumfoundation.eth"]) + HexBytes("0x913c99ea930c78868f1535d34cd705ab85929b2eaaf70fcd09677ecd6e5d75e9") + + +Check Encodability +~~~~~~~~~~~~~~~~~~~~ + +.. py:method:: w3.is_encodable(_type, value) + + Returns ``True`` if a value can be encoded as the given type. Otherwise returns ``False``. + + .. code-block:: python + + >>> from web3.auto.gethdev import w3 + >>> w3.is_encodable('bytes2', b'12') + True + >>> w3.is_encodable('bytes2', b'1') + True + >>> w3.is_encodable('bytes2', '0x1234') + True + >>> w3.is_encodable('bytes2', b'123') + False + +.. py:method:: w3.enable_strict_bytes_type_checking() + + Enables stricter bytes type checking. For more examples see :ref:`enable-strict-byte-check` + + .. doctest:: + + >>> from web3.auto.gethdev import w3 + >>> w3.enable_strict_bytes_type_checking() + >>> w3.is_encodable('bytes2', b'12') + True + >>> w3.is_encodable('bytes2', b'1') + False RPC APIS --------- +~~~~~~~~ Each ``web3`` instance also exposes these namespaced APIs. diff --git a/newsfragments/1681.doc.rst b/newsfragments/1681.doc.rst new file mode 100644 index 0000000000..5f1311fba9 --- /dev/null +++ b/newsfragments/1681.doc.rst @@ -0,0 +1 @@ +Overhaul the Overview documentation to provide a tour of major features.