Rename Citation->EventIvorn.

Add `Citation` wrapper class with FutureWarning regarding deprecation.

examples/author_new_voevent.py

@@ -86,7 +86,7 @@
 
 # We can also cite earlier VOEvents:
 vp.add_citations(v,
-                 vp.Citation(
+                 vp.EventIvorn(
                      ivorn='ivo://astronomy.physics.science.org/super_exciting_events#101',
                      cite_type=vp.definitions.cite_types.followup))
 

voeventparse/__init__.py

@@ -5,10 +5,10 @@
 from __future__ import absolute_import
 
 from ._version import get_versions
+
 __version__ = get_versions()['version']
 del get_versions
 
-
 from voeventparse.voevent import (
     Voevent,
     voevent_v2_0_schema,
@@ -19,10 +19,17 @@
 )
 import voeventparse.definitions as definitions
 from voeventparse.misc import (
-    Param, Group,
-    Reference, Inference,
+    Citation,
+    EventIvorn,
+    Group,
+    Inference,
+    Param,
     Position2D,
-    Citation)
+    Reference,
+)
 from voeventparse.convenience import (
-    pull_astro_coords, pull_params, pull_isotime,
-    prettystr)
+    pull_astro_coords,
+    pull_isotime,
+    pull_params,
+    prettystr,
+)

voeventparse/definitions.py

@@ -77,7 +77,7 @@ class units:
 
 
 class cite_types:
-    """Possible types of :func:`.Citation`"""
+    """Possible types of :func:`.EventIvorn`"""
     followup = 'followup'
     supersedes = 'supersedes'
     retraction = 'retraction'

voeventparse/misc.py

@@ -24,6 +24,7 @@ class Position2D(namedtuple('Position2D', 'ra dec err units system')):
     """
     pass  # Just wrapping a namedtuple so we can assign a docstring.
 
+
 _datatypes_autoconversion = {
     bool: ('string', lambda b: str(b)),
     int: ('int', lambda i: str(i)),
@@ -74,7 +75,7 @@ def Param(name, value=None, unit=None, ucd=None, dataType=None, utype=None,
     # We use locals() to allow concise looping over the arguments.
     atts = locals()
     atts.pop('ac')
-    temp_dict={}
+    temp_dict = {}
     temp_dict.update(atts)
     for k in temp_dict.keys():
         if atts[k] is None:
@@ -83,7 +84,7 @@ def Param(name, value=None, unit=None, ucd=None, dataType=None, utype=None,
         and value is not None
         and (not isinstance(value, string_types))
         and dataType is None
-    ):
+        ):
         if type(value) in _datatypes_autoconversion:
             datatype, func = _datatypes_autoconversion[type(value)]
             atts['dataType'] = datatype
@@ -150,8 +151,9 @@ def Inference(probability=None, relation=None, name=None, concept=None):
     return inf
 
 
-def Citation(ivorn, cite_type):
-    """Used to cite earlier VOEvents.
+def EventIvorn(ivorn, cite_type):
+    """
+    Used to cite earlier VOEvents.
 
     Args:
         ivorn(string): It is assumed this will be copied verbatim from elsewhere,
@@ -167,3 +169,15 @@ def Citation(ivorn, cite_type):
     c.tag = "EventIVORN"
     return c
 
+
+def Citation(ivorn, cite_type):
+    import warnings
+    warnings.warn(
+        """
+        `Citation` class has been renamed `EventIvorn` to reflect naming
+        conventions in the VOEvent standard.
+        As such this class name is a deprecated alias and may be removed in a
+        future release.
+        """,
+        FutureWarning)
+    return EventIvorn(ivorn, cite_type)

voeventparse/tests/test_voeventparse.py

@@ -299,7 +299,7 @@ def setUp(self):
     def test_followup_citation(self):
         ref = 'ivo://nasa.gsfc.gcn/SWIFT#BAT_GRB_Pos_532871-729'
         vp.add_citations(self.v,
-                         vp.Citation(
+                         vp.EventIvorn(
                              'ivo://nasa.gsfc.gcn/SWIFT#BAT_GRB_Pos_532871-729',
                              cite_type=vp.definitions.cite_types.followup)
                          )
@@ -308,7 +308,7 @@ def test_followup_citation(self):
         # print
         # print vp.prettystr(self.v.Citations)
         vp.add_citations(self.v,
-                         vp.Citation(
+                         vp.EventIvorn(
                              'ivo://nasa.gsfc.gcn/SWIFT#BAT_GRB_Pos_532871-730',
                              cite_type=vp.definitions.cite_types.followup)
                          )

voeventparse/voevent.py

@@ -343,7 +343,7 @@ def add_why(voevent, importance=None, expires=None, inferences=None):
         voevent.Why.extend(_listify(inferences))
 
 
-def add_citations(voevent, citations):
+def add_citations(voevent, event_ivorns):
     """Add citations to other voevents.
 
     The schema mandates that the 'Citations' section must either be entirely
@@ -352,12 +352,13 @@ def add_citations(voevent, citations):
 
     Args:
         voevent(:class:`Voevent`): Root node of a VOEvent etree.
-        citation(:class:`voeventparse.misc.Citation`): Citation or list of citations.
+        event_ivorns (:class:`voeventparse.misc.EventIvorn`): List of EventIvorn
+            elements to add to citation list.
 
     """
     if not voevent.xpath('Citations'):
         etree.SubElement(voevent, 'Citations')
-    voevent.Citations.extend(_listify(citations))
+    voevent.Citations.extend(_listify(event_ivorns))
 
 
 # ###################################################