Move getBalance to snake_case

docs/examples.rst

@@ -73,13 +73,13 @@ If you want to know the latest block number you can use the
 Checking the balance of an account
 ----------------------------------
 
-To find the amount of ether owned by an account, use the :meth:`~web3.eth.Eth.getBalance` method.
+To find the amount of ether owned by an account, use the :meth:`~web3.eth.Eth.get_balance` method.
 At the time of writing, the account with the `most ether <https://etherscan.io/accounts/1>`_
 has a public address of 0x742d35Cc6634C0532925a3b844Bc454e4438f44e.
 
 .. code-block:: python
 
-   >>> web3.eth.getBalance('0x742d35Cc6634C0532925a3b844Bc454e4438f44e')
+   >>> web3.eth.get_balance('0x742d35Cc6634C0532925a3b844Bc454e4438f44e')
    3841357360894980500000001
 
 Note that this number is not denominated in ether, but instead in the smallest unit of value in

docs/overview.rst

@@ -13,7 +13,7 @@ greater detail.
 Configuration
 ~~~~~~~~~~~~~
 
-After installing Web3.py (via ``pip install web3``), you'll need to specify the 
+After installing Web3.py (via ``pip install web3``), you'll need to specify the
 provider and any middleware you want to use beyond the defaults.
 
 
@@ -43,7 +43,7 @@ following built-in providers:
    >>> w3.isConnected()
    True
 
-For more information, (e.g., connecting to remote nodes, provider auto-detection, 
+For more information, (e.g., connecting to remote nodes, provider auto-detection,
 using a test provider) see the :ref:`Providers <providers>` documentation.
 
 
@@ -131,7 +131,7 @@ demonstrate how to use several of these methods.
 Fetching Data
 -------------
 
-Viewing account balances (:meth:`getBalance <web3.eth.Eth.getBalance>`), transactions
+Viewing account balances (:meth:`get_balance <web3.eth.Eth.get_balance>`), transactions
 (:meth:`getTransaction <web3.eth.Eth.getTransaction>`), and block data
 (:meth:`getBlock <web3.eth.Eth.getBlock>`) are some of the most common starting
 points in Web3.py.
@@ -140,7 +140,7 @@ points in Web3.py.
 API
 ^^^
 
-- :meth:`web3.eth.getBalance() <web3.eth.Eth.getBalance>`
+- :meth:`web3.eth.get_balance() <web3.eth.Eth.get_balance>`
 - :meth:`web3.eth.getBlock() <web3.eth.Eth.getBlock>`
 - :meth:`web3.eth.getBlockTransactionCount() <web3.eth.Eth.getBlockTransactionCount>`
 - :meth:`web3.eth.getCode() <web3.eth.Eth.getCode>`

docs/web3.eth.rst

@@ -171,7 +171,7 @@ Methods
 The following methods are available on the ``web3.eth`` namespace.
 
 
-.. py:method:: Eth.getBalance(account, block_identifier=eth.defaultBlock)
+.. py:method:: Eth.get_balance(account, block_identifier=eth.defaultBlock)
 
     * Delegates to ``eth_getBalance`` RPC Method
 
@@ -182,10 +182,16 @@ The following methods are available on the ``web3.eth`` namespace.
 
     .. code-block:: python
 
-        >>> web3.eth.getBalance('0xd3CdA913deB6f67967B99D67aCDFa1712C293601')
+        >>> web3.eth.get_balance('0xd3CdA913deB6f67967B99D67aCDFa1712C293601')
         77320681768999138915
 
 
+.. py:method:: Eth.getBalance(account, block_identifier=eth.defaultBlock)
+
+    .. warning:: Deprecated: This method is deprecated in favor of
+      :meth:`~web3.eth.get_balance()`
+
+
 .. py:method:: Eth.getStorageAt(account, position, block_identifier=eth.defaultBlock)
 
     * Delegates to ``eth_getStorageAt`` RPC Method

newsfragments/1806.feature.rst

@@ -0,0 +1 @@
+Add new get_balance method on Eth class. Deprecated getBalance.

tests/core/middleware/test_name_to_address_middleware.py

@@ -42,7 +42,7 @@ def test_pass_name_resolver(w3):
     })
     w3.middleware_onion.inject(return_chain_on_mainnet, layer=0)
     w3.middleware_onion.inject(return_balance, layer=0)
-    assert w3.eth.getBalance(NAME) == BALANCE
+    assert w3.eth.get_balance(NAME) == BALANCE
 
 
 def test_fail_name_resolver(w3):
