Add docstrings for RPC methods

Author: fjarri

pons/_client.py

@@ -277,10 +277,11 @@ async def call(
     ) -> Any:
         """
         Sends a prepared contact method call to the provided address.
-        Returns the decoded output.
 
         If ``sender_address`` is provided, it will be included in the call
         and affect the return value if the method uses ``msg.sender`` internally.
+
+        The decoded output is returned according to :py:class:`Method.decode_output` rules.
         """
         with convert_errors(call.contract_abi):
             return await self._rpc.eth_call(call, block=block, sender_address=sender_address)

pons/_client_rpc.py

@@ -126,19 +126,19 @@ def __init__(self, provider_session: ProviderSession):
         self._provider_session = provider_session
 
     async def net_version(self) -> str:
-        """Calls the ``net_version`` RPC method."""
+        """Returns the current network id."""
         return await rpc_call(self._provider_session, "net_version", str)
 
     async def eth_chain_id(self) -> int:
-        """Calls the ``eth_chainId`` RPC method."""
+        """Returns the chain ID used for signing replay-protected transactions."""
         return await rpc_call(self._provider_session, "eth_chainId", int)
 
     async def eth_get_balance(self, address: Address, block: Block = BlockLabel.LATEST) -> Amount:
-        """Calls the ``eth_getBalance`` RPC method."""
+        """Returns the balance of the account of given address."""
         return await rpc_call(self._provider_session, "eth_getBalance", Amount, address, block)
 
     async def eth_get_transaction_by_hash(self, tx_hash: TxHash) -> None | TxInfo:
-        """Calls the ``eth_getTransactionByHash`` RPC method."""
+        """Returns the information about a transaction requested by transaction hash."""
         # Need an explicit cast, mypy doesn't work with union types correctly.
         # See https://github.com/python/mypy/issues/16935
         return cast(
@@ -152,7 +152,13 @@ async def eth_get_transaction_by_hash(self, tx_hash: TxHash) -> None | TxInfo:
         )
 
     async def eth_get_transaction_receipt(self, tx_hash: TxHash) -> None | TxReceipt:
