Deprecate eth.get_uncle* methods (#3685)

* Cherry-pick efe41ef

* Deprecate get_uncle* methods

* Update docs

* Deprecate async get_uncle* methods

Author: tibor-reiss

docs/web3.eth.rst

@@ -398,6 +398,8 @@ The following methods are available on the ``web3.eth`` namespace.
 
 .. py:method:: Eth.get_uncle_by_block(block_identifier, uncle_index)
 
+    .. warning:: Deprecated. Will be removed in v8.
+
     * Delegates to ``eth_getUncleByBlockHashAndIndex`` or
       ``eth_getUncleByBlockNumberAndIndex`` RPC methods
 
@@ -444,6 +446,8 @@ The following methods are available on the ``web3.eth`` namespace.
 
 .. py:method:: Eth.get_uncle_count(block_identifier)
 
+    .. warning:: Deprecated. Will be removed in v8.
+
     * Delegates to ``eth_getUncleCountByBlockHash`` or
       ``eth_getUncleCountByBlockNumber`` RPC methods
 

newsfragments/3683.deprecation.rst

@@ -0,0 +1 @@
+Deprecate eth.get_uncle* methods. Will be removed in v8.

tests/core/utilities/test_abi.py

@@ -829,7 +829,7 @@ def test_get_event_abi(event_name: str, input_args: Sequence[ABIComponent]) -> N
 
     with pytest.warns(
         DeprecationWarning,
-        match="get_event_abi is deprecated in favor of get_abi_element",
+        match="get_event_abi is deprecated: use get_abi_element instead",
     ):
         assert (
             get_event_abi(contract_abi, event_name, input_names) == expected_event_abi

web3/_utils/decorators.py

@@ -43,7 +43,7 @@ def deprecated_for(replace_message: str) -> Callable[..., Any]:
     """
     Decorate a deprecated function, with info about what to use instead, like:
 
-    @deprecated_for("to_bytes()")
+    @deprecated_for("use to_bytes() instead")
     def toAscii(arg):
         ...
     """
@@ -52,7 +52,7 @@ def decorator(to_wrap: TFunc) -> TFunc:
         @functools.wraps(to_wrap)
         def wrapper(*args: Any, **kwargs: Any) -> Callable[..., Any]:
             warnings.warn(
-                f"{to_wrap.__name__} is deprecated in favor of {replace_message}",
+                f"{to_wrap.__name__} is deprecated: {replace_message}",
                 category=DeprecationWarning,
                 stacklevel=2,
             )

web3/_utils/module_testing/eth_module.py

@@ -2221,19 +2221,31 @@ async def test_eth_getBlockTransactionCountByHash_block_with_txn(
     async def test_eth_getUncleCountByBlockHash(
         self, async_w3: "AsyncWeb3", async_empty_block: BlockData
     ) -> None:
-        uncle_count = await async_w3.eth.get_uncle_count(async_empty_block["hash"])
+        with pytest.warns(
+            DeprecationWarning,
+            match=r"get_uncle_count is deprecated: all get_uncle\* "
+            r"methods will be removed in v8",
+        ):
+            uncle_count = await async_w3.eth.get_uncle_count(async_empty_block["hash"])
 
-        assert is_integer(uncle_count)
-        assert uncle_count == 0
+            assert is_integer(uncle_count)
+            assert uncle_count == 0
 
     @pytest.mark.asyncio
     async def test_eth_getUncleCountByBlockNumber(
         self, async_w3: "AsyncWeb3", async_empty_block: BlockData
     ) -> None:
-        uncle_count = await async_w3.eth.get_uncle_count(async_empty_block["number"])
+        with pytest.warns(
+            DeprecationWarning,
+            match=r"get_uncle_count is deprecated: all get_uncle\* "
+            r"methods will be removed in v8",
+        ):
+            uncle_count = await async_w3.eth.get_uncle_count(
+                async_empty_block["number"]
+            )
 
-        assert is_integer(uncle_count)
-        assert uncle_count == 0
+            assert is_integer(uncle_count)
+            assert uncle_count == 0
 
     @pytest.mark.asyncio
     async def test_eth_getBlockTransactionCountByNumber_block_with_txn(
@@ -2843,18 +2855,24 @@ def test_eth_getBlockTransactionCountByNumber_block_with_txn(
     def test_eth_getUncleCountByBlockHash(
         self, w3: "Web3", empty_block: BlockData
     ) -> None:
-        uncle_count = w3.eth.get_uncle_count(empty_block["hash"])
+        with pytest.warns(
+            DeprecationWarning, match=r"All get_uncle\* methods have been deprecated"
+        ):
+            uncle_count = w3.eth.get_uncle_count(empty_block["hash"])
 
-        assert is_integer(uncle_count)
-        assert uncle_count == 0
+            assert is_integer(uncle_count)
+            assert uncle_count == 0
 
     def test_eth_getUncleCountByBlockNumber(
         self, w3: "Web3", empty_block: BlockData
     ) -> None:
-        uncle_count = w3.eth.get_uncle_count(empty_block["number"])
+        with pytest.warns(
+            DeprecationWarning, match=r"All get_uncle\* methods have been deprecated"
+        ):
+            uncle_count = w3.eth.get_uncle_count(empty_block["number"])
 
-        assert is_integer(uncle_count)
-        assert uncle_count == 0
+            assert is_integer(uncle_count)
+            assert uncle_count == 0
 
     def test_eth_get_code(
         self, w3: "Web3", math_contract_address: ChecksumAddress

web3/eth/async_eth.py

@@ -39,6 +39,9 @@
 from web3._utils.compat import (
     Unpack,
 )
+from web3._utils.decorators import (
+    deprecated_for,
+)
 from web3._utils.fee_utils import (
     async_fee_history_priority_fee,
 )
@@ -669,6 +672,7 @@ async def sign_typed_data(
         mungers=[default_root_munger],
     )
 
+    @deprecated_for("all get_uncle* methods will be removed in v8")
     async def get_uncle_count(self, block_identifier: BlockIdentifier) -> int:
         return await self._get_uncle_count(block_identifier)
 

web3/eth/eth.py

@@ -69,6 +69,7 @@
     Web3ValueError,
 )
 from web3.method import (
+    DeprecatedMethod,
     Method,
     default_root_munger,
 )
@@ -566,26 +567,38 @@ def get_proof_munger(
     # eth_getUncleCountByBlockHash
     # eth_getUncleCountByBlockNumber
 
-    get_uncle_count: Method[Callable[[BlockIdentifier], int]] = Method(
+    _get_uncle_count: Method[Callable[[BlockIdentifier], int]] = Method(
         method_choice_depends_on_args=select_method_for_block_identifier(
             if_predefined=RPC.eth_getUncleCountByBlockNumber,
             if_hash=RPC.eth_getUncleCountByBlockHash,
             if_number=RPC.eth_getUncleCountByBlockNumber,
         ),
         mungers=[default_root_munger],
     )
+    get_uncle_count = DeprecatedMethod(
+        _get_uncle_count,
+        old_name="_get_uncle_count",
+        new_name="get_uncle_count",
+        msg="All get_uncle* methods have been deprecated",
+    )
 
     # eth_getUncleByBlockHashAndIndex
     # eth_getUncleByBlockNumberAndIndex
 
-    get_uncle_by_block: Method[Callable[[BlockIdentifier, int], Uncle]] = Method(
+    _get_uncle_by_block: Method[Callable[[BlockIdentifier, int], Uncle]] = Method(
         method_choice_depends_on_args=select_method_for_block_identifier(
             if_predefined=RPC.eth_getUncleByBlockNumberAndIndex,
             if_hash=RPC.eth_getUncleByBlockHashAndIndex,
             if_number=RPC.eth_getUncleByBlockNumberAndIndex,
         ),
         mungers=[default_root_munger],
     )
+    get_uncle_by_block = DeprecatedMethod(
+        _get_uncle_by_block,
+        old_name="_get_uncle_by_block",
+        new_name="get_uncle_by_block",
+        msg="All get_uncle* methods have been deprecated",
+    )
 
     def replace_transaction(
         self, transaction_hash: _Hash32, new_transaction: TxParams

web3/method.py

@@ -241,17 +241,25 @@ def process_params(
 
 class DeprecatedMethod:
     def __init__(
-        self, method: Method[Callable[..., Any]], old_name: str, new_name: str
+        self,
+        method: Method[Callable[..., Any]],
+        old_name: Optional[str] = None,
+        new_name: Optional[str] = None,
+        msg: Optional[str] = None,
     ) -> None:
         self.method = method
         self.old_name = old_name
         self.new_name = new_name
+        self.msg = msg
 
     def __get__(
         self, obj: Optional["Module"] = None, obj_type: Optional[Type["Module"]] = None
     ) -> Any:
+        message = f"{self.old_name} is deprecated in favor of {self.new_name}"
+        if self.msg is not None:
+            message = self.msg
         warnings.warn(
-            f"{self.old_name} is deprecated in favor of {self.new_name}",
+            message,
             category=DeprecationWarning,
             stacklevel=2,
         )

web3/utils/abi.py

@@ -682,7 +682,7 @@ def check_if_arguments_can_be_encoded(
     )
 
 
-@deprecated_for("get_abi_element")
+@deprecated_for("use get_abi_element instead")
 def get_event_abi(
     abi: ABI,
     event_name: str,