common.lib.item_mapping

  1"""
  2Classes for mapped items, i.e. complex objects mapped to simple dictionaries
  3for 4CAT processing
  4"""
  5
  6
  7class MissingMappedField:
  8    """
  9    Class for a missing field in a mapped item
 10
 11    Used if e.g. a metric is missing in the underlying data object, and
 12    processors might want to know this instead of using a default value
 13    """
 14
 15    def __init__(self, default):
 16        """
 17        Constructor
 18
 19        :param default:  Value to use as the value of this field unless the
 20        processor decides otherwise.
 21        """
 22        self.value = default
 23
 24
 25class MappedItem:
 26    """
 27    Class for mapped items
 28
 29    Mapped items are complex objects mapped to simple dictionaries for 4CAT
 30    processing. But a dictionary has limited room for annotation, so this
 31    class allows for additionally passing messages, warnings, etc.
 32    """
 33
 34    def __init__(self, data, message=""):
 35        """
 36        Constructor
 37        :param dict data:  Mapped item data
 38        :param str message:  Optionally, a message, e.g. a raised warning
 39        """
 40        self.data = data
 41        self.message = message
 42        self.missing = [k for k in self.data if type(self.data[k]) is MissingMappedField]
 43
 44    def get_item_data(self, safe=False):
 45        """
 46        Get mapped item data
 47
 48        :param bool safe:  Replace MissingMappedFields with their default value
 49        :return dict:
 50        """
 51        data = self.data.copy()
 52
 53        # replace MissingMappedFields
 54        if safe:
 55            for field, value in data.items():
 56                if type(value) is MissingMappedField:
 57                    data[field] = value.value
 58
 59        return self.data
 60
 61    def get_message(self):
 62        """
 63        Get mapped item message
 64        :return str:
 65        """
 66        return self.message
 67
 68    def get_missing_fields(self):
 69        """
 70        Get missing data fields
 71        :return list:
 72        """
 73        return self.missing
 74
 75
 76class DatasetItem(dict):
 77    """
 78    An item, from a dataset
 79
 80    This is a dict, with two special properties: 'original' and 'mapped_object'
 81    which store the unmapped version of the item and the MappedItem
 82    representation of the item, respectively. These can be used as alternative
 83    views on the same data which may offer useful capabilities in some contexts.
 84
 85    :todo: consider just-in-time mapping by only storing the original and
 86    calling the mapper only when the object is accessed as a dict
 87    """
 88    def __init__(self, mapper, original, mapped_object, *args, **kwargs):
 89        """
 90        DatasetItem init
 91
 92        :param callable mapper:  Mapper for this item. Currently unused, could
 93        be used for above-mentioned just-in-time mapping.
 94        :param dict original:  Original item, e.g. from the csv or ndjson
 95        :param MappedItem mapped_object:  Mapped item, before resolving any
 96        potential missing data
 97        """
 98        super().__init__(*args, **kwargs)
 99
100        self._mapper = mapper
101        self._original = original
102        self._mapped_object = mapped_object
103
104        if hasattr(mapped_object, "get_missing_fields"):
105            self.missing_fields = mapped_object.get_missing_fields()
106            self["missing_fields"] = ", ".join(self.missing_fields)
107
108    @property
109    def original(self):
110        """
111        Return original unmapped data
112
113        :return dict:
114        """
115        return self._original
116
117    @property
118    def mapped_object(self):
119        """
120        Return mapped item object
121
122        :return MappedItem:
123        """
124        return self._mapped_object