-        """Calls the ``eth_getTransactionReceipt`` RPC method."""
+        """
+        Returns the receipt of a transaction by transaction hash.
+
+        .. note::
+
+            That the receipt is not available for pending transactions.
+        """
         # Need an explicit cast, mypy doesn't work with union types correctly.
         # See https://github.com/python/mypy/issues/16935
         return cast(
@@ -168,7 +174,7 @@ async def eth_get_transaction_receipt(self, tx_hash: TxHash) -> None | TxReceipt
     async def eth_get_transaction_count(
         self, address: Address, block: Block = BlockLabel.LATEST
     ) -> int:
-        """Calls the ``eth_getTransactionCount`` RPC method."""
+        """Returns the number of transactions sent from an address."""
         return await rpc_call(
             self._provider_session,
             "eth_getTransactionCount",
@@ -178,13 +184,13 @@ async def eth_get_transaction_count(
         )
 
     async def eth_get_code(self, address: Address, block: Block = BlockLabel.LATEST) -> bytes:
-        """Calls the ``eth_getCode`` RPC method."""
+        """Returns code at a given address."""
         return await rpc_call(self._provider_session, "eth_getCode", bytes, address, block)
 
     async def eth_get_storage_at(
         self, address: Address, position: int, block: Block = BlockLabel.LATEST
     ) -> bytes:
-        """Calls the ``eth_getCode`` RPC method."""
+        """Returns the value from a storage position at a given address."""
         return await rpc_call(
             self._provider_session,
             "eth_getStorageAt",
@@ -201,11 +207,14 @@ async def eth_call(
         sender_address: None | Address = None,
     ) -> Any:
         """
-        Sends a prepared contact method call to the provided address.
-        Returns the decoded output.
+        Executes a new message call immediately without creating a transaction on the blockchain.
+        Often used for executing read-only smart contract functions,
+        for example the ``balanceOf`` for an ERC-20 contract.
 
         If ``sender_address`` is provided, it will be included in the call
         and affect the return value if the method uses ``msg.sender`` internally.
+
+        The decoded output is returned according to :py:class:`Method.decode_output` rules.
         """
         params = EthCallParams(to=call.contract_address, data=call.data_bytes, from_=sender_address)
 
@@ -219,25 +228,35 @@ async def eth_call(
         return call.decode_output(encoded_output)
 
     async def eth_send_raw_transaction(self, tx_bytes: bytes) -> TxHash:
-        """Sends a signed and serialized transaction."""
+        """Creates new message call transaction or a contract creation for signed transactions."""
         return await rpc_call(self._provider_session, "eth_sendRawTransaction", TxHash, tx_bytes)
 
     async def eth_estimate_gas(self, params: EstimateGasParams, block: Block) -> int:
-        """Calls the ``eth_estimateGas`` RPC method."""
+        """
+        Generates and returns an estimate of how much gas is necessary
+        to allow the transaction to complete.
+        The transaction will not be added to the blockchain.
+        Note that the estimate may be significantly more than the amount of gas
+        actually used by the transaction, for a variety of reasons
+        including EVM mechanics and node performance.
+        """
         return await rpc_call(self._provider_session, "eth_estimateGas", int, params, block)
 
     async def eth_gas_price(self) -> Amount:
-        """Calls the ``eth_gasPrice`` RPC method."""
+        """
+        Returns an estimate of the current price per gas in wei,
+        according to a provider-specific algorithm.
+        """
         return await rpc_call(self._provider_session, "eth_gasPrice", Amount)
 
     async def eth_block_number(self) -> int:
-        """Calls the ``eth_blockNumber`` RPC method."""
+        """Returns the number of the most recent block."""
         return await rpc_call(self._provider_session, "eth_blockNumber", int)
 
     async def eth_get_block_by_hash(
         self, block_hash: BlockHash, *, with_transactions: bool = False
     ) -> None | BlockInfo:
-        """Calls the ``eth_getBlockByHash`` RPC method."""
+        """Returns information about a block by hash."""
         # Need an explicit cast, mypy doesn't work with union types correctly.
         # See https://github.com/python/mypy/issues/16935
         return cast(
@@ -254,7 +273,7 @@ async def eth_get_block_by_hash(
     async def eth_get_block_by_number(
         self, block: Block = BlockLabel.LATEST, *, with_transactions: bool = False
     ) -> None | BlockInfo:
-        """Calls the ``eth_getBlockByNumber`` RPC method."""
+        """Returns information about a block by block number."""
         # Need an explicit cast, mypy doesn't work with union types correctly.
         # See https://github.com/python/mypy/issues/16935
         return cast(
@@ -275,7 +294,7 @@ async def eth_get_logs(
         from_block: Block = BlockLabel.LATEST,
         to_block: Block = BlockLabel.LATEST,
     ) -> tuple[LogEntry, ...]:
-        """Calls the ``eth_getLogs`` RPC method."""
+        """Returns an array of all logs matching a given filter object."""
         if isinstance(source, Iterable):
             source = tuple(source)
         params = FilterParams(
@@ -287,14 +306,14 @@ async def eth_get_logs(
         return await rpc_call(self._provider_session, "eth_getLogs", tuple[LogEntry, ...], params)
 
     async def eth_new_block_filter(self) -> BlockFilter:
-        """Calls the ``eth_newBlockFilter`` RPC method."""
+        """Creates a filter in the node, to notify when a new block arrives."""
         result, provider_path = await rpc_call_pin(
             self._provider_session, "eth_newBlockFilter", int
         )
         return BlockFilter(id=result, provider_path=provider_path)
 
     async def eth_new_pending_transaction_filter(self) -> PendingTransactionFilter:
-        """Calls the ``eth_newPendingTransactionFilter`` RPC method."""
+        """Creates a filter in the node, to notify when new pending transactions arrive."""
         result, provider_path = await rpc_call_pin(
             self._provider_session, "eth_newPendingTransactionFilter", int
         )
@@ -307,7 +326,10 @@ async def eth_new_filter(
         from_block: Block = BlockLabel.LATEST,
         to_block: Block = BlockLabel.LATEST,
     ) -> LogFilter:
-        """Calls the ``eth_newFilter`` RPC method."""
+        """
+        Creates a filter object, based on filter options,
+        to notify when the state changes (logs).
+        """
         if isinstance(source, Iterable):
             source = tuple(source)
         params = FilterParams(
@@ -351,14 +373,15 @@ async def _query_filter(
     async def eth_get_filter_logs(
         self, filter_: BlockFilter | PendingTransactionFilter | LogFilter
     ) -> tuple[BlockHash, ...] | tuple[TxHash, ...] | tuple[LogEntry, ...]:
-        """Calls the ``eth_getFilterLogs`` RPC method."""
+        """Returns an array of all logs matching filter with given id."""
         return await self._query_filter("eth_getFilterLogs", filter_)
 
     async def eth_get_filter_changes(
         self, filter_: BlockFilter | PendingTransactionFilter | LogFilter
     ) -> tuple[BlockHash, ...] | tuple[TxHash, ...] | tuple[LogEntry, ...]:
         """
-        Calls the ``eth_getFilterChanges`` RPC method.
+        Polling method for a filter, which returns an array of logs which occurred since last poll.
+
         Depending on what ``filter_`` was, returns a tuple of corresponding results.
         """
         return await self._query_filter("eth_getFilterChanges", filter_)
@@ -367,49 +390,54 @@ async def eth_uninstall_filter(
         self, filter_: BlockFilter | PendingTransactionFilter | LogFilter
     ) -> bool:
         """
-        Calls the ``eth_uninstallFilter`` RPC method.
+        Uninstalls a filter with given id. Should always be called when watch is no longer needed.
+
         Returns ``true`` if there was an active filter with a given filter ID.
 
         .. note::
 
-            Many providers will automatically uninstall filters after some time.
+            Many providers will automatically uninstall filters after some time
+            if they are not queried.
         """
         return await rpc_call_at_pin(
             self._provider_session, filter_.provider_path, "eth_uninstallFilter", bool, filter_.id
         )
 
     async def web3_client_version(self) -> str:
-        """Calls the ``web3_clientVersion`` RPC method."""
+        """Returns the current client version."""
         return await rpc_call(self._provider_session, "web3_clientVersion", str)
 
     async def web3_sha3(self, data: bytes) -> bytes:
-        """Calls the ``web3_sha3`` RPC method."""
+        """Returns Keccak-256 (*not* the standardized SHA3-256) of the given data."""
         return await rpc_call(self._provider_session, "web3_sha3", bytes, data)
 
     async def net_listening(self) -> bool:
-        """Calls the ``net_listening`` RPC method."""
+        """Returns ``True`` if client is actively listening for network connections."""
         return await rpc_call(self._provider_session, "net_listening", bool)
 
     async def net_peer_count(self) -> int:
-        """Calls the ``net_peerCount`` RPC method."""
+        """Returns number of peers currently connected to the client."""
         return await rpc_call(self._provider_session, "net_peerCount", int)
 
     async def eth_coinbase(self) -> Address:
-        """Calls the ``eth_coinbase`` RPC method."""
+        """Returns the client coinbase address."""
         return await rpc_call(self._provider_session, "eth_coinbase", Address)
 
     async def eth_accounts(self) -> list[Address]:
-        """Calls the ``eth_accounts`` RPC method."""
+        """Returns a list of addresses owned by client."""
         return await rpc_call(self._provider_session, "eth_accounts", list[Address])
 
     async def eth_get_block_transaction_count_by_hash(self, block_hash: BlockHash) -> int:
-        """Calls the ``eth_getBlockTransactionCountByHash`` RPC method."""
+        """
+        Returns the number of transactions in a block from a block
+        matching the given block hash.
+        """
         return await rpc_call(
             self._provider_session, "eth_getBlockTransactionCountByHash", int, block_hash
         )
 
     async def eth_get_block_transaction_count_by_number(self, block: Block) -> int:
-        """Calls the ``eth_getBlockTransactionCountByNumber`` RPC method."""
+        """Returns the number of transactions in a block matching the given block number."""
         return await rpc_call(
             self._provider_session, "eth_getBlockTransactionCountByNumber", int, block
         )
@@ -427,7 +455,7 @@ async def eth_get_uncle_count_by_block_number(self, block: Block) -> int:
     async def eth_get_transaction_by_block_hash_and_index(
         self, block_hash: BlockHash, index: int
     ) -> TxInfo:
-        """Calls the ``eth_getTransactionByBlockHashAndIndex`` RPC method."""
+        """Returns information about a transaction by block hash and transaction index position."""
         return await rpc_call(
             self._provider_session,
             "eth_getTransactionByBlockHashAndIndex",
@@ -439,15 +467,18 @@ async def eth_get_transaction_by_block_hash_and_index(
     async def eth_get_transaction_by_block_number_and_index(
         self, block: Block, index: int
     ) -> TxInfo:
-        """Calls the ``eth_getTransactionByBlockNumberAndIndex`` RPC method."""
+        """
+        Returns information about a transaction by block number
+        and transaction index position.
+        """
         return await rpc_call(
             self._provider_session, "eth_getTransactionByBlockNumberAndIndex", TxInfo, block, index
         )
 
     async def eth_get_uncle_by_block_hash_and_index(
         self, block_hash: BlockHash, index: int
     ) -> None | BlockInfo:
-        """Calls the ``eth_getUncleByBlockHashAndIndex`` RPC method."""
+        """Returns information about a uncle of a block by hash and uncle index position."""
         # Need an explicit cast, mypy doesn't work with union types correctly.
         # See https://github.com/python/mypy/issues/16935
         return cast(
@@ -464,7 +495,7 @@ async def eth_get_uncle_by_block_hash_and_index(
     async def eth_get_uncle_by_block_number_and_index(
         self, block: Block, index: int
     ) -> None | BlockInfo:
-        """Calls the ``eth_getUncleByBlockNumberAndIndex`` RPC method."""
+        """Returns information about a uncle of a block by number and uncle index position."""
         # Need an explicit cast, mypy doesn't work with union types correctly.
         # See https://github.com/python/mypy/issues/16935
         return cast(

pons/_contract_abi.py

@@ -638,14 +638,7 @@ def __str__(self) -> str:
 
 
 class Event:
-    """
-    A contract event.
-
-    .. note::
-
-       If the name of a field given to the constructor matches a Python keyword,
-       ``_`` will be appended to it.
-    """
+    """A contract event."""
 
     name: str
     """The name of this event."""