@@ -51,4 +51,4 @@ def test_fail_name_resolver(w3):
     })
     w3.middleware_onion.inject(return_chain_on_mainnet, layer=0)
     with pytest.raises(InvalidAddress, match=r'.*ethereum\.eth.*'):
-        w3.eth.getBalance("ethereum.eth")
+        w3.eth.get_balance("ethereum.eth")

tests/core/middleware/test_transaction_signing.py

@@ -212,7 +212,7 @@ def fund_account(w3):
             'from': w3.eth.accounts[0],
             'gas': 21000,
             'value': tx_value})
-        assert w3.eth.getBalance(address) == tx_value
+        assert w3.eth.get_balance(address) == tx_value
 
 
 @pytest.mark.parametrize(
@@ -277,10 +277,10 @@ def test_signed_transaction(
 
     if isinstance(expected, type) and issubclass(expected, Exception):
         with pytest.raises(expected):
-            start_balance = w3.eth.getBalance(_transaction.get('from', w3.eth.accounts[0]))
+            start_balance = w3.eth.get_balance(_transaction.get('from', w3.eth.accounts[0]))
             w3.eth.sendTransaction(_transaction)
     else:
-        start_balance = w3.eth.getBalance(_transaction.get('from', w3.eth.accounts[0]))
+        start_balance = w3.eth.get_balance(_transaction.get('from', w3.eth.accounts[0]))
         w3.eth.sendTransaction(_transaction)
         assert w3.eth.getBalance(_transaction.get('from')) <= start_balance + expected
 

tests/core/tools/pytest_ethereum/test_linker.py

@@ -75,8 +75,8 @@ def callback_fn(package):
         run_python(callback_fn),
     )
     escrow_deployer.register_strategy("Escrow", escrow_strategy)
-    assert w3.eth.getBalance(recipient) == w3.toWei("1000000", "ether")
+    assert w3.eth.get_balance(recipient) == w3.toWei("1000000", "ether")
     linked_escrow_package = escrow_deployer.deploy("Escrow")
     escrow_instance = linked_escrow_package.deployments.get_instance("Escrow")
     assert escrow_instance.functions.sender().call() == sender
-    assert w3.eth.getBalance(recipient) == w3.toWei("1000001", "ether")
+    assert w3.eth.get_balance(recipient) == w3.toWei("1000001", "ether")

web3/_utils/module_testing/eth_module.py

@@ -121,21 +121,33 @@ def test_eth_blockNumber(self, web3: "Web3") -> None:
         assert is_integer(block_number)
         assert block_number >= 0
 
-    def test_eth_getBalance(self, web3: "Web3") -> None:
+    def test_eth_get_balance(self, web3: "Web3") -> None:
         coinbase = web3.eth.coinbase
 
         with pytest.raises(InvalidAddress):
-            web3.eth.getBalance(ChecksumAddress(HexAddress(HexStr(coinbase.lower()))))
+            web3.eth.get_balance(ChecksumAddress(HexAddress(HexStr(coinbase.lower()))))
 
-        balance = web3.eth.getBalance(coinbase)
+        balance = web3.eth.get_balance(coinbase)
 
         assert is_integer(balance)
         assert balance >= 0
 
-    def test_eth_getBalance_with_block_identifier(self, web3: "Web3") -> None:
+    def test_eth_getBalance_deprecated(self, web3: "Web3") -> None:
+        coinbase = web3.eth.coinbase
+
+        with pytest.warns(DeprecationWarning):
+            with pytest.raises(InvalidAddress):
+                web3.eth.getBalance(ChecksumAddress(HexAddress(HexStr(coinbase.lower()))))
+
+            balance = web3.eth.getBalance(coinbase)
+
+        assert is_integer(balance)
+        assert balance >= 0
+
+    def test_eth_get_balance_with_block_identifier(self, web3: "Web3") -> None:
         miner_address = web3.eth.getBlock(1)['miner']
-        genesis_balance = web3.eth.getBalance(miner_address, 0)
-        later_balance = web3.eth.getBalance(miner_address, 1)
+        genesis_balance = web3.eth.get_balance(miner_address, 0)
+        later_balance = web3.eth.get_balance(miner_address, 1)
 
         assert is_integer(genesis_balance)
         assert is_integer(later_balance)
@@ -145,17 +157,17 @@ def test_eth_getBalance_with_block_identifier(self, web3: "Web3") -> None:
         ('test-address.eth', True),
         ('not-an-address.eth', False)
     ])
