Update createVOEvent for superevents

Adapting createVOEvent to work with superevents. Note that this
required some server-side changes to the part of the events API
which handles VOEvent creation.  Also changed the arguments
(instead of sticking everything in kwargs) and updated the docstring.

ligo/gracedb/rest.py

@@ -1611,36 +1611,87 @@ class GraceDb(GsiRest):
         return response
 
     @event_or_superevent
-    def createVOEvent(self, graceid, voevent_type, *args, **kwargs):
+    def createVOEvent(self, object_id, voevent_type, skymap_type=None,
+        skymap_filename=None, skymap_image_filename=None, internal=True,
+        vetted=False, open_alert=False, hardware_inj=False,
+        CoincComment=False, ProbHasNS=None, ProbHasRemnant=None,
+        *args, **kwargs):
         # TBD for superevents - requires a lot of changes to server code
         """Create a new VOEvent
 
         Signature:
-            createVOEvent(graceid, voevent_type, *args, **kwargs)
-
-        Required args: graceid, voevent_type
+            createVOEvent(self, object_id, voevent_type, skymap_type=None,
+                skymap_filename=None, skymap_image_filename=None,
+                internal=True, vetted=False, open_alert=False,
+                hardware_inj=False, CoincComment=False, ProbHasNS=None,
+                ProbHasRemnant=None)
 
-        Additional keyword arguments may be passed in to be sent in the POST
-        data. Only the following kwargs are recognized:
-            skymap_filename
-            skyamp_type
+        Arguments:
+            object_id: event graceid or superevent id
+            voevent_type: VOEvent type (options: 'preliminary', 'initial',
+                          'update', 'retraction')
+            skymap_type: skymap type (required for voevents which include a
+                         skymap)
+            skymap_filename: name of skymap file in GraceDB (required for
+                             'initial' and 'update' alerts, optional for
+                             'preliminary' alerts.
+            skymap_image_filename: name of skymap image file in GraceDB
+                                   (same requirements as skymap_filename)
+            internal: whether the VOEvent should be distributed to LVC members
+                      only (True/False)
+            hardware_inj: whether the candidate is a hardware injection
+                          (True/False)
+            vetted: whether candidate has undergone basic human vetting
+                    (True/False)
+            open_alert: whether the candidate is an open alert or not
+                        (True/False)
+            CoincComment: whether the candidate has a possible counterpart
+                          GRB (True/False)
+            ProbHasNS: probability that at least one object in the binary is
+                       less than 3 M_sun (optional)
+            ProbHasRemnant: probability that there is matter in the
+                            surroundings of the central object (optional)
 
-        Any other kwargs will be ignored.
         """
         is_superevent = kwargs.pop('is_superevent', False)
         if is_superevent:
-            raise NotImplementedError('Not yet implemented for superevents')
-        # validate facility, waveband, eel_status, and obs_status
+            template = self.templates['superevent-voevent-list-template']
+            uri_kwargs = {'superevent_id': object_id}
+        else:
+            template = self.templates['voevent-list-template']
+            uri_kwargs = {'graceid': object_id}
+        uri = template.format(**uri_kwargs)
+
+        # validate voevent_type, convert to short form if necessary
         voevent_type = self._getCode(voevent_type.lower(), self.voevent_types)
         if not voevent_type:
-            raise ValueError("voevent_type must be one of: %s" % list(self.voevent_types.values()))
-        template = self.templates['voevent-list-template']
-        uri = template.format(graceid=graceid)
+            raise ValueError("voevent_type must be one of: {0}".format(
+                list(self.voevent_types.values())))
+
+        # TODO:
+        # Require skymaps for 'update' and 'initial'
 
+        # Construct request body
         body = {
-            'voevent_type' : voevent_type,
+            'voevent_type': voevent_type,
+            'internal': internal,
+            'vetted': vetted,
+            'open_alert': open_alert,
+            'hardware_inj': hardware_inj,
+            'CoincComment': CoincComment
         }
-        body.update(**kwargs)
+        # Add optional args
+        if skymap_type:
+            body['skymap_type'] = skymap_type
+        if skymap_filename:
+            body['skymap_filename'] = skymap_filename
+        if skymap_image_filename:
+            body['skymap_image_filename'] = skymap_image_filename
+        if ProbHasNS:
+            body['ProbHasNS'] = ProbHasNS
+        if ProbHasRemnant:
+            body['ProbHasRemnant'] = ProbHasRemnant
+
         return self.post(uri, body=body)