Re-order metadata methods logically and add vspace

Signed-off-by: Lukas Puehringer <[email protected]>

Author: lukpueh

tuf/api/metadata.py

@@ -18,9 +18,12 @@
 
  * Add Root metadata class
 
+ * Add classes for other complex metadata attributes, see 'signatures' (in
+   Metadata) 'meta'/'targets' (in Timestamp, Snapshot, Targets), 'delegations'
+   (in Targets), 'keys'/'roles' (in not yet existent 'Delegation'), ...
+
 """
 # Imports
-
 from datetime import datetime, timedelta
 from typing import Any, Dict, Optional
 
@@ -45,12 +48,10 @@
 
 
 # Types
-
 JsonDict = Dict[str, Any]
 
 
 # Classes.
-
 class Metadata():
     """A container for signed TUF metadata.
 
@@ -77,12 +78,50 @@ def __init__(self, signed: 'Signed', signatures: list) -> None:
         self.signed = signed
         self.signatures = signatures
 
-    def to_dict(self) -> JsonDict:
-        """Returns the JSON-serializable dictionary representation of self. """
-        return {
-            'signatures': self.signatures,
-            'signed': self.signed.to_dict()
-        }
+
+    # Deserialization (factories).
+    @classmethod
+    def from_dict(cls, metadata: JsonDict) -> 'Metadata':
+        """Creates Metadata object from its JSON/dict representation.
+
+        Calls 'from_dict' for any complex metadata attribute represented by a
+        class also that has a 'from_dict' factory method. (Currently this is
+        only the signed attribute.)
+
+        Arguments:
+            metadata: TUF metadata in JSON/dict representation, as e.g.
+            returned by 'json.loads'.
+
+        Raises:
+            KeyError: The metadata dict format is invalid.
+            ValueError: The metadata has an unrecognized signed._type field.
+
+        Returns:
+            A TUF Metadata object.
+
+        """
+        # Dispatch to contained metadata class on metadata _type field.
+        _type = metadata['signed']['_type']
+
+        if _type == 'targets':
+            inner_cls = Targets
+        elif _type == 'snapshot':
+            inner_cls = Snapshot
+        elif _type == 'timestamp':
+            inner_cls = Timestamp
+        elif _type == 'root':
+            # TODO: implement Root class
+            raise NotImplementedError('Root not yet implemented')
+        else:
+            raise ValueError(f'unrecognized metadata type "{_type}"')
+
+        # NOTE: If Signature becomes a class, we should iterate over
+        # metadata['signatures'], call Signature.from_dict for each item, and
+        # pass a list of Signature objects to the Metadata constructor intead.
+        return cls(
+                signed=inner_cls.from_dict(metadata['signed']),
+                signatures=metadata['signatures'])
+
 
     @classmethod
     def from_json(cls, metadata_json: str) -> 'Metadata':
@@ -102,6 +141,40 @@ def from_json(cls, metadata_json: str) -> 'Metadata':
         return cls.from_dict(load_json_string(metadata_json))
 
 
+    @classmethod
+    def from_json_file(
+            cls, filename: str,
+            storage_backend: Optional[StorageBackendInterface] = None
+            ) -> 'Metadata':
+        """Loads JSON-formatted TUF metadata from file storage.
+
+        Arguments:
+            filename: The path to read the file from.
+            storage_backend: An object that implements
+                securesystemslib.storage.StorageBackendInterface. Per default
+                a (local) FilesystemBackend is used.
+
+        Raises:
+            securesystemslib.exceptions.StorageError: The file cannot be read.
+            securesystemslib.exceptions.Error, ValueError, KeyError: The
+                metadata cannot be parsed.
+
+        Returns:
+            A TUF Metadata object.
+
+        """
+        return cls.from_dict(load_json_file(filename, storage_backend))
+
+
+    # Serialization.
+    def to_dict(self) -> JsonDict:
+        """Returns the JSON-serializable dictionary representation of self. """
+        return {
+            'signatures': self.signatures,
+            'signed': self.signed.to_dict()
+        }
+
+
     def to_json(self, compact: bool = False) -> None:
         """Returns the optionally compacted JSON representation of self. """
         return json.dumps(
@@ -110,6 +183,30 @@ def to_json(self, compact: bool = False) -> None:
                 separators=((',', ':') if compact else (',', ': ')),
                 sort_keys=True)
 
