metadata: add write_files_metadata

derivermodule/metadata.py

@@ -6,12 +6,14 @@ from xml.dom import minidom
 
 import hashlib, zlib
 
+from json import dump
+
 from subprocess import check_output
 from collections import OrderedDict
 
 import xmltodict
 
-from .const import PB_ITEM
+from .const import PB_ITEM, PB_TASK
 
 
 def parse_item_metadata(path):
@@ -116,6 +118,9 @@ def load_files_metadata(identifier):
     modified) object. Use `lookup_file_metadata` to get a reference to the
     metadata of a specific file.
 
+    There is no way to save changes made to this structure, so users have to
+    treat the result as read-only.
+
     Args:
 
     * identifier (``str``): Identifier of the item
@@ -130,6 +135,39 @@ def load_files_metadata(identifier):
     return xmltodict.parse(data)
 
 
+def write_files_metadata(files_metadata):
+    """
+    Write additional metadata for a set of files.
+    This function cannot add metadata to arbitrary files, only to the target
+    file and any extra targets specified in
+    ``derivermodule.task.write_extra_targets``. It also cannot delete metadata
+    values, nor does it have to: any files that are created by this module will
+    have no metadata associated with it, so there will be nothing to delete.
+
+    Metadata values can be of type ``str`` or ``list (of str)``.
+
+    Args:
+
+    * files_metadata: a dictionary where the key is a canonical item filename
+                      (see ``derivermodule.files.canonical_item_filename``)
+                      and the value is a key-value metadata pairs.
+
+    Returns:
+
+    * Nothing
+
+    Example:
+
+    >>> from derivermodule.files import canonical_item_filename
+    >>> md = {'foo_module_version': '0.0.1'}
+    >>> write_files_metadata({canonical_item_filename(target_file): md})
+    """
+    files_metadata_file = join(PB_TASK, 'extra_metadata.json')
+    fp = open(files_metadata_file, 'w+')
+    dump(files_metadata, fp)
+    fp.close()
+
+
 ## TODO: Perform a *LOT* of testing on this
 #def write_files_metadata(identifier, metadata):
 #    """