Fix docs of Eth.getTransactionReceipt and web3.middleware (#1663)

* Update docs of Eth.getTransactionReceipt to show it raises an exception when TX yet not mined * Consistent argument names in docs of web3.geth.personal.new_account * Fix wrong docs for web3.middleware.construct_latest_block_based_cache_middleware * Missing prompt space in web3.geth docs * Additional touches to web3.eth docs * Fix formatting issue in web3.geth.personal.unlock_account docs * Fix wrong deprecation warnings in web3.geth * Add newsfragment Co-authored-by: Marc Garreau <[email protected]>
ethereum · Jun 1, 2020 · 8a217ae · 8a217ae
1 parent 6258d2e
commit 8a217ae
Show file tree

Hide file tree

Showing 4 changed files with 45 additions and 38 deletions.
diff --git a/docs/middleware.rst b/docs/middleware.rst
@@ -308,8 +308,11 @@ All of the caching middlewares accept these common arguments.
 .. py:method:: web3.middleware.construct_latest_block_based_cache_middleware(cache_class, average_block_time_sample_size, default_average_block_time, rpc_whitelist, should_cache_fn)
 
     Constructs a middleware which will cache the return values for any RPC
-    method in the ``rpc_whitelist`` for an amount of time defined by
-    ``cache_expire_seconds``.
+    method in the ``rpc_whitelist`` for the latest block.
+    It avoids re-fetching the current latest block for each
+    request by tracking the current average block time and only requesting
+    a new block when the last seen latest block is older than the average
+    block time.
 
     * ``average_block_time_sample_size`` The number of blocks which should be
       sampled to determine the average block time.

diff --git a/docs/web3.eth.rst b/docs/web3.eth.rst
@@ -454,9 +454,9 @@ The following methods are available on the ``web3.eth`` namespace.
 
 .. py:method:: Eth.getTransaction(transaction_hash)
 
-    * Delegates to ``eth_getTransactionByHAsh`` RPC Method
+    * Delegates to ``eth_getTransactionByHash`` RPC Method
 
-    Returns the transaction specified by ``transaction_hash``. If the transaction has not yet been mined returns ``TransactionNotFound``.
+    Returns the transaction specified by ``transaction_hash``. If the transaction has not yet been mined throws :class:`web3.exceptions.TransactionNotFound`.
 
     .. code-block:: python
 
@@ -491,7 +491,7 @@ The following methods are available on the ``web3.eth`` namespace.
     ``eth_getTransactionByBlockNumberAndIndex`` if ``block_identifier`` is an
     integer or one of the predefined block parameters ``'latest', 'earliest',
     'pending'``, otherwise delegates to
-    ``eth_getTransactionByBlockHashAndIndex``. If the transaction has not yet been mined returns ``TransactionNotFound``.
+    ``eth_getTransactionByBlockHashAndIndex``. If the transaction has not yet been mined throws :class:`web3.exceptions.TransactionNotFound`.
 
     .. code-block:: python
 
@@ -559,12 +559,14 @@ The following methods are available on the ``web3.eth`` namespace.
 
     * Delegates to ``eth_getTransactionReceipt`` RPC Method
 
-    Returns the transaction receipt specified by ``transaction_hash``.  If the transaction has not yet been mined returns ``TransactionNotFound``
+    Returns the transaction receipt specified by ``transaction_hash``.  If the transaction has not yet been mined throws :class:`web3.exceptions.TransactionNotFound`.
 
     .. code-block:: python
 
         >>> web3.eth.getTransactionReceipt('0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060')  # not yet mined
-        None
+        Traceback # ... etc ...
+        TransactionNotFound: Transaction with hash: 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060 not found.
+
         # wait for it to be mined....
         >>> web3.eth.getTransactionReceipt('0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060')
         AttributeDict({

diff --git a/docs/web3.geth.rst b/docs/web3.geth.rst
@@ -267,7 +267,7 @@ The following methods are available on the ``web3.geth.personal`` namespace.
       :meth:`~web3.geth.personal.import_raw_key()`
 
 
-.. py:method:: new_account(self, password)
+.. py:method:: new_account(self, passphrase)
 
     * Delegates to ``personal_newAccount`` RPC Method
 
@@ -276,14 +276,14 @@ The following methods are available on the ``web3.geth.personal`` namespace.
 
     .. code-block:: python
 
-        >>> web3.geth.personal.newAccount('the-passphrase')
+        >>> web3.geth.personal.new_account('the-passphrase')
         '0xd3CdA913deB6f67967B99D67aCDFa1712C293601'
 
 
 .. py:method:: newAccount()
 
     .. warning:: Deprecated: This method is deprecated in favor of
-      :meth:`~web3.geth.personal.newAccount()`
+      :meth:`~web3.geth.personal.new_account()`
 
 
 .. py:method:: lock_account(self, account)
@@ -300,17 +300,18 @@ The following methods are available on the ``web3.geth.personal`` namespace.
 .. py:method:: lockAccount()
 
     .. warning:: Deprecated: This method is deprecated in favor of
-      :meth:`~web3.geth.personal.lockAccount()`
+      :meth:`~web3.geth.personal.lock_account()`
 
 
 .. py:method:: unlock_account(self, account, passphrase, duration=None)
 
     * Delegates to ``personal_unlockAccount`` RPC Method
 
-    Unlocks the given ``account`` for ``duration`` seconds. If ``duration`` is
-	``None`` then the account will remain unlocked for 300 seconds (which is current default by Geth v1.9.5),
-	if ``duration`` is set to ``0``, the account will remain unlocked indefinitely.
-	Returns boolean as to whether the account was successfully unlocked.
+    Unlocks the given ``account`` for ``duration`` seconds.
+    If ``duration`` is ``None``, then the account will remain unlocked
+    for 300 seconds (which is current default by Geth v1.9.5);
+    if ``duration`` is set to ``0``, the account will remain unlocked indefinitely.
+    Returns boolean as to whether the account was successfully unlocked.
 
     .. code-block:: python
 
@@ -323,7 +324,7 @@ The following methods are available on the ``web3.geth.personal`` namespace.
 .. py:method:: unlockAccount()
 
     .. warning:: Deprecated: This method is deprecated in favor of
-      :meth:`~web3.geth.personal.unlockAccount()`
+      :meth:`~web3.geth.personal.unlock_account()`
 
 
 .. py:method:: send_transaction(self, transaction, passphrase)
@@ -336,7 +337,7 @@ The following methods are available on the ``web3.geth.personal`` namespace.
 .. py:method:: sendTransaction()
 
     .. warning:: Deprecated: This method is deprecated in favor of
-      :meth:`~web3.geth.personal.sendTransaction()`
+      :meth:`~web3.geth.personal.send_transaction()`
 
 
 .. py:module:: web3.geth.txpool
@@ -546,7 +547,7 @@ Full documentation for Geth-supported endpoints can be found `here <https://gith
 
     .. code-block:: python
 
-        >>>web3.geth.shh.version()
+        >>> web3.geth.shh.version()
         6.0
 
 .. py:method:: Shh.info()
@@ -555,7 +556,7 @@ Full documentation for Geth-supported endpoints can be found `here <https://gith
 
     .. code-block:: python
 
-        >>>web3.geth.shh.info()
+        >>> web3.geth.shh.info()
         {'maxMessageSize': 1024, 'memory': 240, 'messages': 0, 'minPow': 0.2}
 
 .. py:method:: Shh.post(self, message)
@@ -578,7 +579,7 @@ Full documentation for Geth-supported endpoints can be found `here <https://gith
 
     .. code-block:: python
 
-        >>>web3.geth.shh.post({'payload': web3.toHex(text="test_payload"), 'pubKey': recipient_public, 'topic': '0x12340000', 'powTarget': 2.5, 'powTime': 2})
+        >>> web3.geth.shh.post({'payload': web3.toHex(text="test_payload"), 'pubKey': recipient_public, 'topic': '0x12340000', 'powTarget': 2.5, 'powTime': 2})
         True
 
 .. py:method:: Shh.newMessageFilter()
@@ -601,7 +602,7 @@ Full documentation for Geth-supported endpoints can be found `here <https://gith
 
     .. code-block:: python
 
-        >>>web3.geth.shh.new_message_filter({'topic': '0x12340000', 'privateKeyID': recipient_private})
+        >>> web3.geth.shh.new_message_filter({'topic': '0x12340000', 'privateKeyID': recipient_private})
         'b37c3106cfb683e8f01b5019342399e0d1d74e9160f69b27625faba7a6738554'
 
 .. py:method:: Shh.deleteMessageFilter()
@@ -618,7 +619,7 @@ Full documentation for Geth-supported endpoints can be found `here <https://gith
 
     .. code-block:: python
 
-        >>>web3.geth.shh.delete_message_filter('b37c3106cfb683e8f01b5019342399e0d1d74e9160f69b27625faba7a6738554')
+        >>> web3.geth.shh.delete_message_filter('b37c3106cfb683e8f01b5019342399e0d1d74e9160f69b27625faba7a6738554')
         True
 
 .. py:method:: Shh.getMessages()
@@ -634,7 +635,7 @@ Full documentation for Geth-supported endpoints can be found `here <https://gith
 
     .. code-block:: python
 
-        >>>web3.geth.shh.get_filter_messages('b37c3106cfb683e8f01b5019342399e0d1d74e9160f69b27625faba7a6738554')
+        >>> web3.geth.shh.get_filter_messages('b37c3106cfb683e8f01b5019342399e0d1d74e9160f69b27625faba7a6738554')
         [{
             'ttl': 50,
             'timestamp': 1524497850,
@@ -659,7 +660,7 @@ Full documentation for Geth-supported endpoints can be found `here <https://gith
 
     .. code-block:: python
 
-        >>>web3.geth.shh.set_max_message_size(1024)
+        >>> web3.geth.shh.set_max_message_size(1024)
         True
 
 .. py:method:: Shh.setMinPoW()
@@ -675,7 +676,7 @@ Full documentation for Geth-supported endpoints can be found `here <https://gith
 
     .. code-block:: python
 
-        >>>web3.geth.shh.set_min_pow(0.4)
+        >>> web3.geth.shh.set_min_pow(0.4)
         True
 
 .. py:method:: Shh.markTrustedPeer()
@@ -691,7 +692,7 @@ Full documentation for Geth-supported endpoints can be found `here <https://gith
 
     .. code-block:: python
 
-        >>>web3.geth.shh.mark_trusted_peer('enode://d25474361659861e9e651bc728a17e807a3359ca0d344afd544ed0f11a31faecaf4d74b55db53c6670fd624f08d5c79adfc8da5dd4a11b9213db49a3b750845e@52.178.209.125:30379')
+        >>> web3.geth.shh.mark_trusted_peer('enode://d25474361659861e9e651bc728a17e807a3359ca0d344afd544ed0f11a31faecaf4d74b55db53c6670fd624f08d5c79adfc8da5dd4a11b9213db49a3b750845e@52.178.209.125:30379')
         True
 
 ---------------
@@ -711,7 +712,7 @@ Asymmetric Keys
 
     .. code-block:: python
 
-        >>>web3.geth.shh.new_key_pair()
+        >>> web3.geth.shh.new_key_pair()
         '86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb'
 
 .. py:method:: Shh.addPrivateKey()
@@ -727,7 +728,7 @@ Asymmetric Keys
 
     .. code-block:: python
 
-        >>>web3.geth.shh.add_private_key('0x7b8190d96cd061a102e551ee36d08d4f3ca1f56fb0008ef5d70c56271d8c46d0')
+        >>> web3.geth.shh.add_private_key('0x7b8190d96cd061a102e551ee36d08d4f3ca1f56fb0008ef5d70c56271d8c46d0')
         '86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb'
 
 .. py:method:: Shh.deleteKeyPair()
@@ -743,7 +744,7 @@ Asymmetric Keys
 
     .. code-block:: python
 
-        >>>web3.geth.shh.delete_key_pair('86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb')
+        >>> web3.geth.shh.delete_key_pair('86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb')
         True
 
 .. py:method:: Shh.hasKeyPair()
@@ -759,7 +760,7 @@ Asymmetric Keys
 
     .. code-block:: python
 
-        >>>web3.geth.shh.has_key_pair('86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb')
+        >>> web3.geth.shh.has_key_pair('86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb')
         False
 
 .. py:method:: Shh.getPublicKey()
@@ -773,7 +774,7 @@ Asymmetric Keys
 
     .. code-block:: python
 
-        >>>web3.geth.shh.get_public_key('86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb')
+        >>> web3.geth.shh.get_public_key('86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb')
         '0x041b0777ceb8cf8748fe0bba5e55039d650a03eb0239a909f9ee345bbbad249f2aa236a4b8f41f51bd0a97d87c08e69e67c51f154d634ba51a224195212fc31e4e'
 
 .. py:method:: Shh.getPrivateKey()
@@ -787,7 +788,7 @@ Asymmetric Keys
 
     .. code-block:: python
 
-        >>>web3.geth.shh.get_private_key('86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb')
+        >>> web3.geth.shh.get_private_key('86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb')
         '0x7b8190d96cd061a102e551ee36d08d4f3ca1f56fb0008ef5d70c56271d8c46d0'
 
 ---------------
@@ -807,7 +808,7 @@ Symmetric Keys
 
     .. code-block:: python
 
-        >>>web3.geth.shh.new_sym_key()
+        >>> web3.geth.shh.new_sym_key()
         '6c388d63003deb378700c9dad87f67df0247e660647d6ba1d04321bbc2f6ce0c'
 
 .. py:method:: Shh.addSymKey()
@@ -823,7 +824,7 @@ Symmetric Keys
 
     .. code-block:: python
 
-        >>>web3.geth.shh.add_sym_key('0x58f6556e56a0d41b464a083161377c8a9c2e95156921f954f99ef97d41cebaa2')
+        >>> web3.geth.shh.add_sym_key('0x58f6556e56a0d41b464a083161377c8a9c2e95156921f954f99ef97d41cebaa2')
         '6c388d63003deb378700c9dad87f67df0247e660647d6ba1d04321bbc2f6ce0c'
 
 .. py:method:: Shh.generateSymKeyFromPassword()
@@ -839,7 +840,7 @@ Symmetric Keys
 
     .. code-block:: python
 
-        >>>web3.geth.shh.generate_sym_key_from_password('shh secret pwd')
+        >>> web3.geth.shh.generate_sym_key_from_password('shh secret pwd')
         '6c388d63003deb378700c9dad87f67df0247e660647d6ba1d04321bbc2f6ce0c'
 
 .. py:method:: Shh.hasSymKey()
@@ -855,7 +856,7 @@ Symmetric Keys
 
     .. code-block:: python
 
-        >>>web3.geth.shh.has_sym_key('6c388d63003deb378700c9dad87f67df0247e660647d6ba1d04321bbc2f6ce0c')
+        >>> web3.geth.shh.has_sym_key('6c388d63003deb378700c9dad87f67df0247e660647d6ba1d04321bbc2f6ce0c')
         False
 
 .. py:method:: Shh.getSymKey()
@@ -871,7 +872,7 @@ Symmetric Keys
 
     .. code-block:: python
 
-        >>>web3.geth.shh.get_sym_key('6c388d63003deb378700c9dad87f67df0247e660647d6ba1d04321bbc2f6ce0c')
+        >>> web3.geth.shh.get_sym_key('6c388d63003deb378700c9dad87f67df0247e660647d6ba1d04321bbc2f6ce0c')
         '0x58f6556e56a0d41b464a083161377c8a9c2e95156921f954f99ef97d41cebaa2'
 
 .. py:method:: Shh.deleteSymKey()
@@ -887,5 +888,5 @@ Symmetric Keys
 
     .. code-block:: python
 
-        >>>web3.geth.shh.delete_sym_key('6c388d63003deb378700c9dad87f67df0247e660647d6ba1d04321bbc2f6ce0c')
+        >>> web3.geth.shh.delete_sym_key('6c388d63003deb378700c9dad87f67df0247e660647d6ba1d04321bbc2f6ce0c')
         True
diff --git a/newsfragments/1663.doc.rst b/newsfragments/1663.doc.rst
@@ -0,0 +1 @@
+Corrects the return value of ``getTransactionReceipt``, description of caching middleware, and deprecated method names.