Update docs and minor changes

Minor changes includes
* Improve test case of from_dict.
* Convert PreAuthEncoding to property.
* Use of TypeError instead of FormatError.

Signed-off-by: Pradyumna Krishna <[email protected]>

securesystemslib/metadata.py

@@ -3,7 +3,7 @@
 
 from typing import Any, List
 
-from securesystemslib import exceptions, formats
+from securesystemslib import formats
 from securesystemslib.signer import Signature
 from securesystemslib.util import b64dec, b64enc
 
@@ -56,6 +56,8 @@ def from_dict(cls, data: dict) -> "Envelope":
             KeyError: If any of the "payload", "payloadType" and "signatures"
                 fields are missing from the "data".
 
+            TypeError: If type of any signature in "signatures" is incorrect.
+
         Returns:
             A "Envelope" instance.
         """
@@ -65,14 +67,16 @@ def from_dict(cls, data: dict) -> "Envelope":
 
         signatures = []
         for signature in data["signatures"]:
+            if formats.GPG_SIGNATURE_SCHEMA.matches(signature):
+                raise NotImplementedError
+
             if formats.SIGNATURE_SCHEMA.matches(signature):
                 signatures.append(Signature.from_dict(signature))
 
-            elif formats.GPG_SIGNATURE_SCHEMA.matches(signature):
-                raise NotImplementedError
-
             else:
-                raise exceptions.FormatError("Invalid signature")
+                raise TypeError(
+                    f"expected type 'Signature', got {type(signature).__name__}"
+                )
 
         return cls(payload, payload_type, signatures)
 
@@ -85,9 +89,13 @@ def to_dict(self) -> dict:
             "signatures": [signature.to_dict() for signature in self.signatures],
         }
 
+    @property
     def pae(self) -> bytes:
-        """Returns the Pre-Auth-Encoding byte sequence of the self."""
+        """Pre-Auth-Encoding byte sequence of self."""
 
-        return b'DSSEv1 %d %b %d %b' % (
-            len(self.payload_type), self.payload_type.encode('utf-8'),
-            len(self.payload), self.payload)
+        return b"DSSEv1 %d %b %d %b" % (
+            len(self.payload_type),
+            self.payload_type.encode("utf-8"),
+            len(self.payload),
+            self.payload,
+        )

securesystemslib/util.py

@@ -460,43 +460,31 @@ def digests_are_equal(digest1: str, digest2: str) -> bool:
 
 
 def b64enc(data: bytes) -> str:
-  """
-  <Purpose>
-    To encode byte sequence into base64 string
+  """To encode byte sequence into base64 string
 
-  <Arguments>
-    data:
-      Byte sequence to encode
+  Arguments:
+    data: Byte sequence to encode
 
-  <Exceptions>
+  Exceptions:
     TypeError: If "data" is not byte sequence
 
-  <Side Effects>
-    None.
-
-  <Return>
+  Returns:
     base64 string
   """
 
   return base64.standard_b64encode(data).decode('utf-8')
 
 
 def b64dec(string: str) -> bytes:
-  """
-  <Purpose>
-    To decode byte sequence from base64 string
+  """To decode byte sequence from base64 string
 
-  <Arguments>
-    string:
-      base64 string to decode
+  Arguments:
+    string: base64 string to decode
 
-  <Exceptions>
+  Raises:
     binascii.Error: If invalid base64-encoded string
 
-  <Side Effects>
-    None.
-
-  <Return>
+  Returns:
     A byte sequence
   """
 

tests/test_metadata.py

@@ -3,6 +3,7 @@
 """Test cases for "metadata.py". """
 
 import copy
+from typing import Type
 import unittest
 
 from securesystemslib.metadata import Envelope
@@ -28,12 +29,18 @@ def setUpClass(cls):
     def test_envelope_from_to_dict(self):
         """Test envelope to_dict and from_dict methods"""
 
+        envelope_dict = copy.deepcopy(self.envelope_dict)
+
         # create envelope object from its dict.
-        envelope_obj = Envelope.from_dict(copy.deepcopy(self.envelope_dict))
+        envelope_obj = Envelope.from_dict(envelope_dict)
 
         # Assert envelope dict created by to_dict will be equal.
         self.assertDictEqual(self.envelope_dict, envelope_obj.to_dict())
 
+        # Assert TypeError on invalid signature
+        envelope_dict["signatures"] = [""]
+        self.assertRaises(TypeError, Envelope.from_dict, envelope_dict)
+
     def test_envelope_eq_(self):
         """Test envelope equality"""
 
@@ -64,10 +71,10 @@ def test_envelope_eq_(self):
     def test_preauthencoding(self):
         """Test envelope Pre-Auth-Encoding"""
 
-        envelope_obj = Envelope.from_dict(self.envelope_dict)
+        envelope_obj = Envelope.from_dict(copy.deepcopy(self.envelope_dict))
 
         # Checking for Pre-Auth-Encoding generated is correct.
-        self.assertEqual(self.pae, envelope_obj.pae())
+        self.assertEqual(self.pae, envelope_obj.pae)
 
 
 # Run the unit tests.