Merge pull request #29 from MatrixEditor/dec/fix-py3.14-digest

[FIX] Python 3.14 Digest alternative

Author: MatrixEditor

README.md

@@ -14,7 +14,9 @@
 
 > [!NOTE]
 > Python 3.14 breaks `with` statements in class definitions since `__annotations__` are added at the end
-> of a class definition. Therefore, `Digest` and conditional statements **ARE NOT SUPPORTED** in Python 3.14+.
+> of a class definition. Therefore, `Digest` and conditional statements **ARE NOT SUPPORTED** in using the `with` syntax Python 3.14+.
+> As of version `2.4.5` the `Digest` class has a counterpart (`DigestField`), which can be used to manually specify a digest without
+> the need of a `ẁith` statement.
 
 
 

docs/sphinx/source/library/fields/crypto.rst

@@ -13,6 +13,10 @@ Hashes
 
 .. autoclass:: caterpillar.py.Digest
 
+.. autoclass:: caterpillar.py.DigestField
+
+.. autoclass:: caterpillar.py.DigestFieldAction
+
 
 Ciphers
 -------

docs/sphinx/source/tutorial/advanced/actions.rst

@@ -31,21 +31,43 @@ Advanced Usage: Message Digests
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. warning::
-    This feature is not supported in Python 3.14+.
+    This feature has a different syntax in Python 3.14+.
 
 Actions can also be used to perform more complex operations, such as calculating
 checksums or cryptographic hash values before or after processing fields. For
 example, you can use an action to automatically wrap a sequence of fields with a
 specialized message digest like SHA256 (see :class:`~caterpillar.py.Digest`):
 
-.. code-block:: python
+.. tab-set::
+
+    .. tab-item:: Python <= 3.13
+
+        .. code-block:: python
+
+            @struct
+            class Format:
+                key: b"..."
+                with Sha2_256("hash", verify=True):
+                    user_data: Bytes(50)
+                # the 'hash' attribute will be set automatically
+
+
+    .. tab-item:: Python >= 3.14
+
+        .. code-block:: python
+
+            @struct
+            class Format:
+                key: b"..."
+                _hash_begin: DigestField.begin("hash", Sha2_256_Algo)
+                user_data: Bytes(50)
+                # the 'hash' attribute must be set manually
+                hash: DigestField("hash", Bytes(32), verify=True) = None
+                # or
+                hash: Sha2_256_Field("hash", verify=True) = None
+
+
 
-    @struct
-    class Format:
-        a: uint8
-        with Sha2_256("hash", verify=True):
-            user_data: Bytes(50)
-        # the 'hash' attribute will be set automatically
 
 In this example, the :code:`user_data` field is wrapped with the :code:`Sha2_256` digest action.
 When the struct is packed, a SHA256 hash is computed for the :code:`user_data` and stored
@@ -54,17 +76,36 @@ with, the verification step will raise an error.
 
 The resulting struct includes the following fields:
 
-.. code-block:: python
 
-    >>> Format.__struct__.fields
-    [
-        Field('key', struct=<ConstBytes>, ...),
-        (Action(Digest.begin), None),
-        Field('user_data', struct=<Bytes>, ...),
-        (Action(Digest.end_pack, Digest.end_unpack), None),
-        Field('hash', struct=<Bytes>, ...),
-        (UnpackAction(Digest.verfiy), None)
-    ]
+.. tab-set::
+
+    .. tab-item:: Python <= 3.13
+
+        .. code-block:: python
+
+            >>> Format.__struct__.fields
+            [
+                Field('key', struct=<ConstBytes>, ...),
+                (Action(Digest.begin), None),
+                Field('user_data', struct=<Bytes>, ...),
+                (Action(Digest.end_pack, Digest.end_unpack), None),
+                Field('hash', struct=<Bytes>, ...),
+                (UnpackAction(Digest.verfiy), None)
+            ]
+
+
+    .. tab-item:: Python >= 3.14
+
+        .. code-block:: python
+
+            >>> Format.__struct__.fields
+            [
+                Field('key', struct=<ConstBytes>, ...),
+                (<DigestFieldAction>, None),
+                Field('user_data', struct=<Bytes>, ...),
+                <DigestField>,
+            ]
+
 
 Here, you can see that:
 

pyproject.toml

@@ -10,7 +10,7 @@ cmake.source-dir = "."
 
 [project]
 name = "caterpillar"
-version = "2.4.4"
+version = "2.4.5"
 
 description="Library to pack and unpack structurized binary data."
 authors = [

src/caterpillar/__init__.py

@@ -14,7 +14,7 @@
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 import warnings
 
-__version__ = "2.4.4"
+__version__ = "2.4.5"
 __release__ = None
 __author__ = "MatrixEditor"
 

src/caterpillar/abc.py

@@ -97,7 +97,7 @@ class _SupportsUnpack(Protocol):
     """
 
     @abstractmethod
-    def __unpack__(self, context: _ContextLike):
+    def __unpack__(self, context: _ContextLike) -> Any:
         pass
 
 
@@ -123,7 +123,7 @@ def __size__(self, context: _ContextLike) -> int:
         pass
 
     @abstractmethod
-    def __unpack__(self, context: _ContextLike):
+    def __unpack__(self, context: _ContextLike) -> Any:
         pass
 
     @abstractmethod

src/caterpillar/fields/__init__.py

@@ -84,4 +84,30 @@
     Crc32,
     Adler,
     HMAC,
+    DigestField,
+    DigestFieldAction,
+    Md5_Algo,
+    Md5_Field,
+    Sha1_Algo,
+    Sha1_Field,
+    Sha2_256_Algo,
+    Sha2_256_Field,
+    Sha2_224_Algo,
+    Sha2_224_Field,
+    Sha2_384_Algo,
+    Sha2_384_Field,
+    Sha2_512_Algo,
+    Sha2_512_Field,
+    Sha3_224_Algo,
+    Sha3_224_Field,
+    Sha3_256_Algo,
+    Sha3_256_Field,
+    Sha3_384_Algo,
+    Sha3_384_Field,
+    Sha3_512_Algo,
+    Sha3_512_Field,
+    Crc32_Algo,
+    Crc32_Field,
+    Adler_Algo,
+    Adler_Field,
 )

src/caterpillar/fields/_base.py

@@ -12,7 +12,7 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
-from typing import Self, Union, Set, Any, Dict, Optional, List, Callable
+from typing import Self, Union, Set, Any, Dict, Optional, List
 from io import BytesIO
 from caterpillar.abc import (
     _StructLike,
@@ -42,7 +42,7 @@
     Flag,
 )
 from caterpillar.context import CTX_OFFSETS, CTX_STREAM
-from caterpillar.context import CTX_FIELD, CTX_POS
+from caterpillar.context import CTX_FIELD
 from caterpillar.context import CTX_VALUE, CTX_SEQ
 from caterpillar import registry
 
@@ -409,7 +409,7 @@ def __unpack__(self, context: _ContextLike) -> Optional[Any]:
             # The "keep_position" flag is not applicable here. Configure a field to keep the
             # position afterward.
             context[CTX_VALUE] = value
-            return struct.__unpack__(context)
+            value = struct.__unpack__(context)
 
         return value