V5 upgrade guide

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.<event_name>.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

docs/index.rst

@@ -15,7 +15,7 @@ Contents
     quickstart
     overview
     node
-    v4_migration
+    v5_migration
     filters
     contracts
     providers

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
 -------
 

docs/v5_migration.rst

@@ -0,0 +1,93 @@
+Migrating your code from v4 to v5
+=======================================
+
+Web3.py follows `Semantic Versioning <http://semver.org>`_, 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, an error will be thrown. This applies to
+the following web3 methods:
+
+- :meth:`~web3.eth.Eth.getTransaction`
+- :meth:`~web3.eth.Eth.getTransactionReceipt`
+- :meth:`~web3.eth.Eth.getTransactionFromBlock`
+- :meth:`~web3.eth.Eth.getTransactionCount`
+- :meth:`~web3.eth.Eth.getBlock`
+- :meth:`~web3.eth.Eth.getUncleCount`
+- :meth:`~web3.eth.Eth.getUncleByBlock`
+
+Removed Methods
+~~~~~~~~~~~~~~~
+
+- ``contract.buildTransaction`` was removed for ``contract.functions.buildTransaction.<method name>``
+- ``contract.deploy`` was removed for ``contract.constructor.transact``
+- ``contract.estimateGas`` was removed for ``contract.functions.<method name>.estimateGas``
+- ``contract.call`` was removed for ``contract.<functions/events>.<method name>.call``
+- ``contract.transact`` was removed for ``contract.<functions/events>.<method name>.transact``
+- ``contract.eventFilter`` was removed for ``contract.events.<event name>.createFilter``
+- ``middleware_stack`` was removed for :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
+~~~~~~~~~~~~~~~~~~
+- ``web3.sha3`` was deprecated for :meth:`~Web3.keccak`
+- ``web3.soliditySha3`` was deprecated for :meth:`~Web3.solidityKeccak`
+
+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.

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.
     """

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""]
 
 

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):
         """