+
+    def to_json_file(
+            self, filename: str, compact: bool = False,
+            storage_backend: StorageBackendInterface = None) -> None:
+        """Writes the JSON representation of self to file storage.
+
+        Arguments:
+            filename: The path to write the file to.
+            compact: A boolean indicating if the JSON string should be compact
+                    by excluding whitespace.
+            storage_backend: An object that implements
+                securesystemslib.storage.StorageBackendInterface. Per default
+                a (local) FilesystemBackend is used.
+        Raises:
+            securesystemslib.exceptions.StorageError:
+                The file cannot be written.
+
+        """
+        with tempfile.TemporaryFile() as f:
+            f.write(self.to_json(compact).encode('utf-8'))
+            persist_temp_file(f, filename, storage_backend)
+
+
+    # Signatures.
     def sign(self, key: JsonDict, append: bool = False) -> JsonDict:
         """Creates signature over 'signed' and assigns it to 'signatures'.
 
@@ -137,6 +234,7 @@ def sign(self, key: JsonDict, append: bool = False) -> JsonDict:
 
         return signature
 
+
     def verify(self, key: JsonDict) -> bool:
         """Verifies 'signatures' over 'signed' that match the passed key by id.
 
@@ -172,93 +270,6 @@ def verify(self, key: JsonDict) -> bool:
 
         return True
 
-    @classmethod
-    def from_json_file(
-            cls, filename: str,
-            storage_backend: Optional[StorageBackendInterface] = None
-            ) -> 'Metadata':
-        """Loads JSON-formatted TUF metadata from file storage.
-
-        Arguments:
-            filename: The path to read the file from.
-            storage_backend: An object that implements
-                securesystemslib.storage.StorageBackendInterface. Per default
-                a (local) FilesystemBackend is used.
-
-        Raises:
-            securesystemslib.exceptions.StorageError: The file cannot be read.
-            securesystemslib.exceptions.Error, ValueError, KeyError: The
-                metadata cannot be parsed.
-
-        Returns:
-            A TUF Metadata object.
-
-        """
-        return cls.from_dict(load_json_file(filename, storage_backend))
-
-    @classmethod
-    def from_dict(cls, metadata: JsonDict) -> 'Metadata':
-        """Creates Metadata object from its JSON/dict representation.
-
-        Calls 'from_dict' for any complex metadata attribute represented by a
-        class also that has a 'from_dict' factory method. (Currently this is
-        only the signed attribute.)
-
-        Arguments:
-            metadata: TUF metadata in JSON/dict representation, as e.g.
-            returned by 'json.loads'.
-
-        Raises:
-            KeyError: The metadata dict format is invalid.
-            ValueError: The metadata has an unrecognized signed._type field.
-
-        Returns:
-            A TUF Metadata object.
-
-        """
-        # Dispatch to contained metadata class on metadata _type field.
-        _type = metadata['signed']['_type']
-
-        if _type == 'targets':
-            inner_cls = Targets
-        elif _type == 'snapshot':
-            inner_cls = Snapshot
-        elif _type == 'timestamp':
-            inner_cls = Timestamp
-        elif _type == 'root':
-            # TODO: implement Root class
-            raise NotImplementedError('Root not yet implemented')
-        else:
-            raise ValueError(f'unrecognized metadata type "{_type}"')
-
-        # NOTE: If Signature becomes a class, we should iterate over
-        # metadata['signatures'], call Signature.from_dict for each item, and
-        # pass a list of Signature objects to the Metadata constructor intead.
-        return cls(
-                signed=inner_cls.from_dict(metadata['signed']),
-                signatures=metadata['signatures'])
-
-
-    def to_json_file(
-            self, filename: str, compact: bool = False,
-            storage_backend: StorageBackendInterface = None) -> None:
-        """Writes the JSON representation of self to file storage.
-
-        Arguments:
-            filename: The path to write the file to.
-            compact: A boolean indicating if the JSON string should be compact
-                    by excluding whitespace.
-            storage_backend: An object that implements
-                securesystemslib.storage.StorageBackendInterface. Per default
-                a (local) FilesystemBackend is used.
-        Raises:
-            securesystemslib.exceptions.StorageError:
-                The file cannot be written.
-
-        """
-        with tempfile.TemporaryFile() as f:
-            f.write(self.to_json(compact).encode('utf-8'))
-            persist_temp_file(f, filename, storage_backend)
 
 class Signed:
     """A base class for the signed part of TUF metadata.
@@ -293,6 +304,8 @@ def __init__(
             raise ValueError(f'version must be < 0, got {version}')
         self.version = version
 
+
+    # Deserialization (factories).
     @classmethod
     def from_dict(cls, signed_dict) -> 'Signed':
         """Creates Signed object from its JSON/dict representation. """
@@ -314,17 +327,12 @@ def from_dict(cls, signed_dict) -> 'Signed':
         # that subclass (see e.g. Metadata.from_dict).
         return cls(**signed_dict)
 
+
+    # Serialization.
     def to_canonical_bytes(self) -> bytes:
         """Returns the UTF-8 encoded canonical JSON representation of self. """
         return encode_canonical(self.to_dict()).encode('UTF-8')
 
-    def bump_expiration(self, delta: timedelta = timedelta(days=1)) -> None:
-        """Increments the expires attribute by the passed timedelta. """
-        self.expires += delta
-
-    def bump_version(self) -> None:
-        """Increments the metadata version number by 1."""
-        self.version += 1
 
     def to_dict(self) -> JsonDict:
         """Returns the JSON-serializable dictionary representation of self. """
@@ -335,6 +343,18 @@ def to_dict(self) -> JsonDict:
             'expires': self.expires.isoformat() + 'Z'
         }
 
+
+    # Modification.
+    def bump_expiration(self, delta: timedelta = timedelta(days=1)) -> None:
+        """Increments the expires attribute by the passed timedelta. """
+        self.expires += delta
+
+
+    def bump_version(self) -> None:
+        """Increments the metadata version number by 1."""
+        self.version += 1
+
+
 class Timestamp(Signed):
     """A container for the signed part of timestamp metadata.
 
