Add a bit more documentation and tests for attrdict middlewares

Author: fselmo

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,11 @@ 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.
+Of note, accessing a 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 +337,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
 

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"])