Add newsfragment & update docs for #198 / #211

Author: fselmo

docs/decoding.rst

@@ -29,3 +29,32 @@ The :py:meth:`eth_abi.decoding.BaseDecoder.decode` function provides an API for
 decoding binary values for ABI types into python values. It accepts a sequence of
 ABI type strings as the first argument and the binary data to be decoded, as a python
 ``bytes`` or ``bytearray`` value, as the second argument.
+
+Strict Mode
+-----------
+
+By default, the decoder will raise an exception if the binary data to be decoded
+is not padded to the next 32-byte boundary. This behavior can be disabled for the
+``ByteStringDecoder`` (the default decoder for ``bytes`` and ``string`` types) by
+passing ``strict=False`` to the :py:meth:`eth_abi.abi.decode` method. Turning off
+strict mode will also ignore any trailing bytes beyond the data size specified. This
+means that if there is any padding, the validation for only empty bytes in the padding
+area is also ignored.
+
+.. doctest::
+
+    >>> from eth_abi import abi
+
+    >>> # decode a bytes value without strict mode
+    >>> hex_val = (
+    ...     # offset to data is 32 bytes:
+    ...     "0000000000000000000000000000000000000000000000000000000000000020"
+    ...     # length of data is 1 byte:
+    ...     "0000000000000000000000000000000000000000000000000000000000000001"
+    ...     # b"\x01" with less than 32 bytes of padding
+    ...     # and not strictly padded with only zero bytes:
+    ...     "0100000000000001020300"
+    ... )
+    >>> (decoded,) = abi.decode(['bytes'], bytes.fromhex(hex_val), strict=False)
+    >>> decoded
+    b'\x01'

eth_abi/codec.py

@@ -139,11 +139,10 @@ def decode(
         :param types: A list or tuple of string representations of the ABI types that
             will be used for decoding e.g. ``('uint256', 'bytes[]', '(int,int)')``
         :param data: The binary value to be decoded.
-        :param strict: If ``False``, then the decoder will ignore properties such as
-            the length of the data being a multiple of 32 bytes. ``False`` is how the
-            Solidity ABI decoder currently works. However, ``True`` is the default for
-            the eth-abi library.
-
+        :param strict: If ``False``, dynamic-type decoders will ignore validations such
+            as making sure the data is padded to a multiple of 32 bytes or checking that
+            padding bytes are zero / empty. ``False`` is how the Solidity ABI decoder
+            currently works. However, ``True`` is the default for the eth-abi library.
 
         :returns: A tuple of equivalent python values for the ABI values
             represented in ``data``.

newsfragments/198.feature.rst

@@ -0,0 +1 @@
+Allow turning off abi decoder "strict mode" when calling ``abi.decode()``.