Metadata API: Document constructor default arguments

Signed-off-by: Jussi Kukkonen <[email protected]>

tuf/api/metadata.py

@@ -104,6 +104,14 @@ class Metadata(Generic[T]):
     ``[Root]`` is not validated at runtime (as pure annotations are not available
     then).
 
+    New Metadata instances can created from scratch with::
+
+        one_day = datetime.utcnow() + timedelta(days=1)
+        timestamp = Metadata(Timestamp(expires=one_day))
+
+    Apart from ``expires`` all of the arguments to the inner constructors have
+    reasonable default values for new metadata.
+
     *All parameters named below are not just constructor arguments but also
     instance attributes.*
 
@@ -112,6 +120,7 @@ class Metadata(Generic[T]):
             ``Snapshot``, ``Timestamp`` or ``Root``.
         signatures: Ordered dictionary of keyids to ``Signature`` objects, each
             signing the canonical serialized representation of ``signed``.
+            Default is an empty dictionary.
         unrecognized_fields: Dictionary of all attributes that are not managed
             by TUF Metadata API. These fields are NOT signed and it's preferable
             if unrecognized fields are added to the Signed derivative classes.
@@ -444,9 +453,10 @@ class Signed(metaclass=abc.ABCMeta):
     instance attributes.*
 
     Args:
-        version: Metadata version number.
-        spec_version: Supported TUF specification version number.
-        expires: Metadata expiry date.
+        version: Metadata version number. Default is 1.
+        spec_version: Supported TUF specification version. Default is the
+            version currently supported by the library.
+        expires: Metadata expiry date. Default is current date and time.
         unrecognized_fields: Dictionary of all attributes that are not managed
             by TUF Metadata API
 
@@ -825,13 +835,17 @@ class Root(Signed):
     Parameters listed below are also instance attributes.
 
     Args:
-        version: Metadata version number.
-        spec_version: Supported TUF specification version number.
-        expires: Metadata expiry date.
+        version: Metadata version number. Default is 1.
+        spec_version: Supported TUF specification version. Default is the
+            version currently supported by the library.
+        expires: Metadata expiry date. Default is current date and time.
         keys: Dictionary of keyids to Keys. Defines the keys used in ``roles``.
+            Default is empty dictionary.
         roles: Dictionary of role names to Roles. Defines which keys are
-            required to sign the metadata for a specific role.
+            required to sign the metadata for a specific role. Default is
+            a dictionary of top level roles without keys and threshold of 1.
         consistent_snapshot: ``True`` if repository supports consistent snapshots.
+            Default is True.
         unrecognized_fields: Dictionary of all attributes that are not managed
             by TUF Metadata API
 
@@ -1122,12 +1136,14 @@ class Timestamp(Signed):
     instance attributes.*
 
     Args:
-        version: Metadata version number.
-        spec_version: Supported TUF specification version number.
-        expires: Metadata expiry date.
+        version: Metadata version number. Default is 1.
+        spec_version: Supported TUF specification version. Default is the
+            version currently supported by the library.
+        expires: Metadata expiry date. Default is current date and time.
         unrecognized_fields: Dictionary of all attributes that are not managed
             by TUF Metadata API
-        snapshot_meta: Meta information for snapshot metadata.
+        snapshot_meta: Meta information for snapshot metadata. Default is a
+            MetaFile with version 1.
 
     Raises:
         ValueError: Invalid arguments.
@@ -1183,12 +1199,14 @@ class Snapshot(Signed):
     instance attributes.*
 
     Args:
-        version: Metadata version number.
-        spec_version: Supported TUF specification version number.
-        expires: Metadata expiry date.
+        version: Metadata version number. Default is 1.
+        spec_version: Supported TUF specification version. Default is the
+            version currently supported by the library.
+        expires: Metadata expiry date. Default is current date and time.
         unrecognized_fields: Dictionary of all attributes that are not managed
             by TUF Metadata API
         meta: Dictionary of target metadata filenames to ``MetaFile`` objects.
+            Default is a dictionary with a Metafile for "snapshot.json".
 
     Raises:
         ValueError: Invalid arguments.
@@ -1650,12 +1668,14 @@ class Targets(Signed):
     instance attributes.*
 
     Args:
-        version: Metadata version number.
-        spec_version: Supported TUF specification version number.
-        expires: Metadata expiry date.
-        targets: Dictionary of target filenames to TargetFiles
+        version: Metadata version number. Default is 1.
+        spec_version: Supported TUF specification version. Default is the
+            version currently supported by the library.
+        expires: Metadata expiry date. Default is current date and time.
+        targets: Dictionary of target filenames to TargetFiles. Default is an
+            empty dictionary.
         delegations: Defines how this Targets delegates responsibility to other
-            Targets Metadata files.
+            Targets Metadata files. Default is None.
         unrecognized_fields: Dictionary of all attributes that are not managed
             by TUF Metadata API