diff --git a/docs/filters.rst b/docs/filters.rst index 5f4355f6df..98b037a229 100644 --- a/docs/filters.rst +++ b/docs/filters.rst @@ -120,7 +120,7 @@ will return a new :class:`BlockFilter` object. Event Log Filters ----------------- -You can set up a filter for event logs using the web3.py contract api: +You can set up a filter for event logs using the web3.py contract api: :func:`web3.contract.Contract.events..createFilter`, which provides some conveniances for creating event log filters. Refer to the following example: @@ -137,7 +137,7 @@ equivalent filter creation would look like: .. code-block:: python - event_signature_hash = web3.sha3(text="eventName(uint32)").hex() + event_signature_hash = web3.keccak(text="eventName(uint32)").hex() event_filter = web3.eth.filter({ "address": myContract_address, "topics": [event_signature_hash, @@ -215,15 +215,15 @@ Asynchronous Filter Polling Starting with web3 version 4, the ``watch`` method was taken out of the web3 filter objects. There are many decisions to be made when designing a system regarding threading and concurrency. -Rather than force a decision, web3 leaves these choices up to the user. Below are some example +Rather than force a decision, web3 leaves these choices up to the user. Below are some example implementations of asynchronous filter-event handling that can serve as starting points. Single threaded concurrency with ``async`` and ``await`` """""""""""""""""""""""""""""""""""""""""""""""""""""""" Beginning in python 3.5, the ``async`` and ``await`` built-in keywords were added. These provide a -shared api for coroutines that can be utilized by modules such as the built-in asyncio_. Below is -an example event loop using asyncio_, that polls multiple web3 filter object, and passes new +shared api for coroutines that can be utilized by modules such as the built-in asyncio_. Below is +an example event loop using asyncio_, that polls multiple web3 filter object, and passes new entries to a handler. .. code-block:: python diff --git a/docs/index.rst b/docs/index.rst index 9787ac6f76..303e64e19a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,6 +15,7 @@ Contents quickstart overview node + v5_migration v4_migration filters contracts diff --git a/docs/overview.rst b/docs/overview.rst index 4235fb4d2f..a0e39146e8 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -294,6 +294,53 @@ Cryptographic Hashing >>> 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") + Modules ------- diff --git a/docs/v5_migration.rst b/docs/v5_migration.rst new file mode 100644 index 0000000000..92d287f3b7 --- /dev/null +++ b/docs/v5_migration.rst @@ -0,0 +1,97 @@ +Migrating your code from v4 to v5 +======================================= + +Web3.py follows `Semantic Versioning `_, which means +that version 5 introduced backwards-incompatible changes. If your +project depends on Web3.py v4, then you'll probably need to make some changes. + +Here are the most common required updates: + +Python 3.5 no longer supported. +------------------------------- + +You will need to upgrade to either Python 3.6 or 3.7 + +``eth-abi`` v1 no longer supported +---------------------------------- + +You will need to upgrade the ``eth-abi`` dependency to v2 or higher. + +Changes to base API +------------------- + +JSON-RPC Updates +~~~~~~~~~~~~~~~~ + +In v4, JSON-RPC calls that looked up transactions or blocks and +didn't find them, returned ``None``. Now if a transaction or +block is not found, a `BlockNotFound` or a `TransactionNotFound` +error will be thrown as appropriate. This applies to the +following web3 methods: + +- :meth:`~web3.eth.Eth.getTransaction` will throw a ``TransactionNotFound`` error +- :meth:`~web3.eth.Eth.getTransactionReceipt` will throw a ``TransactionNotFound`` error +- :meth:`~web3.eth.Eth.getTransactionByBlock` will throw a ``TransactionNotFound`` error +- :meth:`~web3.eth.Eth.getTransactionCount` will throw a ``BlockNotFound`` error +- :meth:`~web3.eth.Eth.getBlock` will throw a ``BlockNotFound`` error +- :meth:`~web3.eth.Eth.getUncleCount` will throw a ``BlockNotFound`` error +- :meth:`~web3.eth.Eth.getUncleByBlock` will throw a ``BlockNotFound`` error + +Removed Methods +~~~~~~~~~~~~~~~ + +- ``contract.buildTransaction`` was removed for ``contract.functions.buildTransaction.`` +- ``contract.deploy`` was removed for ``contract.constructor.transact`` +- ``contract.estimateGas`` was removed for ``contract.functions..estimateGas`` +- ``contract.call`` was removed for ``contract...call`` +- ``contract.transact`` was removed for ``contract...transact`` +- ``contract.eventFilter`` was removed for ``contract.events..createFilter`` +- ``middleware_stack`` was renamed to :meth:`~Web3.middleware_onion` +- ``web3.miner.hashrate`` was a duplicate of :meth:`~web3.eth.Eth.hashrate` and was removed. +- ``web3.version.network`` was a duplicate of :meth:`~web3.net.Net.version` and was removed. +- ``web3.providers.tester.EthereumTesterProvider`` and ``web3.providers.tester.TestRPCProvider`` have been removed for :meth:`~web3.providers.eth_tester.EthereumTesterProvider` + +Deprecated Methods +~~~~~~~~~~~~~~~~~~ +Expect the following methods to be removed in v6: + +- ``web3.sha3`` was deprecated for :meth:`~Web3.keccak` +- ``web3.soliditySha3`` was deprecated for :meth:`~Web3.solidityKeccak` +- :meth:`~web3.eth.Eth.getTransactionFromBlock` has been deprecated according to EIP 1474 and does not have a replacement + +Manager Provider +~~~~~~~~~~~~~~~~ + +In v5, only a single provider will be allowed. While allowing +multiple providers is a feature we'd like to support in the future, +the way that multiple providers was handled in v4 wasn't ideal. +The only thing they could do was fall back. There was no mechanism for any +round robin, nor was there any control around which provider +was chosen. Eventually, the idea is to expand the Manager API +to support injecting custom logic into the provider selection process. + +For now, ``manager.providers`` has changed to ``manager.provider``. +Similarly, instances of ``web3.providers`` have been changed to +``web3.provider``. + +Testnet Changes +~~~~~~~~~~~~~~~ + +- Web3.py will no longer automatically look up a testnet connection + in IPCProvider. Something like ``from web3.auto.ropsten import w3`` + should be used instead. + +ENS +--- + +Web3.py has stopped inferring the ``.eth`` TLD on domain names. +If a domain name is used instead of an address, you'll need +to specify the TLD. An ``InvalidTLD`` error will be thrown if +the TLD is missing. + +Required Infura API Key +----------------------- + +In order to interact with Infura after March 27, 2019, you'll need to set an +environment variable called ``WEB3_INFURA_PROJECT_ID``. You can get a +project id by visiting https://infura.io/register. diff --git a/web3/_utils/events.py b/web3/_utils/events.py index 459459e30e..45affc85a4 100644 --- a/web3/_utils/events.py +++ b/web3/_utils/events.py @@ -144,7 +144,7 @@ def is_dynamic_sized_type(type_str: TypeStr) -> bool: @to_tuple def get_event_abi_types_for_decoding(event_inputs): """ - Event logs use the `sha3(value)` for indexed inputs of type `bytes` or + Event logs use the `keccak(value)` for indexed inputs of type `bytes` or `string`. Because of this we need to modify the types so that we can decode the log entries using the correct types. """ diff --git a/web3/contract.py b/web3/contract.py index 40a5e332ad..4a12d973a2 100644 --- a/web3/contract.py +++ b/web3/contract.py @@ -91,13 +91,6 @@ NoABIFunctionsFound, ) -DEPRECATED_SIGNATURE_MESSAGE = ( - "The constructor signature for the `Contract` object has changed. " - "Please update your code to reflect the updated function signature: " - "'Contract(address)'. To construct contract classes use the " - "'Contract.factory(...)' class method." -) - ACCEPTABLE_EMPTY_STRINGS = ["0x", b"0x", "", b""] diff --git a/web3/main.py b/web3/main.py index b346884583..4795b800ab 100644 --- a/web3/main.py +++ b/web3/main.py @@ -19,6 +19,7 @@ ) from web3._utils.decorators import ( combomethod, + deprecated_for, ) from web3._utils.empty import ( empty, @@ -157,6 +158,11 @@ def provider(self, provider): def clientVersion(self): return self.manager.request_blocking("web3_clientVersion", []) + @deprecated_for("keccak") + @apply_to_return_value(HexBytes) + def sha3(primitive=None, text=None, hexstr=None): + return Web3.keccak(primitive, text, hexstr) + @staticmethod @apply_to_return_value(HexBytes) def keccak(primitive=None, text=None, hexstr=None): @@ -173,6 +179,11 @@ def keccak(primitive=None, text=None, hexstr=None): ) ) + @combomethod + @deprecated_for("solidityKeccak") + def soliditySha3(cls, abi_types, values): + return cls.solidityKeccak(abi_types, values) + @combomethod def solidityKeccak(cls, abi_types, values): """