Merge pull request #1027 from joshuagl/joshuagl/custom

Improve error message and docstring for custom parameter in `add_target()`

Author: SantiagoTorres

tuf/formats.py

@@ -300,7 +300,10 @@
 # The fileinfo format of targets specified in the repository and
 # developer tools.  The fields match that of FILEINFO_SCHEMA, only all
 # fields are optional.
-CUSTOM_SCHEMA = SCHEMA.Object()
+CUSTOM_SCHEMA = SCHEMA.DictOf(
+  key_schema = SCHEMA.AnyString(),
+  value_schema = SCHEMA.Any()
+)
 LOOSE_FILEINFO_SCHEMA = SCHEMA.Object(
   object_name = "LOOSE_FILEINFO_SCHEMA",
   length = SCHEMA.Optional(LENGTH_SCHEMA),

tuf/repository_tool.py

@@ -1929,12 +1929,6 @@ def add_target(self, filepath, custom=None, fileinfo=None):
       Add a filepath (must be relative to the repository's targets directory)
       to the Targets object.
 
-      This method does not access the file system. 'filepath' must already
-      exist on the file system.
-
-      If 'filepath' does not exist the file will still be added to 'roleinfo'.
-      Only later calls to write() and writeall() will fail.
-
       If 'filepath' has already been added, it will be replaced with any new
       file or 'custom' information.
 
@@ -1948,11 +1942,21 @@ def add_target(self, filepath, custom=None, fileinfo=None):
         targets directory.
 
       custom:
-        An optional object providing additional information about the file.
+        An optional dictionary providing additional information about the file.
+        NOTE: if a custom value is passed, the fileinfo parameter must be None.
+        This parameter will be deprecated in a future release of tuf, use of
+        the fileinfo parameter is preferred.
 
       fileinfo:
-        An optional fileinfo object, conforming to tuf.formats.FILEINFO_SCHEMA,
-        providing full information about the file.
+        An optional fileinfo dictionary, conforming to
+        tuf.formats.FILEINFO_SCHEMA, providing full information about the
+        file, i.e:
+          { 'length': 101,
+            'hashes': { 'sha256': '123EDF...' },
+            'version': 2, # optional
+            'custom': { 'permissions': '600'} # optional
+          }
+        NOTE: if a custom value is passed, the fileinfo parameter must be None.
 
     <Exceptions>
       securesystemslib.exceptions.FormatError, if 'filepath' is improperly