From 8a217ae2361f8959e9797d1c1d7a642835e9d24f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20N=C3=BA=C3=B1ez?= Date: Mon, 1 Jun 2020 20:31:29 +0200 Subject: [PATCH] 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 --- docs/middleware.rst | 7 +++-- docs/web3.eth.rst | 12 +++++--- docs/web3.geth.rst | 63 +++++++++++++++++++------------------- newsfragments/1663.doc.rst | 1 + 4 files changed, 45 insertions(+), 38 deletions(-) create mode 100644 newsfragments/1663.doc.rst diff --git a/docs/middleware.rst b/docs/middleware.rst index ab4337d9d7..e1bded2720 100644 --- 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 index afd7bc437b..f7f3707b53 100644 --- 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 index 4afc2a9e02..286aaf1df0 100644 --- 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 >>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 >>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 >>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 >>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 >>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 >>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 >>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 >>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 >>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 new file mode 100644 index 0000000000..0bfa72733e --- /dev/null +++ b/newsfragments/1663.doc.rst @@ -0,0 +1 @@ +Corrects the return value of ``getTransactionReceipt``, description of caching middleware, and deprecated method names.