projectal.entity

  1"""
  2The base Entity class that all entities inherit from.
  3"""
  4import copy
  5import logging
  6import sys
  7
  8import projectal
  9from projectal import api
 10
 11
 12class Entity(dict):
 13    """
 14    The parent class for all our entities, offering requests
 15    and validation for the fundamental create/read/update/delete
 16    operations.
 17
 18    This class (and all our entities) inherit from the builtin
 19    `dict` class. This means all entity classes can be used
 20    like standard Python dictionary objects, but we can also
 21    offer additional utility functions that operate on the
 22    instance itself (see `linkers` for an example). Any method
 23    that expects a `dict` can also consume an `Entity` subclass.
 24
 25    The class methods in this class can operate on one or more
 26    entities in one request. If the methods are called with
 27    lists (for batch operation), the output returned will also
 28    be a list. Otherwise, a single `Entity` subclass is returned.
 29
 30    Note for batch operations: a `ProjectalException` is raised
 31    if *any* of the entities fail during the operation. The
 32    changes will *still be saved to the database for the entities
 33    that did not fail*.
 34    """
 35
 36    #: Child classes must override these with their entity names
 37    _path = 'entity'  # URL portion to api
 38    _name = 'entity'
 39
 40    # And to which entities they link to
 41    _links = []
 42    _links_reverse = []
 43
 44    def __init__(self, data):
 45        dict.__init__(self, data)
 46        self._is_new = True
 47        self._link_def_by_key = {}
 48        self._link_def_by_name = {}
 49        self._create_link_defs()
 50        self._with_links = set()
 51
 52        self.__fetch = self.get
 53        self.get = self.__get
 54        self.update = self.__update
 55        self.delete = self.__delete
 56        self.history = self.__history
 57        self.__old = copy.deepcopy(self)
 58        self.__type_links()
 59
 60    # ----- LINKING -----
 61
 62    def _create_link_defs(self):
 63        for cls in self._links:
 64            self._add_link_def(cls)
 65        for cls in self._links_reverse:
 66            self._add_link_def(cls, reverse=True)
 67
 68    def _add_link_def(self, cls, reverse=False):
 69        """
 70        Each entity is accompanied by a dict with details about how to
 71        get access to the data of the link within the object. Subclasses
 72        can pass in customizations to this dict when their APIs differ.
 73
 74        reverse denotes a reverse linker, where extra work is done to
 75        reverse the relationship of the link internally so that it works.
 76        The backend only offers one side of the relationship.
 77        """
 78        d = {
 79            'name': cls._link_name,
 80            'link_key': cls._link_key or cls._link_name + 'List',
 81            'data_name': cls._link_data_name,
 82            'type': cls._link_type,
 83            'entity': cls._link_entity or cls._link_name.capitalize(),
 84            'reverse': reverse
 85        }
 86        self._link_def_by_key[d['link_key']] = d
 87        self._link_def_by_name[d['name']] = d
 88
 89    def _add_link(self, to_entity_name, to_link):
 90        self._link(to_entity_name, to_link, 'add')
 91
 92    def _update_link(self,to_entity_name, to_link):
 93        self._link(to_entity_name, to_link, 'update')
 94
 95    def _delete_link(self, to_entity_name, to_link):
 96        self._link(to_entity_name, to_link, 'delete')
 97
 98    def _link(self, to_entity_name, to_link, operation, update_cache=True):
 99        """
100        `to_entity_name`: Destination entity name (e.g. 'staff')
101
102        `to_link`: List of Entities of the same type (and optional data) to link to
103
104        `operation`: `add`, `update`, `delete`
105
106        update_cache: also modify the entity's internal representation of the links
107        to match the operation that was done. Set this to False when replacing the
108        list with a new one (i.e., when calling save() instead of a linker method).
109        """
110
111        link_def = self._link_def_by_name[to_entity_name]
112        to_key = link_def['link_key']
113
114        if isinstance(to_link, dict) and link_def['type'] == list:
115            # Convert input dict to list when link type is a list (we allow linking to single entity for convenience)
116            to_link = [to_link]
117
118            # For cases where user passed in dict instead of Entity, we turn them into
119            # Entity on their behalf.
120            typed_list = []
121            target_cls = getattr(sys.modules['projectal.entities'], link_def['entity'])
122            for link in to_link:
123                if not isinstance(link, target_cls):
124                    typed_list.append(target_cls(link))
125                else:
126                    typed_list.append(link)
127            to_link = typed_list
128        else:
129            # For everything else, we expect types to match.
130            if not isinstance(to_link, link_def['type']):
131                raise api.UsageException('Expected link type to be {}. Got {}.'.format(link_def['type'], type(to_link)))
132
133        if not to_link:
134            return
135
136        # Is it a reverse linker? If so, invert the relationship
137        if link_def['reverse']:
138            for link in to_link:
139                link._link(self._name, self, operation, update_cache)
140        else:
141            # Only keep UUID and the data attribute, if it has one
142            def strip_payload(link):
143                single = {'uuId': link['uuId']}
144                data_name = link_def.get('data_name')
145                if data_name and data_name in link:
146                    single[data_name] = copy.deepcopy(link[data_name])
147                return single
148
149            to_link_payload = None
150            if isinstance(to_link, list):
151                to_link_payload = []
152                for link in to_link:
153                    to_link_payload.append(strip_payload(link))
154            if isinstance(to_link, dict):
155                to_link_payload = strip_payload(to_link)
156
157            payload = {
158                'uuId': self['uuId'],
159                to_key: to_link_payload
160            }
161            url = '/api/{}/link/{}/{}'.format(self._path, to_entity_name, operation)
162            api.post(url, payload=payload)
163
164        if not update_cache:
165            return
166
167        # Set the initial state if first add. We need the type to be set to correctly update the cache
168        if operation == 'add' and self.get(to_key, None) is None:
169            if link_def.get('type') == dict:
170                self[to_key] = {}
171            elif link_def.get('type') == list:
172                self[to_key] = []
173
174        # Modify the entity object's cache of links to match the changes we pushed to the server.
175        if isinstance(self.get(to_key, []), list):
176            if operation == 'add':
177                # Sometimes the backend doesn't return a list when it has none. Create it.
178                if to_key not in self:
179                    self[to_key] = []
180
181                for to_entity in to_link:
182                    self[to_key].append(to_entity)
183            else:
184                for to_entity in to_link:
185                    # Find it in original list
186                    for i, old in enumerate(self.get(to_key, [])):
187                        if old['uuId'] == to_entity['uuId']:
188                            if operation == 'update':
189                                self[to_key][i] = to_entity
190                            elif operation == 'delete':
191                                del self[to_key][i]
192        if isinstance(self.get(to_key, None), dict):
193            if operation in ['add', 'update']:
194                self[to_key] = to_link
195            elif operation == 'delete':
196                self[to_key] = None
197
198        # Update the "old" record of the link on the entity to avoid
199        # flagging it for changes (link lists are not meant to be user editable).
200        if to_key in self:
201            self.__old[to_key] = self[to_key]
202
203    # -----
204
205    @classmethod
206    def create(cls, entities, params=None):
207        """
208        Create one or more entities of the same type. The entity
209        type is determined by the subclass calling this method.
210
211        `entities`: Can be a `dict` to create a single entity,
212        or a list of `dict`s to create many entities in bulk.
213
214        `params`: Optional URL parameters that may apply to the
215        entity's API (e.g: `?holder=1234`).
216
217        If input was a `dict`, returns an entity subclass. If input was
218        a list of `dict`s, returns a list of entity subclasses.
219
220        ```
221        # Example usage:
222        projectal.Customer.create({'name': 'NewCustomer'})
223        # returns Customer object
224        ```
225        """
226
227        if isinstance(entities, dict):
228            # Dict input needs to be a list
229            e_list = [entities]
230        else:
231            # We have a list of dicts already, the expected format
232            e_list = entities
233
234        # Apply type
235        typed_list = []
236        for e in e_list:
237            if not isinstance(e, Entity):
238                # Start empty to correctly populate history
239                new = cls({})
240                new.update(e)
241                typed_list.append(new)
242            else:
243                typed_list.append(e)
244        e_list = typed_list
245
246        endpoint = '/api/{}/add'.format(cls._path)
247        if params:
248            endpoint += params
249        if not e_list:
250            return []
251
252        # Strip links from payload
253        payload = []
254        keys = e_list[0]._link_def_by_key.keys()
255        for e in e_list:
256            cleancopy = copy.deepcopy(e)
257            # Remove any fields that match a link key
258            for key in keys:
259                cleancopy.pop(key, None)
260            payload.append(cleancopy)
261
262        objects = []
263        for i in range(0, len(payload), projectal.chunk_size_write):
264            chunk = payload[i:i + projectal.chunk_size_write]
265            orig_chunk = e_list[i:i + projectal.chunk_size_write]
266            response = api.post(endpoint, chunk)
267            # Put uuId from response into each input dict
268            for e, o, orig in zip(chunk, response, orig_chunk):
269                orig['uuId'] = o['uuId']
270                orig.__old = copy.deepcopy(orig)
271                # Delete links from the history in order to trigger a change on them after
272                for key in orig._link_def_by_key:
273                    orig.__old.pop(key, None)
274                objects.append(orig)
275
276        # Detect and apply any link additions
277        for e in e_list:
278            e.__apply_link_changes()
279
280        if not isinstance(entities, list):
281            return objects[0]
282        return objects
283
284    @classmethod
285    def _get_linkset(cls, links):
286        """Get a set of link names we have been asked to fetch with. Raise an
287        error if the requested link is not valid for this Entity type."""
288        link_set = set()
289        if links is not None:
290            if isinstance(links, str) or not hasattr(links, '__iter__'):
291                raise projectal.UsageException("Parameter 'links' must be a list or None.")
292
293            defs = cls({})._link_def_by_name
294            for link in links:
295                name = link.lower()
296                if name not in defs:
297                    raise projectal.UsageException(
298                        "Link '{}' is invalid for {}".format(name, cls._name))
299                link_set.add(name)
300        return link_set
301
302    @classmethod
303    def get(cls, entities, links=None, deleted_at=None):
304        """
305        Get one or more entities of the same type. The entity
306        type is determined by the subclass calling this method.
307
308        `entities`: One of several formats containing the `uuId`s
309        of the entities you want to get (see bottom for examples):
310
311        - `str` or list of `str`
312        - `dict` or list of `dict` (with `uuId` key)
313
314        `links`: A case-insensitive list of entity names to fetch with
315        this entity. For performance reasons, links are only returned
316        on demand.
317
318        Links follow a common naming convention in the output with
319        a *_List* suffix. E.g.:
320        `links=['company', 'location']` will appear as `companyList` and
321        `locationList` in the response.
322        ```
323        # Example usage:
324        # str
325        projectal.Project.get('1b21e445-f29a-4a9f-95ff-fe253a3e1b11')
326
327        # list of str
328        ids = ['1b21e445-f29a...', '1b21e445-f29a...', '1b21e445-f29a...']
329        projectal.Project.get(ids)
330
331        # dict
332        project = project.Project.create({'name': 'MyProject'})
333        # project = {'uuId': '1b21e445-f29a...', 'name': 'MyProject', ...}
334        projectal.Project.get(project)
335
336        # list of dicts (e.g. from a query)
337        # projects = [{'uuId': '1b21e445-f29a...'}, {'uuId': '1b21e445-f29a...'}, ...]
338        project.Project.get(projects)
339
340        # str with links
341        projectal.Project.get('1b21e445-f29a...', 'links=['company', 'location']')
342        ```
343
344        `deleted_at`: Include this parameter to get a deleted entity.
345        This value should be a UTC timestamp from a webhook delete event.
346        """
347        link_set = cls._get_linkset(links)
348
349        if isinstance(entities, str):
350            # String input is a uuId
351            payload = [{'uuId': entities}]
352        elif isinstance(entities, dict):
353            # Dict input needs to be a list
354            payload = [entities]
355        elif isinstance(entities, list):
356            # List input can be a list of uuIds or list of dicts
357            # If uuIds (strings), convert to list of dicts
358            if len(entities) > 0 and isinstance(entities[0], str):
359                payload = [{'uuId': uuId} for uuId in entities]
360            else:
361                # Already expected format
362                payload = entities
363        else:
364            # We have a list of dicts already, the expected format
365            payload = entities
366
367        if deleted_at:
368            if not isinstance(deleted_at, int):
369                raise projectal.UsageException("deleted_at must be a number")
370
371        url = '/api/{}/get'.format(cls._path)
372        params = []
373        params.append('links={}'.format(','.join(links))) if links else None
374        params.append('epoch={}'.format(deleted_at - 1)) if deleted_at else None
375        if len(params) > 0:
376            url += '?' + '&'.join(params)
377
378        # We only need to send over the uuIds
379        payload = [{'uuId': e['uuId']} for e in payload]
380        if not payload:
381            return []
382        objects = []
383        for i in range(0, len(payload), projectal.chunk_size_read):
384            chunk = payload[i:i + projectal.chunk_size_read]
385            dicts = api.post(url, chunk)
386            for d in dicts:
387                obj = cls(d)
388                obj._with_links.update(link_set)
389                obj._is_new = False
390                # Create default fields for links we ask for. Workaround for backend
391                # sometimes omitting links if no links exist.
392                for link_name in link_set:
393                    link_def = obj._link_def_by_name[link_name]
394                    if link_def['link_key'] not in obj:
395                        if link_def['type'] == dict:
396                            obj.set_readonly(link_def['link_key'], None)
397                        else:
398                            obj.set_readonly(link_def['link_key'], link_def['type']())
399                objects.append(obj)
400
401        if not isinstance(entities, list):
402            return objects[0]
403        return objects
404
405    def __get(self, *args, **kwargs):
406        """Use the dict get for instances."""
407        return super(Entity, self).get(*args, **kwargs)
408
409    @classmethod
410    def update(cls, entities):
411        """
412        Save one or more entities of the same type. The entity
413        type is determined by the subclass calling this method.
414        Only the fields that have been modifier will be sent
415        to the server as part of the request.
416
417        `entities`: Can be a `dict` to update a single entity,
418        or a list of `dict`s to update many entities in bulk.
419
420        Returns `True` if all entities update successfully.
421
422        ```
423        # Example usage:
424        rebate = projectal.Rebate.create({'name': 'Rebate2022', 'rebate': 0.2})
425        rebate['name'] = 'Rebate2024'
426        projectal.Rebate.update(rebate)
427        # Returns True. New rebate name has been saved.
428        ```
429        """
430        if isinstance(entities, dict):
431            e_list = [entities]
432        else:
433            e_list = entities
434
435        # Reduce the list to only modified entities and their modified fields.
436        # Only do this to an Entity subclass - the consumer may have passed
437        # in a dict of changes on their own.
438        payload = []
439
440        for e in e_list:
441            if isinstance(e, Entity):
442                changes = e._changes_internal()
443                if changes:
444                    changes['uuId'] = e['uuId']
445                    payload.append(changes)
446            else:
447                payload.append(e)
448        if payload:
449            for i in range(0, len(payload), projectal.chunk_size_write):
450                chunk = payload[i:i + projectal.chunk_size_write]
451                api.put('/api/{}/update'.format(cls._path), chunk)
452
453        # Detect and apply any link changes
454        for e in e_list:
455            if isinstance(e, Entity):
456                e.__apply_link_changes()
457        return True
458
459    def __update(self, *args, **kwargs):
460        """Use the dict update for instances."""
461        return super(Entity, self).update(*args, **kwargs)
462
463    def save(self):
464        """Calls `update()` on this instance of the entity, saving
465        it to the database."""
466        return self.__class__.update(self)
467
468    @classmethod
469    def delete(cls, entities):
470        """
471        Delete one or more entities of the same type. The entity
472        type is determined by the subclass calling this method.
473
474        `entities`: See `Entity.get()` for expected formats.
475
476        ```
477        # Example usage:
478        ids = ['1b21e445-f29a...', '1b21e445-f29a...', '1b21e445-f29a...']
479        projectal.Customer.delete(ids)
480        ```
481        """
482        if isinstance(entities, str):
483            # String input is a uuId
484            payload = [{'uuId': entities}]
485        elif isinstance(entities, dict):
486            # Dict input needs to be a list
487            payload = [entities]
488        elif isinstance(entities, list):
489            # List input can be a list of uuIds or list of dicts
490            # If uuIds (strings), convert to list of dicts
491            if len(entities) > 0 and isinstance(entities[0], str):
492                payload = [{'uuId': uuId} for uuId in entities]
493            else:
494                # Already expected format
495                payload = entities
496        else:
497            # We have a list of dicts already, the expected format
498            payload = entities
499
500        # We only need to send over the uuIds
501        payload = [{'uuId': e['uuId']} for e in payload]
502        if not payload:
503            return True
504        for i in range(0, len(payload), projectal.chunk_size_write):
505            chunk = payload[i:i + projectal.chunk_size_write]
506            api.delete('/api/{}/delete'.format(cls._path), chunk)
507        return True
508
509    def __delete(self):
510        """Let an instance delete itself."""
511        return self.__class__.delete(self)
512
513    def clone(self, entity):
514        """
515        Clones an entity and returns its `uuId`.
516
517        Each entity has its own set of required values when cloning.
518        Check the API documentation of that entity for details.
519        """
520        url = '/api/{}/clone?reference={}'.format(self._path, self['uuId'])
521        response = api.post(url, entity)
522        return response['jobClue']['uuId']
523
524    @classmethod
525    def history(cls, UUID, start=0, limit=-1, order='desc', epoch=None, event=None):
526        """
527        Returns an ordered list of all changes made to the entity.
528
529        `UUID`: the UUID of the entity.
530
531        `start`: Start index for pagination (default: `0`).
532
533        `limit`: Number of results to include for pagination. Use
534        `-1` to return the entire history (default: `-1`).
535
536        `order`: `asc` or `desc` (default: `desc` (index 0 is newest))
537
538        `epoch`: only return the history UP TO epoch date
539
540        `event`:
541        """
542        url = '/api/{}/history?holder={}&'.format(cls._path, UUID)
543        params = []
544        params.append('start={}'.format(start))
545        params.append('limit={}'.format(limit))
546        params.append('order={}'.format(order))
547        params.append('epoch={}'.format(epoch)) if epoch else None
548        params.append('event={}'.format(event)) if event else None
549        url += '&'.join(params)
550        return api.get(url)
551
552    def __history(self, **kwargs):
553        """Get history of instance."""
554        return self.__class__.history(self['uuId'], **kwargs)
555
556    @classmethod
557    def list(cls, expand=False, links=None):
558        """Return a list of all entity UUIDs of this type.
559
560        You may pass in `expand=True` to get full Entity objects
561        instead, but be aware this may be very slow if you have
562        thousands of objects.
563
564        If you are expanding the objects, you may further expand
565        the results with `links`.
566        """
567
568        payload = {
569            "name": "List all entities of type {}".format(cls._name.upper()),
570            "type": "msql", "start": 0, "limit": -1,
571            "select": [
572                ["{}.uuId".format(cls._name.upper())]
573            ],
574        }
575        ids = api.query(payload)
576        ids = [id[0] for id in ids]
577        if ids:
578            return cls.get(ids, links=links) if expand else ids
579        return []
580
581    @classmethod
582    def match(cls, field, term, links=None):
583        """Find entities where `field`=`term` (exact match), optionally
584        expanding the results with `links`.
585
586        Relies on `Entity.query()` with a pre-built set of rules.
587        ```
588        projects = projectal.Project.match('identifier', 'zmb-005')
589        ```
590        """
591        filter = [["{}.{}".format(cls._name.upper(), field), "eq", term]]
592        return cls.query(filter, links)
593
594    @classmethod
595    def match_startswith(cls, field, term, links=None):
596        """Find entities where `field` starts with the text `term`,
597        optionally expanding the results with `links`.
598
599        Relies on `Entity.query()` with a pre-built set of rules.
600        ```
601        projects = projectal.Project.match_startswith('name', 'Zomb')
602        ```
603        """
604        filter = [["{}.{}".format(cls._name.upper(), field), "prefix", term]]
605        return cls.query(filter, links)
606
607    @classmethod
608    def match_endswith(cls, field, term, links=None):
609        """Find entities where `field` ends with the text `term`,
610        optionally expanding the results with `links`.
611
612        Relies on `Entity.query()` with a pre-built set of rules.
613        ```
614        projects = projectal.Project.match_endswith('identifier', '-2023')
615        ```
616        """
617        term = "(?i).*{}$".format(term)
618        filter = [["{}.{}".format(cls._name.upper(), field), "regex", term]]
619        return cls.query(filter, links)
620
621    @classmethod
622    def match_one(cls, field, term, links=None):
623        """Convenience function for match(). Returns the first match or None."""
624        matches = cls.match(field, term, links)
625        if matches:
626            return matches[0]
627
628    @classmethod
629    def match_startswith_one(cls, field, term, links=None):
630        """Convenience function for match_startswith(). Returns the first match or None."""
631        matches = cls.match_startswith(field, term, links)
632        if matches:
633            return matches[0]
634
635    @classmethod
636    def match_endswith_one(cls, field, term, links=None):
637        """Convenience function for match_endswith(). Returns the first match or None."""
638        matches = cls.match_endswith(field, term, links)
639        if matches:
640            return matches[0]
641
642    @classmethod
643    def search(cls, fields=None, term='', case_sensitive=True, links=None):
644        """Find entities that contain the text `term` within `fields`.
645        `fields` is a list of field names to target in the search.
646
647        `case_sensitive`: Optionally turn off case sensitivity in the search.
648
649        Relies on `Entity.query()` with a pre-built set of rules.
650        ```
651        projects = projectal.Project.search(['name', 'description'], 'zombie')
652        ```
653        """
654        filter = []
655        term = '(?{}).*{}.*'.format('' if case_sensitive else '?', term)
656        for field in fields:
657            filter.append(["{}.{}".format(cls._name.upper(), field), "regex", term])
658        filter = ['_or_', filter]
659        return cls.query(filter, links)
660
661    @classmethod
662    def query(cls, filter, links=None):
663        """Run a query on this entity with the supplied filter.
664
665        The query is already set up to target this entity type, and the
666        results will be converted into full objects when found, optionally
667        expanded with the `links` provided. You only need to supply a
668        filter to reduce the result set.
669
670        See [the filter documentation](https://projectal.com/docs/v1.1.1#section/Filter-section)
671        for a detailed overview of the kinds of filters you can construct.
672        """
673        payload = {
674            "name": "Python library entity query ({})".format(cls._name.upper()),
675            "type": "msql", "start": 0, "limit": -1,
676            "select": [
677                ["{}.uuId".format(cls._name.upper())]
678            ],
679            "filter": filter
680        }
681        ids = api.query(payload)
682        ids = [id[0] for id in ids]
683        if ids:
684            return cls.get(ids, links=links)
685        return []
686
687    def profile_get(self, key):
688        """Get the profile (metadata) stored for this entity at `key`."""
689        return projectal.profile.get(key, self.__class__._name.lower(), self['uuId'])
690
691    def profile_set(self, key, data):
692        """Set the profile (metadata) stored for this entity at `key`. The contents
693        of `data` will completely overwrite the existing data dictionary."""
694        return projectal.profile.set(key, self.__class__._name.lower(), self['uuId'], data)
695
696    def __type_links(self):
697        """Find links and turn their dicts into typed objects matching their Entity type."""
698
699        for key, _def in self._link_def_by_key.items():
700            if key in self:
701                cls = getattr(projectal, _def['entity'])
702                if _def['type'] == list:
703                    as_obj = []
704                    for link in self[key]:
705                        as_obj.append(cls(link))
706                elif _def['type'] == dict:
707                    as_obj = cls(self[key])
708                else:
709                    raise projectal.UsageException("Unexpected link type")
710                self[key] = as_obj
711
712    def changes(self):
713        """Return a dict containing the fields that have changed since fetching the object.
714        Dict values contain both the old and new values. E.g.: {'old': 'original', 'new': 'current'}.
715
716        In the case of link lists, there are three values: added, removed, updated. Only links with
717        a data attribute can end up in the updated list, and the old/new dictionary is placed within
718        that data attribute. E.g. for a staff-resource link:
719        'updated': [{
720            'uuId': '24eb4c31-0f92-49d1-8b4d-507ab939003e',
721            'resourceLink': {'quantity': {'old': 2, 'new': 5}}
722        }]
723        """
724        changed = {}
725        for key in self.keys():
726            link_def = self._link_def_by_key.get(key)
727            if link_def:
728                changes = self._changes_for_link_list(link_def, key)
729                # Only add it if something in it changed
730                for action in changes.values():
731                    if len(action):
732                        changed[key] = changes
733                        break
734            elif key not in self.__old and self[key] is not None:
735                changed[key] = {'old': None, 'new': self[key]}
736            elif self.__old.get(key) != self[key]:
737                changed[key] = {'old': self.__old.get(key), 'new': self[key]}
738        return changed
739
740    def _changes_for_link_list(self, link_def, key):
741        changes = self.__apply_list(link_def, report_only=True)
742        data_key = link_def['data_name']
743
744        # For linked entities, we will only report their UUID, name (if it has one),
745        # and the content of their data attribute (if it has one).
746        def get_slim_list(entities):
747            slim = []
748            if isinstance(entities, dict):
749                entities = [entities]
750            for e in entities:
751                fields = {'uuId': e['uuId']}
752                name = e.get('name')
753                if name:
754                    fields['name'] = e['name']
755                if data_key and e[data_key]:
756                    fields[data_key] = e[data_key]
757                slim.append(fields)
758            return slim
759
760        out = {
761            'added': get_slim_list(changes.get('add', [])),
762            'updated': [],
763            'removed': get_slim_list(changes.get('remove', [])),
764        }
765
766        updated = changes.get('update', [])
767        if updated:
768            before_map = {}
769            for entity in self.__old.get(key):
770                before_map[entity['uuId']] = entity
771
772            for entity in updated:
773                old_data = before_map[entity['uuId']][data_key]
774                new_data = entity[data_key]
775                diff = {}
776                for key in new_data.keys():
777                    if key not in old_data and new_data[key] is not None:
778                        diff[key] = {'old': None, 'new': new_data[key]}
779                    elif old_data.get(key) != new_data[key]:
780                        diff[key] = {'old': old_data.get(key), 'new': new_data[key]}
781                out['updated'].append({'uuId': entity['uuId'], data_key: diff})
782        return out
783
784    def _changes_internal(self):
785        """Return a dict containing only the fields that have changed and their current value,
786        without any link data.
787
788        This method is used internally to strip payloads down to only the fields that have changed.
789        """
790        changed = {}
791        for key in self.keys():
792            # We don't deal with link or link data changes here. We only want standard fields.
793            if key in self._link_def_by_key:
794                continue
795            if key not in self.__old and self[key] is not None:
796                changed[key] = self[key]
797            elif self.__old.get(key) != self[key]:
798                changed[key] = self[key]
799        return changed
800
801    def set_readonly(self, key, value):
802        """Set a field on this Entity that will not be sent over to the
803        server on update unless modified."""
804        self[key] = value
805        self.__old[key] = value
806
807    # --- Link management ---
808
809    @staticmethod
810    def __link_data_differs(have_link, want_link, data_key):
811
812        if data_key:
813            if 'uuId' in have_link[data_key]:
814                del have_link[data_key]['uuId']
815            if 'uuId' in want_link[data_key]:
816                del want_link[data_key]['uuId']
817            return have_link[data_key] != want_link[data_key]
818
819        # Links without data never differ
820        return False
821
822    def __apply_link_changes(self):
823        """Send each link list to the conflict resolver. If we detect
824        that the entity was not fetched with that link, we do the fetch
825        first and use the result as the basis for comparison."""
826
827        # Find which lists belong to links but were not fetched so we can fetch them
828        need = []
829        find_list = []
830        if not self._is_new:
831            for link in self._link_def_by_key.values():
832                if link['link_key'] in self and link['name'] not in self._with_links:
833                    need.append(link['name'])
834                    find_list.append(link['link_key'])
835
836        if len(need):
837            logging.warning("Entity links were modified but entity not fetched with links. "
838                            "For better performance, include the links when getting the entity.")
839            logging.warning("Fetching {} again with missing links: {}".format(self._name.upper(), ','.join(need)))
840            new = self.__fetch(self, links=need)
841            for _list in find_list:
842                self.__old[_list] = copy.deepcopy(new.get(_list, []))
843
844        for keys in self._link_def_by_key.values():
845            self.__apply_list(keys)
846
847    def __apply_list(self, link_def, report_only=False):
848        """Automatically resolve differences and issue the correct sequence of
849        link/unlink/relink for the link list to result in the supplied list
850        of entities.
851
852        report_only will not make any changes to the data or issue network requests.
853        Instead, it returns the three lists of changes (add, update, delete).
854        """
855        to_add = []
856        to_remove = []
857        to_update = []
858        should_only_have = set()
859        link_key = link_def['link_key']
860
861        if link_def['type'] == list:
862            want_entities = self.get(link_key, [])
863            have_entities = self.__old.get(link_key, [])
864
865            if not isinstance(want_entities, list):
866                raise api.UsageException("Expecting '{}' to be {}. Found {} instead.".format(
867                    link_key, link_def['type'].__name__, type(want_entities).__name__))
868
869            for want_entity in want_entities:
870                if want_entity['uuId'] in should_only_have:
871                    raise api.UsageException("Duplicate {} in {}".format(link_def['name'], link_key))
872                should_only_have.add(want_entity['uuId'])
873                have = False
874                for have_entity in have_entities:
875                    if have_entity['uuId'] == want_entity['uuId']:
876                        have = True
877                        data_name = link_def.get('data_name')
878                        if data_name and self.__link_data_differs(have_entity, want_entity, data_name):
879                            to_update.append(want_entity)
880                if not have:
881                    to_add.append(want_entity)
882            for have_entity in have_entities:
883                if have_entity['uuId'] not in should_only_have:
884                    to_remove.append(have_entity)
885        elif link_def['type'] == dict:
886            # Note: dict type does not implement updates as we have no dict links
887            # that support update (yet?).
888            want_entity = self.get(link_key, None)
889            have_entity = self.__old.get(link_key, None)
890
891            if want_entity is not None and not isinstance(want_entity, dict):
892                raise api.UsageException("Expecting '{}' to be {}. Found {} instead.".format(
893                    link_key, link_def['type'].__name__, type(have_entity).__name__))
894
895            if want_entity:
896                if have_entity:
897                    if want_entity['uuId'] != have_entity['uuId']:
898                        to_remove = have_entity
899                        to_add = want_entity
900                else:
901                    to_add = want_entity
902            if not want_entity:
903                if have_entity:
904                    to_remove = have_entity
905
906            want_entities = want_entity
907        else:
908            # Would be an error in this library if we reach here
909            raise projectal.UnsupportedException("This type does not support linking")
910
911        if not report_only:
912            if to_remove:
913                self._link(link_def['name'], to_remove, 'delete', update_cache=False)
914            if to_update:
915                self._link(link_def['name'], to_update, 'update', update_cache=False)
916            if to_add:
917                self._link(link_def['name'], to_add, 'add', update_cache=False)
918
919            self.__old[link_key] = copy.deepcopy(want_entities)
920        else:
921            changes = {}
922            if to_remove:
923                changes['remove'] = to_remove
924            if to_update:
925                changes['update'] = to_update
926            if to_add:
927                changes['add'] = to_add
928            return changes
929
930    @classmethod
931    def get_link_definitions(cls):
932        return cls({})._link_def_by_name
933    # --- ---
934
935    def entity_name(self):
936        return self._name.capitalize()