@@ -361,6 +381,8 @@ def __init__(
         # TODO: Add class for meta
         self.meta = meta
 
+
+    # Serialization.
     def to_dict(self) -> JsonDict:
         """Returns the JSON-serializable dictionary representation of self. """
         json_dict = super().to_dict()
@@ -369,6 +391,8 @@ def to_dict(self) -> JsonDict:
         })
         return json_dict
 
+
+    # Modification.
     def update(self, version: int, length: int, hashes: JsonDict) -> None:
         """Assigns passed info about snapshot metadata to meta dict. """
         self.meta['snapshot.json'] = {
@@ -411,6 +435,7 @@ def __init__(
         # TODO: Add class for meta
         self.meta = meta
 
+    # Serialization.
     def to_dict(self) -> JsonDict:
         """Returns the JSON-serializable dictionary representation of self. """
         json_dict = super().to_dict()
@@ -419,7 +444,8 @@ def to_dict(self) -> JsonDict:
         })
         return json_dict
 
-    # Add or update metadata about the targets metadata.
+
+    # Modification.
     def update(
             self, rolename: str, version: int, length: Optional[int] = None,
             hashes: Optional[JsonDict] = None) -> None:
@@ -497,6 +523,7 @@ def __init__(
         self.delegations = delegations
 
 
+    # Serialization.
     def to_dict(self) -> JsonDict:
         """Returns the JSON-serializable dictionary representation of self. """
         json_dict = super().to_dict()
@@ -506,7 +533,7 @@ def to_dict(self) -> JsonDict:
         })
         return json_dict
 
-    # Add or update metadata about the target.
+    # Modification.
     def update(self, filename: str, fileinfo: JsonDict) -> None:
         """Assigns passed target file info to meta dict. """
         self.targets[filename] = fileinfo