Clean up waitForTransactionReceipt for merging

- stimulate -> simulate
- poll latency reduced to 100ms
- plenty of invocations for test to try out
- doc fixups

Author: carver

conftest.py

@@ -111,4 +111,3 @@ def web3():
     w3.eth.enable_unaudited_features()
 
     return w3
-

docs/web3.eth.rst

@@ -328,16 +328,20 @@ The following methods are available on the ``web3.eth`` namespace.
         })
 
 
-.. py:method:: Eth.waitForTransactionReceipt(transaction_hash)
+.. py:method:: Eth.waitForTransactionReceipt(transaction_hash, timeout=120)
 
-    * Delegates to ``wait_for_transaction_receipt`` Method from ``web3.utils.transactions``
+    Waits for the transaction specified by ``transaction_hash`` to be included in a block, then
+    returns its transaction receipt.
 
-    Returns the transaction receipt specified by ``transaction_hash``.  It waits for transaction to mine before returning the receipt.
+    Optionally, specify a ``timeout`` in seconds. If timeout elapses before the transaction
+    is added to a block, then :meth:`~Eth.waitForTransactionReceipt` returns None.
 
     .. code-block:: python
 
-        >>> web3.eth.waitForTransactionReceipt('0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060')  # not yet mined
-        # waits for transaction to mine before returning transaction data
+        >>> web3.eth.waitForTransactionReceipt('0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060')
+        # If transaction is not yet in a block, time passes, while the thread sleeps...
+        # ...
+        # Then when the transaction is added to a block, its receipt is returned:
         AttributeDict({
             'blockHash': '0x4e3a3754410177e6937ef1f84bba68ea139e8d1a2258c5f85db9f1cd715a1bdd',
             'blockNumber': 46147,

tests/core/eth-module/test_transactions.py

@@ -3,7 +3,7 @@
 from web3.exceptions import (
     ValidationError,
 )
-from web3.middleware.stimulate_unmined_transaction import (
+from web3.middleware.simulate_unmined_transaction import (
     unmined_receipt_simulator_middleware,
 )
 
@@ -52,8 +52,7 @@ def test_unmined_transaction_wait_for_receipt(web3, extra_accounts):
         'value': 123457
     })
     assert web3.eth.getTransactionReceipt(txn_hash) is None
-    assert web3.eth.getTransactionReceipt(txn_hash) is None
-    txn_receipt = web3.eth.getTransactionReceipt(txn_hash)
-    print(txn_receipt)
+
+    txn_receipt = web3.eth.waitForTransactionReceipt(txn_hash)
     assert txn_receipt['transactionHash'] == txn_hash
-    assert txn_receipt['blockHash']
+    assert txn_receipt['blockHash'] is not None

web3/eth.py

@@ -204,8 +204,7 @@ def getTransactionFromBlock(self, block_identifier, transaction_index):
         )
 
     def waitForTransactionReceipt(self, transaction_hash, timeout=120):
-        txn_receipt = wait_for_transaction_receipt(self.web3, transaction_hash, timeout)
-        return txn_receipt
+        return wait_for_transaction_receipt(self.web3, transaction_hash, timeout)
 
     def getTransactionReceipt(self, transaction_hash):
         return self.web3.manager.request_blocking(

web3/middleware/stimulate_unmined_transaction.py renamed to web3/middleware/simulate_unmined_transaction.py

@@ -3,14 +3,19 @@
 
 counter = itertools.count()
 
+INVOCATIONS_BEFORE_RESULT = 5
+
 
 def unmined_receipt_simulator_middleware(make_request, web3):
     receipt_counters = collections.defaultdict(itertools.count)
 
     def middleware(method, params):
         if method == 'eth_getTransactionReceipt':
             txn_hash = params[0]
-            if next(receipt_counters[txn_hash]) < 2:
+            if next(receipt_counters[txn_hash]) < INVOCATIONS_BEFORE_RESULT:
                 return {'result': None}
-        return make_request(method, params)
+            else:
+                return make_request(method, params)
+        else:
+            return make_request(method, params)
     return middleware

web3/utils/transactions.py

@@ -1,5 +1,4 @@
 import math
-import random
 
 from cytoolz import (
     assoc,
@@ -50,13 +49,13 @@ def fill_transaction_defaults(web3, transaction):
     return merge(defaults, transaction)
 
 
-def wait_for_transaction_receipt(web3, txn_hash, timeout=120):
+def wait_for_transaction_receipt(web3, txn_hash, timeout=120, poll_latency=0.1):
     with Timeout(timeout) as _timeout:
         while True:
             txn_receipt = web3.eth.getTransactionReceipt(txn_hash)
             if txn_receipt is not None:
                 break
-            _timeout.sleep(random.random())
+            _timeout.sleep(poll_latency)
     return txn_receipt