Add documentation on ENS strict bytes check flag

Author: fselmo

docs/abi_types.rst

@@ -28,18 +28,28 @@ All addresses must be supplied in one of three ways:
 Disabling Strict Bytes Type Checking
 ------------------------------------
 
-There is a boolean flag on the web3 instance that will disable strict bytes type checking.
-This allows bytes values of Python strings and allows byte strings less
-than the specified byte size, appropriately padding values that need padding. To
-disable stricter checks, set the ``w3.strict_bytes_type_checking`` flag to ``False``.
-This will no longer cause the web3 instance to raise an error if a Python string is
-passed in without a "0x" prefix. It will also render valid byte strings or hex strings
+There is a boolean flag on the ``Web3`` class and the ``ENS`` class that will disable
+strict bytes type checking. This allows bytes values of Python strings and allows byte
+strings less than the specified byte size, appropriately padding values that need
+padding. To disable stricter checks, set the ``w3.strict_bytes_type_checking``
+(or ``ns.strict_bytes_type_checking``) flag to ``False``. This will no longer cause
+the ``Web3`` / ``ENS`` instance to raise an error if a Python string is passed in
+without a "0x" prefix. It will also render valid byte strings or hex strings
 that are below the exact number of bytes specified by the ABI type by padding the value
 appropriately, according to the ABI type. See the :ref:`disable-strict-byte-check`
-section for an example on using the flag and more details. For more details on the ABI
+section for an example on using the flag and more details.
+
+.. note::
+    If an ``ENS`` class is instantiated from a ``Web3`` instance, i.e.
+    ``ns = ENS.from_web3(w3)``, it will inherit the value of the
+    ``w3.strict_bytes_type_checking`` flag from the ``Web3`` instance at the time of
+    instantiation.
+
+For more details on the ABI
 specification, refer to the
 `Solidity ABI Spec <https://docs.soliditylang.org/en/latest/abi-spec.html>`_.
 
+
 Types by Example
 ----------------
 

docs/ens_overview.rst

@@ -62,6 +62,77 @@ The first time it's used, Web3.py will create the  ``ens`` instance using
     w3.ens.address('ethereum.eth')
 
 
+.. py:attribute:: ens.strict_bytes_type_checking
+
+    The ``ENS`` instance has a ``strict_bytes_type_checking`` flag that toggles the flag
+    with the same name on the ``Web3`` instance attached to the ``ENS`` instance.
+    You may disable the stricter bytes type checking that is loaded by default using
+    this flag. For more examples, see :ref:`disable-strict-byte-check`
+
+    If instantiating a standalone ENS instance using ``ENS.from_web3()``, the ENS
+    instance will inherit the value of the flag on the Web3 instance at time of
+    instantiation.
+
+    .. doctest::
+
+        >>> from web3 import Web3, EthereumTesterProvider
+        >>> from ens import ENS
+        >>> w3 = Web3(EthereumTesterProvider())
+
+        >>> assert w3.strict_bytes_type_checking  # assert strict by default
+        >>> w3.is_encodable('bytes2', b'1')
+        False
+
+        >>> w3.strict_bytes_type_checking = False
+        >>> w3.is_encodable('bytes2', b'1')  # zero-padded, so encoded to: b'1\x00'
+        True
+
+        >>> ns = ENS.from_web3(w3)
+        >>> # assert inherited from w3 at time of instantiation via ENS.from_web3()
+        >>> assert ns.strict_bytes_type_checking is False
+        >>> ns.w3.is_encodable('bytes2', b'1')
+        True
+
+        >>> # assert these are now separate instances
+        >>> ns.strict_bytes_type_checking = True
+        >>> ns.w3.is_encodable('bytes2', b'1')
+        False
+
+        >>> # assert w3 flag value remains
+        >>> assert w3.strict_bytes_type_checking is False
+        >>> w3.is_encodable('bytes2', b'1')
+        True
+
+    However, if accessing the ``ENS`` class via the ``Web3`` instance as a module
+    (``w3.ens``), since all modules use the same ``Web3`` object reference
+    under the the hood (the parent ``w3`` object), changing the
+    ``strict_bytes_type_checking`` flag value on ``w3`` also changes the flag state
+    for ``w3.ens.w3`` and all modules.
+
+    .. doctest::
+
+        >>> from web3 import Web3, EthereumTesterProvider
+        >>> w3 = Web3(EthereumTesterProvider())
+
+        >>> assert w3.strict_bytes_type_checking  # assert strict by default
+        >>> w3.is_encodable('bytes2', b'1')
+        False
+
+        >>> w3.strict_bytes_type_checking = False
+        >>> w3.is_encodable('bytes2', b'1')  # zero-padded, so encoded to: b'1\x00'
+        True
+
+        >>> assert w3 == w3.ens.w3  # assert same object
+        >>> assert not w3.ens.w3.strict_bytes_type_checking
+        >>> w3.ens.w3.is_encodable('bytes2', b'1')
+        True
+
+        >>> # sanity check on eth module as well
+        >>> assert not w3.eth.w3.strict_bytes_type_checking
+        >>> w3.eth.w3.is_encodable('bytes2', b'1')
+        True
+
+
 Usage
 -----
 

newsfragments/2788.breaking.rst

@@ -1 +1 @@
-Strict bytes type checking is now default for ``web3.py``. This change also adds a boolean flag for turning this feature on and off.
+Strict bytes type checking is now default for ``web3.py``. This change also adds a boolean flag on the ``Web3`` class for turning this feature on and off, as well as a flag on the ``ENS`` class for control over a standalone ``ENS`` instance.