-    def test_eth_getBalance_with_ens_name(
+    def test_eth_get_balance_with_ens_name(
         self, web3: "Web3", address: ChecksumAddress, expect_success: bool
     ) -> None:
         with ens_addresses(web3, {'test-address.eth': web3.eth.accounts[0]}):
             if expect_success:
-                balance = web3.eth.getBalance(address)
+                balance = web3.eth.get_balance(address)
                 assert is_integer(balance)
                 assert balance >= 0
             else:
                 with pytest.raises(NameNotFound):
-                    web3.eth.getBalance(address)
+                    web3.eth.get_balance(address)
 
     def test_eth_getStorageAt(
         self, web3: "Web3", emitter_contract_address: ChecksumAddress

web3/_utils/module_testing/personal_module.py

@@ -143,7 +143,7 @@ def test_personal_send_transaction(
         unlockable_account_dual_type: ChecksumAddress,
         unlockable_account_pw: str,
     ) -> None:
-        assert web3.eth.getBalance(unlockable_account_dual_type) > web3.toWei(1, 'ether')
+        assert web3.eth.get_balance(unlockable_account_dual_type) > web3.toWei(1, 'ether')
         txn_params: TxParams = {
             'from': unlockable_account_dual_type,
             'to': unlockable_account_dual_type,
@@ -168,7 +168,7 @@ def test_personal_sendTransaction_deprecated(
         unlockable_account_pw: str,
     ) -> None:
         with pytest.warns(DeprecationWarning):
-            assert web3.eth.getBalance(unlockable_account_dual_type) > web3.toWei(1, 'ether')
+            assert web3.eth.get_balance(unlockable_account_dual_type) > web3.toWei(1, 'ether')
             txn_params: TxParams = {
                 'from': unlockable_account_dual_type,
                 'to': unlockable_account_dual_type,
@@ -459,7 +459,7 @@ def test_personal_send_transaction(
         unlockable_account_dual_type: ChecksumAddress,
         unlockable_account_pw: str,
     ) -> None:
-        assert web3.eth.getBalance(unlockable_account_dual_type) > web3.toWei(1, 'ether')
+        assert web3.eth.get_balance(unlockable_account_dual_type) > web3.toWei(1, 'ether')
         txn_params: TxParams = {
             'from': unlockable_account_dual_type,
             'to': unlockable_account_dual_type,
@@ -484,7 +484,7 @@ def test_personal_sendTransaction_deprecated(
         unlockable_account_pw: str,
     ) -> None:
         with pytest.warns(DeprecationWarning):
-            assert web3.eth.getBalance(unlockable_account_dual_type) > web3.toWei(1, 'ether')
+            assert web3.eth.get_balance(unlockable_account_dual_type) > web3.toWei(1, 'ether')
             txn_params: TxParams = {
                 'from': unlockable_account_dual_type,
                 'to': unlockable_account_dual_type,

web3/eth.py

@@ -74,6 +74,7 @@
     Iban,
 )
 from web3.method import (
+    DeprecatedMethod,
     Method,
     default_root_munger,
 )
@@ -205,7 +206,7 @@ def block_id_munger(
             block_identifier = self.defaultBlock
         return (account, block_identifier)
 
-    getBalance: Method[Callable[..., Wei]] = Method(
+    get_balance: Method[Callable[..., Wei]] = Method(
         RPC.eth_getBalance,
         mungers=[block_id_munger],
     )
@@ -563,3 +564,6 @@ def generateGasPrice(self, transaction_params: Optional[TxParams] = None) -> Opt
 
     def setGasPriceStrategy(self, gas_price_strategy: GasPriceStrategy) -> None:
         self.gasPriceStrategy = gas_price_strategy
+
+    # Deprecated Methods
+    getBalance = DeprecatedMethod(get_balance, 'getBalance', 'get_balance')

web3/method.py

@@ -87,12 +87,12 @@ class Method(Generic[TFunc]):
 
             A note about mungers: The first (root) munger should reflect the desired
         api function arguments. In other words, if the api function wants to
-        behave as: `getBalance(account, block_identifier=None)`, the root munger
+        behave as: `get_balance(account, block_identifier=None)`, the root munger
         should accept these same arguments, with the addition of the module as
         the first argument e.g.:
 
         ```
-        def getBalance_root_munger(module, account, block_identifier=None):
+        def get_balance_root_munger(module, account, block_identifier=None):
             if block_identifier is None:
                 block_identifier = DEFAULT_BLOCK
             return module, [account, block_identifier]