Remove AttributeDict method formatters and opt for middleware

docs/examples.rst

@@ -881,7 +881,7 @@ The script can be run with: ``python ./eventscanner.py <your JSON-RPC API URL>``
 
             :param event: Symbolic dictionary of the event data
 
-            :return: Internal state structure that is the result of event tranformation.
+            :return: Internal state structure that is the result of event transformation.
             """
 
         @abstractmethod

docs/middleware.rst

@@ -29,9 +29,14 @@ AttributeDict
 
 .. py:method:: web3.middleware.attrdict_middleware
 
-    This middleware converts the output of a function from a dictionary to an ``AttributeDict``
-    which enables dot-syntax access, like ``eth.get_block('latest').number``
-    in addition to ``eth.get_block('latest')['number']``.
+    This middleware recursively converts any dictionary type in the result of a call
+    to an ``AttributeDict``. This enables dot-syntax access, like
+    ``eth.get_block('latest').number`` in addition to
+    ``eth.get_block('latest')['number']``.
+
+    .. note::
+        Accessing a property via attribute breaks type hinting. For this reason, this
+        feature is available as a middleware, which may be removed if desired.
 
 .eth Name Resolution
 ~~~~~~~~~~~~~~~~~~~~~
@@ -42,10 +47,10 @@ AttributeDict
     address that the name points to. For example :meth:`w3.eth.send_transaction <web3.eth.Eth.send_transaction>` will
     accept .eth names in the 'from' and 'to' fields.
 
-.. note::
-    This middleware only converts ENS names if invoked with the mainnet
-    (where the ENS contract is deployed), for all other cases will result in an
-    ``InvalidAddress`` error
+    .. note::
+        This middleware only converts ENS names if invoked with the mainnet
+        (where the ENS contract is deployed), for all other cases will result in an
+        ``InvalidAddress`` error
 
 Pythonic
 ~~~~~~~~~~~~

docs/providers.rst

@@ -369,6 +369,7 @@ Supported Middleware
 - :meth:`Gas Price Strategy <web3.middleware.gas_price_strategy_middleware>`
 - :meth:`Buffered Gas Estimate Middleware <web3.middleware.buffered_gas_estimate_middleware>`
 - :meth:`Stalecheck Middleware <web3.middleware.make_stalecheck_middleware>`
+- :meth:`Attribute Dict Middleware <web3.middleware.attrdict_middleware>`
 - :meth:`Validation Middleware <web3.middleware.validation>`
 - :ref:`Geth POA Middleware <geth-poa>`
 - :meth:`Simple Cache Middleware <web3.middleware.simple_cache_middleware>`

docs/web3.eth.rst

@@ -16,7 +16,7 @@ web3.eth API
 The ``web3.eth`` object exposes the following properties and methods to
 interact with the RPC APIs under the ``eth_`` namespace.
 
-Often, when a property or method returns a mapping of keys to values, it
+By default, when a property or method returns a mapping of keys to values, it
 will return an ``AttributeDict`` which acts like a ``dict`` but you can
 access the keys as attributes and cannot modify its fields. For example,
 you can find the latest block number in these two ways:
@@ -39,6 +39,13 @@ you can find the latest block number in these two ways:
         Traceback # ... etc ...
         TypeError: This data is immutable -- create a copy instead of modifying
 
+This feature is available via the ``attrdict_middleware`` which is a default middleware.
+
+.. note::
+    Accessing an ``AttributeDict`` property via attribute will break type hinting. If
+    typing is crucial for your application, accessing via key / value, as well as
+    removing the ``attrdict_middleware`` altogether, may be desired.
+
 
 Properties
 ----------
@@ -332,7 +339,8 @@ The following methods are available on the ``web3.eth`` namespace.
 
     * Merkle proof verification using py-trie.
 
-    The following example verifies that the values returned in the AttributeDict are included in the state of given trie ``root``.
+    The following example verifies that the values returned in the ``AttributeDict``
+    are included in the state of given trie ``root``.
 
     .. code-block:: python
 

newsfragments/2805.breaking.rst

@@ -0,0 +1 @@
+``dict`` to ``AttributeDict`` conversion is no longer a default result formatter. This conversion is now done via a default middleware that may be removed.

tests/core/method-class/test_method.py

@@ -337,11 +337,11 @@ def test_process_params(
             object(), *args, **kwargs
         )
         assert request_params == expected_request_result
-        first_formatter = (output_formatter[0].first,)
-        all_other_formatters = output_formatter[0].funcs
 
-        # the expected result formatters length is 2
-        assert len(first_formatter + all_other_formatters) == 2
+        first_formatter = (output_formatter[0],)
+
+        # the expected result formatters length is 1
+        assert len(first_formatter) == 1
 
 
 def keywords(module, keyword_one, keyword_two):

tests/core/middleware/test_attrdict_middleware.py

@@ -0,0 +1,156 @@
+import pytest
+
+from web3 import (
+    EthereumTesterProvider,
+    Web3,
+)
+from web3.datastructures import (
+    AttributeDict,
+)
+from web3.middleware import (
+    async_attrdict_middleware,
+    async_construct_result_generator_middleware,
+    attrdict_middleware,
+    construct_result_generator_middleware,
+)
+from web3.providers.eth_tester import (
+    AsyncEthereumTesterProvider,
+)
+from web3.types import (
+    RPCEndpoint,
+)
+
+GENERATED_NESTED_DICT_RESULT = {
+    "result": {
+        "a": 1,
+        "b": {
+            "b1": 1,
+            "b2": {"b2a": 1, "b2b": {"b2b1": 1, "b2b2": {"test": "fin"}}},
+        },
+    }
+}
+
+
+def _assert_dict_and_not_attrdict(value):
+    assert not isinstance(value, AttributeDict)
+    assert isinstance(value, dict)
+
+
+def test_attrdict_middleware_default_for_ethereum_tester_provider():
+    w3 = Web3(EthereumTesterProvider())
+    assert w3.middleware_onion.get("attrdict") == attrdict_middleware
+
+
+def test_attrdict_middleware_is_recursive(w3):
+    w3.middleware_onion.inject(
+        construct_result_generator_middleware(
+            {RPCEndpoint("fake_endpoint"): lambda *_: GENERATED_NESTED_DICT_RESULT}
+        ),
+        "result_gen",
+        layer=0,
+    )
+    response = w3.manager.request_blocking("fake_endpoint", [])
+
+    result = response["result"]
+    assert isinstance(result, AttributeDict)
+    assert response.result == result
+
+    assert isinstance(result["b"], AttributeDict)
+    assert result.b == result["b"]
+    assert isinstance(result.b["b2"], AttributeDict)
+    assert result.b.b2 == result.b["b2"]
+    assert isinstance(result.b.b2["b2b"], AttributeDict)
+    assert result.b.b2.b2b == result.b.b2["b2b"]
+    assert isinstance(result.b.b2.b2b["b2b2"], AttributeDict)
+    assert result.b.b2.b2b.b2b2 == result.b.b2.b2b["b2b2"]
+
+    # cleanup
+    w3.middleware_onion.remove("result_gen")
+
+
+def test_no_attrdict_middleware_does_not_convert_dicts_to_attrdict():
+    w3 = Web3(EthereumTesterProvider())
+
+    w3.middleware_onion.inject(
+        construct_result_generator_middleware(
+            {RPCEndpoint("fake_endpoint"): lambda *_: GENERATED_NESTED_DICT_RESULT}
+        ),
+        "result_gen",
+        layer=0,
+    )
+
+    # remove attrdict middleware
+    w3.middleware_onion.remove("attrdict")
+
+    response = w3.manager.request_blocking("fake_endpoint", [])
+
+    result = response["result"]
+
+    _assert_dict_and_not_attrdict(result)
+    _assert_dict_and_not_attrdict(result["b"])
+    _assert_dict_and_not_attrdict(result["b"]["b2"])
+    _assert_dict_and_not_attrdict(result["b"]["b2"]["b2b"])
+    _assert_dict_and_not_attrdict(result["b"]["b2"]["b2b"]["b2b2"])
+
+
+# --- async --- #
+
+
+@pytest.mark.asyncio
+async def test_async_attrdict_middleware_default_for_async_ethereum_tester_provider():
+    async_w3 = Web3(AsyncEthereumTesterProvider())
+    assert async_w3.middleware_onion.get("attrdict") == async_attrdict_middleware
+
+
+@pytest.mark.asyncio
+async def test_async_attrdict_middleware_is_recursive(async_w3):
+    async_w3.middleware_onion.inject(
+        await async_construct_result_generator_middleware(
+            {RPCEndpoint("fake_endpoint"): lambda *_: GENERATED_NESTED_DICT_RESULT}
+        ),
+        "result_gen",
+        layer=0,
+    )
+    response = await async_w3.manager.coro_request("fake_endpoint", [])
+
+    result = response["result"]
+    assert isinstance(result, AttributeDict)
+    assert response.result == result
+
+    assert isinstance(result["b"], AttributeDict)
+    assert result.b == result["b"]
+    assert isinstance(result.b["b2"], AttributeDict)
+    assert result.b.b2 == result.b["b2"]
+    assert isinstance(result.b.b2["b2b"], AttributeDict)
+    assert result.b.b2.b2b == result.b.b2["b2b"]
+    assert isinstance(result.b.b2.b2b["b2b2"], AttributeDict)
+    assert result.b.b2.b2b.b2b2 == result.b.b2.b2b["b2b2"]
+
+    # cleanup
+    async_w3.middleware_onion.remove("result_gen")
+
+
+@pytest.mark.asyncio
+async def test_no_async_attrdict_middleware_does_not_convert_dicts_to_attrdict():
+    async_w3 = Web3(AsyncEthereumTesterProvider())
+
+    async_w3.middleware_onion.inject(
+        await async_construct_result_generator_middleware(
+            {RPCEndpoint("fake_endpoint"): lambda *_: GENERATED_NESTED_DICT_RESULT}
+        ),
+        "result_gen",
+        layer=0,
+    )
+
+    # remove attrdict middleware
+    async_w3.middleware_onion.remove("attrdict")
+
+    response = await async_w3.manager.coro_request("fake_endpoint", [])
+
+    result = response["result"]
+
+    _assert_dict_and_not_attrdict(result)
+    _assert_dict_and_not_attrdict(result["b"])
+    _assert_dict_and_not_attrdict(result["b"]["b2"])
+    _assert_dict_and_not_attrdict(result["b"]["b2"]["b2b"])
+    _assert_dict_and_not_attrdict(result["b"]["b2"]["b2b"]["b2b2"])

tests/core/middleware/test_filter_middleware.py

@@ -15,8 +15,10 @@
     AsyncEth,
 )
 from web3.middleware import (
+    async_attrdict_middleware,
     async_construct_result_generator_middleware,
     async_local_filter_middleware,
+    attrdict_middleware,
     construct_result_generator_middleware,
     local_filter_middleware,
 )
@@ -105,6 +107,7 @@ def w3_base():
 @pytest.fixture(scope="function")
 def w3(w3_base, result_generator_middleware):
     w3_base.middleware_onion.add(result_generator_middleware)
+    w3_base.middleware_onion.add(attrdict_middleware)
     w3_base.middleware_onion.add(local_filter_middleware)
     return w3_base
 
@@ -284,6 +287,7 @@ def async_w3_base():
 @pytest.fixture(scope="function")
 def async_w3(async_w3_base, async_result_generator_middleware):
     async_w3_base.middleware_onion.add(async_result_generator_middleware)
+    async_w3_base.middleware_onion.add(async_attrdict_middleware)
     async_w3_base.middleware_onion.add(async_local_filter_middleware)
     return async_w3_base
 

tests/core/providers/test_async_http_provider.py

@@ -20,6 +20,7 @@
     Geth,
 )
 from web3.middleware import (
+    async_attrdict_middleware,
     async_buffered_gas_estimate_middleware,
     async_gas_price_strategy_middleware,
     async_validation_middleware,
@@ -63,12 +64,13 @@ def test_web3_with_async_http_provider_has_default_middlewares_and_modules() ->
 
     # the following length check should fail and will need to be added to once more
     # async middlewares are added to the defaults
-    assert len(async_w3.middleware_onion.middlewares) == 3
+    assert len(async_w3.middleware_onion.middlewares) == 4
 
     assert (
         async_w3.middleware_onion.get("gas_price_strategy")
         == async_gas_price_strategy_middleware
     )
+    assert async_w3.middleware_onion.get("attrdict") == async_attrdict_middleware
     assert async_w3.middleware_onion.get("validation") == async_validation_middleware
     assert (
         async_w3.middleware_onion.get("gas_estimate")

web3/_utils/events.py

@@ -208,7 +208,9 @@ def get_event_abi_types_for_decoding(
 
 @curry
 def get_event_data(
-    abi_codec: ABICodec, event_abi: ABIEvent, log_entry: LogReceipt
+    abi_codec: ABICodec,
+    event_abi: ABIEvent,
+    log_entry: LogReceipt,
 ) -> EventData:
     """
     Given an event ABI and a log entry for that event, return the decoded
@@ -269,18 +271,21 @@ def get_event_data(
         )
     )
 
-    event_data = {
-        "args": event_args,
-        "event": event_abi["name"],
-        "logIndex": log_entry["logIndex"],
-        "transactionIndex": log_entry["transactionIndex"],
-        "transactionHash": log_entry["transactionHash"],
-        "address": log_entry["address"],
-        "blockHash": log_entry["blockHash"],
-        "blockNumber": log_entry["blockNumber"],
-    }
+    event_data = EventData(
+        args=event_args,
+        event=event_abi["name"],
+        logIndex=log_entry["logIndex"],
+        transactionIndex=log_entry["transactionIndex"],
+        transactionHash=log_entry["transactionHash"],
+        address=log_entry["address"],
+        blockHash=log_entry["blockHash"],
+        blockNumber=log_entry["blockNumber"],
+    )
+
+    if isinstance(log_entry, AttributeDict):
+        return cast(EventData, AttributeDict.recursive(event_data))
 
-    return cast(EventData, AttributeDict.recursive(event_data))
+    return event_data
 
 
 @to_tuple