Decode tuples per abi

docs/web3.contract.rst

@@ -146,12 +146,29 @@ Each Contract Factory exposes the following properties.
     The runtime part of the contract bytecode string.  May be ``None`` if not
     provided during factory creation.
 
+
+.. py:attribute:: Contract.decode_tuples
+
+    If a Tuple/Struct is returned by a contract function, this flag defines whether
+    to apply the field names from the ABI to the returned data.
+    If False, the returned value will be a normal Python `Tuple`. If True, the returned
+    value will be a Python `NamedTuple` of the class `ABIDecodedNamedTuple`.
+
+    NamedTuples have some restrictions regarding field names.
+    web3.py sets `NamedTuple`'s `rename=True`, so disallowed field names may be 
+    different than expected. See the [Python docs](https://docs.python.org/3/library/collections.html#collections.namedtuple)
+    for more information.
+
+    Defaults to ``False`` if not provided during factory creation.
+
+
 .. py:attribute:: Contract.functions
 
     This provides access to contract functions as attributes.  For example:
     ``myContract.functions.MyMethod()``.  The exposed contract functions are classes of the
     type :py:class:`ContractFunction`.
 
+
 .. py:attribute:: Contract.events
 
     This provides access to contract events as attributes.  For example:

docs/web3.eth.rst

@@ -1454,6 +1454,7 @@ Contracts
     - ``bytecode_runtime``
     - ``clone_bin``
     - ``dev_doc``
+    - ``decode_tuples``
     - ``interface``
     - ``metadata``
     - ``opcodes``

newsfragments/2799.feature.rst

@@ -0,0 +1 @@
+add decode_tuples option to contract instantiation

tests/core/contracts/conftest.py

@@ -50,6 +50,10 @@
 from web3._utils.contract_sources.contract_data.string_contract import (
     STRING_CONTRACT_DATA,
 )
+from web3._utils.contract_sources.contract_data.tuple_contracts import (
+    NESTED_TUPLE_CONTRACT_DATA,
+    TUPLE_CONTRACT_DATA,
+)
 
 
 @pytest.fixture(scope="session")
@@ -340,6 +344,44 @@ def revert_contract(w3, address_conversion_func):
     return deploy(w3, revert_contract_factory, address_conversion_func)
 
 
+@pytest.fixture
+def tuple_contract(w3, address_conversion_func):
+    tuple_contract_factory = w3.eth.contract(**TUPLE_CONTRACT_DATA)
+    return deploy(w3, tuple_contract_factory, address_conversion_func)
+
+
+@pytest.fixture
+def nested_tuple_contract(w3, address_conversion_func):
+    nested_tuple_contract_factory = w3.eth.contract(**NESTED_TUPLE_CONTRACT_DATA)
+    return deploy(w3, nested_tuple_contract_factory, address_conversion_func)
+
+
+TUPLE_CONTRACT_DATA_DECODE_TUPLES = {
+    **TUPLE_CONTRACT_DATA,
+    "decode_tuples": True,
+}
+
+
+NESTED_TUPLE_CONTRACT_DATA_DECODE_TUPLES = {
+    **NESTED_TUPLE_CONTRACT_DATA,
+    "decode_tuples": True,
+}
+
+
+@pytest.fixture
+def tuple_contract_with_decode_tuples(w3, address_conversion_func):
+    tuple_contract_factory = w3.eth.contract(**TUPLE_CONTRACT_DATA_DECODE_TUPLES)
+    return deploy(w3, tuple_contract_factory, address_conversion_func)
+
+
+@pytest.fixture
+def nested_tuple_contract_with_decode_tuples(w3, address_conversion_func):
+    nested_tuple_contract_factory = w3.eth.contract(
+        **NESTED_TUPLE_CONTRACT_DATA_DECODE_TUPLES
+    )
+    return deploy(w3, nested_tuple_contract_factory, address_conversion_func)
+
+
 @pytest.fixture
 def some_address(address_conversion_func):
     return address_conversion_func("0x5B2063246F2191f18F2675ceDB8b28102e957458")
@@ -563,6 +605,46 @@ async def async_revert_contract(async_w3, address_conversion_func):
     )
 
 
+@pytest_asyncio.fixture
+async def async_tuple_contract(async_w3, address_conversion_func):
+    async_tuple_contract_factory = async_w3.eth.contract(**TUPLE_CONTRACT_DATA)
+    return await async_deploy(
+        async_w3, async_tuple_contract_factory, address_conversion_func
+    )
+
+
+@pytest_asyncio.fixture
+async def async_nested_tuple_contract(async_w3, address_conversion_func):
+    async_nested_tuple_contract_factory = async_w3.eth.contract(
+        **NESTED_TUPLE_CONTRACT_DATA
+    )
+    return await async_deploy(
+        async_w3, async_nested_tuple_contract_factory, address_conversion_func
+    )
+
+
+@pytest_asyncio.fixture
+async def async_tuple_contract_with_decode_tuples(async_w3, address_conversion_func):
+    async_tuple_contract_factory = async_w3.eth.contract(
+        **TUPLE_CONTRACT_DATA_DECODE_TUPLES
+    )
+    return await async_deploy(
+        async_w3, async_tuple_contract_factory, address_conversion_func
+    )
+
+
+@pytest_asyncio.fixture
+async def async_nested_tuple_contract_with_decode_tuples(
+    async_w3, address_conversion_func
+):
+    async_nested_tuple_contract_factory = async_w3.eth.contract(
+        **NESTED_TUPLE_CONTRACT_DATA_DECODE_TUPLES
+    )
+    return await async_deploy(
+        async_w3, async_nested_tuple_contract_factory, address_conversion_func
+    )
+
+
 async def async_invoke_contract(
     api_call_desig="call",
     contract=None,