NTV.json_ntv.ntv_comment

  1# -*- coding: utf-8 -*-
  2"""
  3Created on Sun Oct  2 22:24:59 2022
  4
  5@author: philippe@loco-labs.io
  6
  7The `NTV.json_ntv.ntv_comment` module contains the `NtvComment` class.
  8"""
  9import json
 10from json_ntv.ntv_patch import NtvPatch
 11
 12
 13class NtvComment:
 14    '''This class includes comments and change management methods for NTV entities :
 15
 16    *Attributes :*
 17
 18    - **_ntv** : Ntv entity being commented on
 19    - **_comments**:  list of NtvPatch to apply to the NTV entity
 20
 21    *dynamic values (@property)*
 22    - `comments`
 23    - `ntv`
 24
 25    *instance method*
 26    - `add`
 27    - `accept`
 28    - `reject`
 29    - `json`
 30    '''
 31
 32    def __init__(self, ntv, comments=None):
 33        ''' constructor
 34
 35        *Parameters*
 36
 37        - **ntv**: Ntv - NTV entity being commented on
 38        - **comments**: list of NtvPatch (default None) - comments applied to the entity
 39        '''
 40        self._ntv = ntv
 41        self._comments = []
 42        if not comments:
 43            return
 44        if comments.__class__.__name__ in ('NtvPatch', 'NtvOp'):
 45            self._comments = [NtvPatch(comments)]
 46        elif isinstance(comments, list):
 47            self._comments = [NtvPatch(comment) for comment in comments]
 48
 49    def __repr__(self):
 50        ''' string representation'''
 51        if not self._comments:
 52            return 'no comments'
 53        return json.dumps(self.json())
 54
 55    def __eq__(self, other):
 56        ''' equal if _comments and _ntv are equal'''
 57        return self.__class__.__name__ == other.__class__.__name__ and\
 58            self._ntv == other._ntv and self._comments == other._comments
 59
 60    @property
 61    def comments(self):
 62        '''getters _comments'''
 63        return self._comments
 64
 65    @property
 66    def ntv(self):
 67        '''getters _ntv'''
 68        return self._ntv
 69
 70    def add(self, comment=None):
 71        '''add comment in the list of comments
 72
 73        *Parameters*
 74
 75        - **comment**: NtvPatch (default None) - new comment to apply
 76        '''
 77        self._comments.append(NtvPatch(comment))
 78        return len(self._comments)-1
 79
 80    def reject(self, all_comment=False):
 81        '''remove the last or all comments
 82
 83        *Parameters*
 84
 85        - **all_comment**: Boolean (default False) - if False, remove the last comment
 86
 87        *return*: resulting NtvComment
 88        '''
 89        if all_comment or len(self._comments) <= 1:
 90            return NtvComment(self._ntv, [])
 91        return NtvComment(self._ntv, self._comments[:-1])
 92
 93    def accept(self, all_comment=True):
 94        '''apply the first or all comments
 95
 96        *Parameters*
 97
 98        - **all_comment**: Boolean (default True) - if False, apply the first comment
 99
100        *return*: resulting NtvComment
101        '''
102        if not self._comments:
103            return NtvComment(self._ntv, self._comments)
104        apply = self._comments if all_comment else [self._comments[0]]
105        ntv = self._ntv
106        for comment in apply:
107            ntv = comment.exe(ntv)
108        return NtvComment(ntv, [] if all_comment else self._comments[1:])
109
110    def json(self, ntv=False, comments=True):
111        ''' return json-value.
112
113        *Parameters*
114
115        - **ntv**: Boolean (default False) - if True, include ntv
116        - **comments**: Boolean (default True) - if True, include comments
117
118        *return*: resulting json-value
119        '''
120        jsn = {}
121        if self._comments and comments:
122            jsn['comments'] = [comment.json for comment in self._comments]
123        if ntv:
124            jsn['ntv'] = self._ntv.to_obj()
125        return jsn