NTV.json_ntv.ntv

   1# -*- coding: utf-8 -*-
   2"""
   3Created on Feb 27 2023
   4
   5@author: Philippe@loco-labs.io
   6
   7The `ntv` module is part of the `NTV.json_ntv` package ([specification document](
   8https://loco-philippe.github.io/ES/JSON%20semantic%20format%20(JSON-NTV).htm)).
   9
  10It contains the classes `NtvSingle`, `NtvList`, `Ntv`(abstract) for NTV entities.
  11
  12For more information, see the 
  13[user guide](https://loco-philippe.github.io/NTV/documentation/user_guide.html) 
  14or the [github repository](https://github.com/loco-philippe/NTV).
  15
  16"""
  17import copy
  18from abc import ABC, abstractmethod
  19from numbers import Number
  20import json
  21
  22from json_ntv.namespace import NtvType, Namespace, str_type, relative_type, agreg_type
  23from json_ntv.ntv_util import NtvError, NtvJsonEncoder, NtvConnector, NtvTree, NtvUtil
  24from json_ntv.ntv_patch import NtvPointer
  25
  26
  27class Ntv(ABC):
  28    ''' The Ntv class is an abstract class used by `NtvSingle`and `NtvList` classes.
  29
  30    *Attributes :*
  31    - **ntv_name** :  String - name of the NTV entity
  32    - **ntv_type**:   NtvType - type of the entity
  33    - **ntv_value**:  value of the entity
  34
  35    *Internal attributes :*
  36    - **parent**:     parent NtvList entity
  37    - **is_json**:    True if ntv_value is a json_value
  38
  39    *dynamic values (@property)*
  40    - `json_array` (abstract method)
  41    - `type_str`
  42    - `code_ntv`
  43    - `max_len`
  44    - `name`
  45    - `tree`
  46    - `val`
  47
  48    The methods defined in this class are :
  49
  50    *Ntv constructor (staticmethod)*
  51    - `fast`
  52    - `obj`
  53    - `from_obj`
  54    - `from_att`
  55
  56    *NTV conversion (instance methods)*
  57    - `alike`
  58    - `to_json_ntv`
  59    - `to_obj_ntv`
  60
  61    *export - conversion (instance methods)*
  62    - `expand`
  63    - `to_fast`
  64    - `to_name`
  65    - `to_obj`
  66    - `to_repr`
  67    - `to_mermaid`
  68    - `to_tuple`
  69    - `to_ntvsingle`
  70    - `to_ntvlist`
  71    - `notype`
  72
  73    *tree methods (instance methods)*
  74    - `childs`
  75    - `pointer`
  76    - `replace`
  77    - `remove`
  78    - `append` (NtvList only)
  79    - `insert` (NtvList only)
  80
  81    *other instance methods*
  82    - `from_value`
  83    - `json_name`
  84    - `set_name`
  85    - `set_type`
  86    - `set_value`
  87    - `obj_value` (abstract method)
  88
  89    *utility methods*
  90    - `decode_json` *(staticmethod)*
  91    - `obj_ntv` *(staticmethod)*
  92    '''
  93
  94    def __init__(self, ntv_value, ntv_name, ntv_type):
  95        '''Ntv constructor.
  96
  97        *Parameters*
  98
  99        - **ntv_value**: Json entity - value of the entity
 100        - **ntv_name** : String (default None) - name of the NTV entity
 101        - **ntv_type**: String or NtvType or Namespace (default None) - type of the entity
 102        '''
 103        if isinstance(ntv_type, (NtvType, Namespace)):
 104            self.ntv_type = ntv_type
 105        elif ntv_type and ntv_type[-1] != '.':
 106            self.ntv_type = NtvType.add(ntv_type)
 107        elif ntv_type and ntv_type[-1] == '.':
 108            self.ntv_type = Namespace.add(ntv_type)
 109        else:
 110            self.ntv_type = None
 111        if not isinstance(ntv_name, str):
 112            ntv_name = ''
 113        self.ntv_name = ntv_name
 114        self.ntv_value = ntv_value
 115        self.is_json = NtvConnector.is_json(ntv_value)
 116        self.parent = None
 117
 118    @staticmethod
 119    def fast(data, no_typ=False, typ_auto=False):
 120        ''' return an Ntv entity from data without conversion.
 121
 122        *Parameters* : see `obj` method'''
 123        return Ntv.obj(data, no_typ=no_typ, typ_auto=typ_auto, fast=True)
 124
 125    @staticmethod
 126    def obj(data, no_typ=False, decode_str=False, typ_auto=False, fast=False):
 127        ''' return an Ntv entity from data.
 128
 129        *Parameters*
 130
 131        - **Data** can be :
 132            - a tuple with value, name, typ and cat (see `from_att` method)
 133            - a value to decode (see `from_obj`method)
 134        - **no_typ** : boolean (default False) - if True, NtvList is with 'json' type
 135        - **type_auto**: boolean (default False) - if True, default type for NtvList
 136        is the ntv_type of the first Ntv in the ntv_value
 137        - **fast** : boolean (default False) - if True, Ntv entity is created without conversion
 138        - **decode_str**: boolean (default False) - if True, string are loaded in json data'''
 139        if isinstance(data, tuple):
 140            return Ntv.from_att(*data, decode_str=decode_str, fast=fast)
 141        # if isinstance(data, str) and data.lstrip() and data.lstrip()[0] in '{[':
 142        if isinstance(data, str):
 143            try:
 144                data = json.loads(data)
 145            except json.JSONDecodeError:
 146                pass
 147        return Ntv.from_obj(data, no_typ=no_typ, decode_str=decode_str,
 148                            typ_auto=typ_auto, fast=fast)
 149
 150    @staticmethod
 151    def from_att(value, name, typ, cat, decode_str=False, fast=False):
 152        ''' return an Ntv entity.
 153
 154        *Parameters*
 155
 156        - **value**: Ntv entity or value to convert in an Ntv entity
 157        - **name** : string - name of the Ntv entity
 158        - **typ** : string or NtvType - type of the NTV entity
 159        - **cat**: string - NTV category ('single', 'list')
 160        - **fast** : boolean (default False) - if True, Ntv entity is created without conversion
 161        - **decode_str**: boolean (default False) - if True, string are loaded as json data'''
 162
 163        value = Ntv._from_value(value, decode_str)
 164        if value.__class__.__name__ in ['NtvSingle', 'NtvList']:
 165            return value
 166        if isinstance(value, list) and cat == 'list':
 167            return NtvList(value, name, typ, fast=fast)
 168        if cat == 'single':
 169            return NtvSingle(value, name, typ, fast=fast)
 170        return Ntv.from_obj(value, def_type=typ, fast=fast)
 171
 172    @staticmethod
 173    def from_obj(value, def_type=None, def_sep=None, no_typ=False, decode_str=False,
 174                 typ_auto=False, fast=False):
 175        ''' return an Ntv entity from an object value.
 176
 177        *Parameters*
 178
 179        - **value**: Ntv value to convert in an Ntv entity
 180        - **no_typ** : boolean (default None) - if True, NtvList is with 'json' type
 181        - **def_type** : NtvType or Namespace (default None) - default type of the value
 182        - **def_sep**: ':', '::' or None (default None) - default separator of the value
 183        - **decode_str**: boolean (default False) - if True, string are loaded as json data
 184        - **type_auto**: boolean (default False) - if True, default type for NtvList
 185        is the ntv_type of the first Ntv in the ntv_value
 186        - **fast** : boolean (default False) - if True, Ntv entity is created without conversion'''
 187        value = Ntv._from_value(value, decode_str)
 188        if value.__class__.__name__ in ['NtvSingle', 'NtvList']:
 189            return value
 190        ntv_value, ntv_name, str_typ, sep, is_json = Ntv.decode_json(value)
 191        sep = def_sep if not sep else sep
 192        if isinstance(ntv_value, list) and sep in (None, '::'):
 193            return Ntv._create_ntvlist(str_typ, def_type, sep, ntv_value,
 194                                       typ_auto, no_typ, ntv_name, fast)
 195        if sep == ':' or (sep is None and isinstance(ntv_value, dict) and
 196                          len(ntv_value) == 1):
 197            ntv_type = agreg_type(str_typ, def_type, False)
 198            return NtvSingle(ntv_value, ntv_name, ntv_type, fast=fast)
 199        if sep is None and not isinstance(ntv_value, dict):
 200            is_single_json = isinstance(value, (int, str, float, bool))
 201            ntv_type = agreg_type(str_typ, def_type, is_single_json)
 202            return NtvSingle(ntv_value, ntv_name, ntv_type, fast=fast)
 203        if isinstance(ntv_value, dict) and (sep == '::' or len(ntv_value) != 1 and
 204                                            sep is None):
 205            return Ntv._create_ntvlist(str_typ, def_type, sep, ntv_value,
 206                                       typ_auto, no_typ, ntv_name, fast)
 207        raise NtvError('separator ":" is not compatible with value')
 208
 209    def __len__(self):
 210        ''' len of ntv_value'''
 211        if isinstance(self.ntv_value, list):
 212            return len(self.ntv_value)
 213        return 1
 214
 215    def __str__(self):
 216        '''return string format'''
 217        return self.to_obj(encoded=True)
 218
 219    def __repr__(self):
 220        '''return classname and code'''
 221        #return json.dumps(self.to_repr(False, False, False, 10), cls=NtvJsonEncoder)
 222        return self.reduce(obj=False, level=3, maxi=6).to_obj(encoded=True)
 223
 224    def __contains__(self, item):
 225        ''' item of Ntv entities'''
 226        if isinstance(self.val, list):
 227            return item in self.ntv_value
 228        return item == self.ntv_value
 229
 230    def __iter__(self):
 231        ''' iterator for Ntv entities'''
 232        if isinstance(self, NtvSingle):
 233            return iter([self.val])
 234        return iter(self.val)
 235
 236    def __getitem__(self, selec):
 237        ''' return ntv_value item with selec:
 238            - String beginning with "/" : json-pointer,
 239            - string : name of the ntv,
 240            - list : recursive selector
 241            - tuple : list of name or index '''
 242        if selec is None or selec == [] or selec == () or selec == '':
 243            return self
 244        if isinstance(selec, (list, tuple)) and len(selec) == 1:
 245            selec = selec[0]
 246        if isinstance(selec, str) and len(selec) > 1 and selec[0] == '/':
 247            selec = list(NtvPointer(selec))
 248        elif isinstance(selec, NtvPointer):
 249            selec = list(selec)
 250        if (selec == 0 or selec == self.ntv_name) and isinstance(self, NtvSingle):
 251            return self.ntv_value
 252        if isinstance(self, NtvSingle):
 253            raise NtvError('item not present')
 254        if isinstance(selec, tuple):
 255            return [self[i] for i in selec]
 256        if isinstance(selec, str) and isinstance(self, NtvList):
 257            ind = [ntv.ntv_name for ntv in self.ntv_value].index(selec)
 258            return self.ntv_value[ind]
 259        if isinstance(selec, list) and isinstance(self, NtvList):
 260            return self[selec[0]][selec[1:]]
 261        return self.ntv_value[selec]
 262
 263    def __lt__(self, other):
 264        ''' return a comparison between two ntv_value'''
 265        # order: number > string > None
 266        res = Ntv.lower(self, other)
 267        if res is None:
 268            res = None if len(self) == len(other) else len(self) < len(other)
 269        res = self.to_obj(encoded=True) < other.to_obj(encoded=True) if res is None else res
 270        return res
 271
 272    @staticmethod
 273    def lower(val1, val2):
 274        ''' compare two ntv_value and return True if val1 < val2, False if val1 > val2 and 
 275        None in the other cases'''
 276        res = None
 277        for v1, v2 in zip(Ntv.obj(val1).tree.leaf_nodes, Ntv.obj(val2).tree.leaf_nodes):
 278            if v1.val is None:
 279                res = True
 280            elif isinstance(v1.val, (dict, list)):
 281                res = Ntv.lower(v1.val, v2)
 282            elif isinstance(v2.val, (dict, list)):
 283                res = Ntv.lower(v1, v2.val)
 284            elif isinstance(v1.val, Number):
 285                if isinstance(v2.val, Number):
 286                    res = None if v1.val == v2.val else v1.val < v2.val
 287                else:
 288                    res = False
 289            elif isinstance(v1.val, str):
 290                if isinstance(v2.val, Number):
 291                    res = True
 292                elif isinstance(v2.val, str):
 293                    res = None if v1.val == v2.val else v1.val < v2.val
 294                else:
 295                    res = False
 296            if not res is None:
 297                break
 298        return res 
 299    
 300    def childs(self, obj=False, nam=False, typ=False):
 301        ''' return a list of child Ntv entities or child data
 302        
 303        *parameters*
 304        
 305        - **obj**: boolean (default False) - return json-value
 306        - **nam**: boolean (default False) - return name (with or without type) 
 307        - **typ**: boolean (default False) - return type (with or without name) 
 308        '''
 309        if isinstance(self, NtvSingle):
 310            return []
 311        if not (obj or nam or typ):
 312            return self.val
 313        if obj:
 314            return [ntv.to_obj() for ntv in self.val]
 315        return [(ntv.name if nam else '') + (' - ' if nam and typ else '') + 
 316                (ntv.type_str if typ else '') for ntv in self.val]
 317        
 318    def pointer(self, index=False, item_idx=None):
 319        '''return a nested list of pointer from root
 320        
 321        *Parameters*
 322
 323        - **index**: Boolean (default False) - use index instead of name
 324        - **item_idx**: Integer (default None) - index value for the pointer 
 325        (useful with duplicate data)'''
 326        if not self.parent:
 327            return NtvPointer([])        
 328        idx = item_idx if item_idx else self.parent.ntv_value.index(self)
 329        num = index or (self.ntv_name == "" and self.parent.json_array)
 330        pointer = self.parent.pointer(index)
 331        pointer.append(idx if num else self.ntv_name)
 332        return pointer
 333         
 334    @property
 335    def code_ntv(self):
 336        '''return a string with the NTV code composed with 1 to 3 letters:
 337        - 'l' (NtvList), 's' (NtvSingle / json_value) or 'o' (NtvSingle / obj_value)
 338        - 'N' if ntv_name is present else none
 339        - 'T' if ntv_type is present else none'''
 340        dic = {'NtvList': 'l', 'NtvSingle': 's'}
 341        code = dic[self.__class__.__name__]
 342        if isinstance(self, NtvSingle) and not self.is_json:
 343            code = 'o'
 344        if self.ntv_name:
 345            code += 'N'
 346        if self.ntv_type and self.ntv_type.long_name != 'json':
 347            code += 'T'
 348        return code
 349
 350    @property
 351    def max_len(self):
 352        '''return the highest len of Ntv entity included'''
 353        maxi = len(self)
 354        if isinstance(self.ntv_value, (list, set)):
 355            maxi = max(maxi, max(ntv.max_len for ntv in self.ntv_value))
 356        return maxi
 357
 358    @property
 359    def name(self):
 360        '''return the ntv_name of the entity'''
 361        return self.ntv_name
 362
 363    @property
 364    def type_str(self):
 365        '''return a string with the value of the NtvType of the entity'''
 366        if not self.ntv_type:
 367            return ''
 368        return self.ntv_type.long_name
 369
 370    @property
 371    def val(self):
 372        '''return the ntv_value of the entity'''
 373        return self.ntv_value
 374
 375    def alike(self, ntv_value):
 376        ''' return a Ntv entity with same name and type.
 377
 378        *Parameters*
 379
 380        - **ntv_value**: list of ntv values'''
 381        return self.__class__(ntv_value, self.ntv_name, self.ntv_type)
 382
 383    def from_value(self):
 384        '''return a Ntv entity from ntv_value'''
 385        if isinstance(self.ntv_value, list):
 386            return NtvList(self.ntv_value)
 387        return Ntv.from_obj(self.ntv_value)
 388
 389    def json_name(self, def_type=None, string=False, explicit=False):
 390        '''return the JSON name of the NTV entity (json-ntv format)
 391
 392        *Parameters*
 393
 394        - **def_typ** : NtvType or Namespace (default None) - type of the parent entity
 395        - **string** : boolean (default False) - If True, return a string else a tuple
 396        - **explicit** : boolean (default False) - If True, type is always included'''
 397        if def_type is None:
 398            def_type = ''
 399        elif isinstance(def_type, (NtvType, Namespace)):
 400            def_type = def_type.long_name
 401        json_name = self.ntv_name if self.ntv_name else ''
 402        json_type = relative_type(
 403            def_type, self.type_str) if self.ntv_type else ''
 404        implicit = (json_type == 'json' and (not def_type or def_type == 'json') or
 405                    not NtvConnector.is_json_class(self.val))
 406        if implicit and not explicit:
 407            json_type = ''
 408        json_sep = self._obj_sep(json_type, def_type)
 409        if string:
 410            return json_name + json_sep + json_type
 411        return [json_name, json_sep, json_type]
 412
 413    def to_ntvsingle(self, name=None, typ=None, def_type=None, **kwargs):
 414        '''convert NtvList entity to NtvSingle entity
 415
 416        *Parameters*
 417
 418        - **ntv_name** : String (default None) - name of the NTV entity
 419        - **ntv_type**: String (default None) - type of the entity
 420        - **value**: value of the entity
 421        - **fast**: boolean (default False) - Ntv is created with a list of json values
 422        without control
 423        '''
 424        return NtvSingle(self.obj_value(def_type=def_type, **kwargs),
 425                         self.name if self.name else name,
 426                         self.type_str if self.type_str else typ)
 427    
 428    def to_ntvlist(self, def_type=None, def_sep=None, no_typ=False, decode_str=False,
 429                 typ_auto=False, fast=False):
 430        '''convert NtvSingle entity to NtvList entity
 431
 432        *Parameters*
 433
 434        - **value**: Ntv value to convert in an Ntv entity
 435        - **no_typ** : boolean (default None) - if True, NtvList is with 'json' type
 436        - **def_type** : NtvType or Namespace (default None) - default type of the value
 437        - **def_sep**: ':', '::' or None (default None) - default separator of the value
 438        - **decode_str**: boolean (default False) - if True, string are loaded as json data
 439        - **type_auto**: boolean (default False) - if True, default type for NtvList
 440        is the ntv_type of the first Ntv in the ntv_value
 441        - **fast** : boolean (default False) - if True, Ntv entity is created without conversion
 442        '''
 443        ntv = Ntv.from_obj(self.ntv_value, def_type, def_sep, no_typ, decode_str,
 444                     typ_auto, fast)
 445        if ntv.__class__.__name__ == 'NtvSingle':
 446            return NtvList([self])
 447        if self.ntv_name:
 448            ntv.set_name(self.ntv_name)
 449        return ntv
 450
 451    def notype(self):
 452        '''convert NTV entity in a NV entity (with ntv_type is 'json' or None')'''
 453        no_type = copy.copy(self)
 454        for ntv in NtvTree(no_type).leaf_nodes:
 455            ntv.set_type('json')           
 456        for ntv in NtvTree(no_type).inner_nodes:
 457            ntv.set_type()
 458        return no_type
 459
 460    def reduce(self, obj=True, maxi=6, level=3):
 461        '''reduce the length and the level of the entity
 462        
 463        *Parameters*
 464
 465        - **obj**: boolean (default True) - If True return jsonNTV else NTV entity
 466        - **maxi**: integer (default 6) - Number of returned entities in an NtvList
 467        - **level**: integer (default 6) - returned entities in an NtvList at this level is None
 468        
 469        *return*
 470        
 471        - **NTV entity** or **jsonNTV**
 472        '''
 473        ntv = copy.copy(self)
 474        cont = Ntv.obj('...') if self.json_array else Ntv.obj({'...':''})            
 475        if isinstance(self, NtvSingle):
 476            return ntv
 477        if level == 0:
 478            ntv.ntv_value = [NtvSingle('...',ntv_type=ntv.type_str)]
 479        if len(self) <= maxi:
 480            ntv.ntv_value = [child.reduce(False, maxi, level-1) for child in ntv]
 481            return ntv
 482        mid = maxi // 2
 483        cont.set_type(ntv.type_str)
 484        start = [child.reduce(False, maxi, level-1) for child in ntv[:mid]]
 485        #middle = [NtvSingle('...',ntv_type=ntv.type_str)]
 486        middle = [cont]
 487        end = [child.reduce(False, maxi, level-1) for child in ntv[-mid:]]
 488        ntv.ntv_value = start + middle + end
 489        if obj:
 490            return ntv.to_obj()
 491        return ntv
 492    
 493    def set_name(self, name='', nodes='simple'):
 494        '''set new names to the entity
 495
 496        *Parameters*
 497
 498        - **name**: list or string (default '') - New name values
 499        - **nodes**: string (default 'simple') - nodes to be changed
 500            'simple': current entity
 501            'leaves': NtvSingle entities
 502            'inner': NtvList entities
 503            'all': all entities  '''
 504        match nodes:
 505            case 'simple':
 506                self.ntv_name = str(name)
 507            case 'leaves':
 508                if not isinstance(name, list):
 509                    name = [str(name)] * NtvTree(self).breadth
 510                for nam, ntv in zip(name, NtvTree(self).leaf_nodes):
 511                    ntv.ntv_name = nam
 512            case 'inner':
 513                if not isinstance(name, list):
 514                    name = [str(name)] * len(NtvTree(self).inner_nodes)
 515                for nam, ntv in zip(name, NtvTree(self).inner_nodes):
 516                    ntv.ntv_name = nam
 517            case 'all':
 518                if not isinstance(name, list):
 519                    name = [str(name)] * NtvTree(self).size
 520                for nam, ntv in zip(name, NtvTree(self).nodes):
 521                    ntv.ntv_name = nam
 522            case _:
 523                raise NtvError('the nodes option is not valid')
 524
 525    def set_type(self, typ=None):
 526        '''set a new type to the entity
 527
 528        *Parameters*
 529
 530        - **typ**: string, NtvType, Namespace (default None)'''
 531        if typ and not isinstance(typ, (str, NtvType, Namespace)):
 532            raise NtvError('the type is not a valid type')
 533        self.ntv_type = str_type(typ, self.__class__.__name__ == 'NtvSingle')
 534
 535    def set_value(self, value=None, fast=False):
 536        '''set new ntv_value of a single entity or of a list of entities included
 537
 538        *Parameters*
 539
 540        - **value**: list or single value
 541        - **fast** : boolean (default False) - if True, value is not converted'''
 542        if isinstance(self, NtvSingle):
 543            self.ntv_value = NtvSingle(value, ntv_type=self.ntv_type, 
 544                                       fast=fast).val
 545            return
 546        if not isinstance(value, list):
 547            value = [value] * NtvTree(self).breadth
 548        ntv_val = NtvList(value, fast=fast)
 549        for val, ntv in zip(ntv_val, NtvTree(self).leaf_nodes):
 550            ntv.ntv_value = val.val
 551        return
 552
 553    def to_mermaid(self, title='', disp=False, row=False, leaves=False):
 554        '''return a mermaid flowchart.
 555
 556        *Parameters*
 557
 558        - **title**: String (default '') - title of the flowchart
 559        - **disp**: Boolean (default False) - if true, return a display else return
 560        a mermaid text diagram
 561        - **row**: Boolean (default False) - if True, add the node row
 562        - **leaves**: Boolean (default False) - if True, add the leaf row
 563        '''
 564        option = {'title': title, 'disp': disp, 'row': row, 'leaves': leaves}
 565        if disp:
 566            Ntv.obj({':$mermaid': self.to_obj()}).to_obj(
 567                format='obj', **option)
 568            return None
 569        return Ntv.obj({':$mermaid': self.to_obj()}).to_obj(format='obj', **option)
 570
 571    def expand(self, full=True):
 572        '''return a json representation of the triplet (name, type, value)'''
 573        if isinstance(self, NtvList) and full:
 574            return {'name': self.name, 'type': self.type_str, 
 575                    'value': [ntv.expand(full) for ntv in self.val]}
 576        if isinstance(self, NtvSingle) and full:
 577            return {'name': self.name, 'type': self.type_str, 'value': self.val}
 578        exp = {} if not self.name else {'name': self.name}
 579        if not self.type_str in ['json', ''] :
 580            exp['type'] = self.type_str
 581        if isinstance(self, NtvList):
 582            exp['value'] = [ntv.expand(full) for ntv in self.val]
 583        else:
 584            exp['value'] = self.val
 585        return exp
 586        
 587    def to_repr(self, nam=True, typ=True, val=True, jsn=False, maxi=10):
 588        '''return a simple json representation of the Ntv entity.
 589
 590        *Parameters*
 591
 592        - **nam**: Boolean(default True) - if true, the names are included
 593        - **typ**: Boolean(default True) - if true, the types are included
 594        - **val**: Boolean(default True) - if true, the values are included
 595        - **jsn**: Boolean(default False) - if false, the 'json' type is not included
 596        - **maxi**: Integer (default 10) - number of values to include for NtvList
 597        entities. If maxi < 1 all the values are included.
 598        '''
 599        ntv = self.code_ntv
 600        if nam and typ:
 601            ntv = ntv[0]
 602        if self.ntv_name and nam:
 603            ntv += '-' + self.ntv_name
 604        if self.ntv_type and typ and (jsn or self.ntv_type.long_name != 'json'):
 605            ntv += '-' + self.ntv_type.long_name
 606        clas = self.__class__.__name__
 607        clas_val = self.ntv_value.__class__.__name__
 608        if clas == 'NtvSingle' and clas_val != 'NtvSingle':
 609            if val:
 610                if ntv:
 611                    ntv += '-'
 612                ntv += json.dumps(self.ntv_value, cls=NtvJsonEncoder)
 613            return ntv
 614        if clas == 'NtvSingle' and clas_val == 'NtvSingle':
 615            return {ntv:  self.ntv_value.to_repr(nam, typ, val, jsn, maxi)}
 616        if clas == 'NtvList':
 617            maxv = len(self.ntv_value) if maxi < 1 else maxi
 618            return {ntv:  [ntvi.to_repr(nam, typ, val, jsn, maxi) 
 619                           for ntvi in self.ntv_value[:maxv]]}
 620        raise NtvError('the ntv entity is not consistent')
 621
 622    def to_name(self, default=''):
 623        '''return the name of the NTV entity
 624
 625        *Parameters*
 626
 627        - **default**: string (default ''): returned value if name is not present '''
 628        if self.ntv_name == '':
 629            return default
 630        return self.ntv_name
 631
 632    def to_fast(self, def_type=None, **kwargs):
 633        '''return the JSON representation of the NTV entity (json-ntv format)
 634        without value conversion.
 635
 636        *Parameters*
 637
 638        - **def_type** : NtvType or Namespace (default None) - default type to apply
 639        to the NTV entity
 640        - **encoded** : boolean (default False) - choice for return format
 641        (string/bytes if True, dict/list/tuple else)
 642        - **format**  : string (default 'json')- choice for return format
 643        (json, cbor, obj)
 644        - **simpleval** : boolean (default False) - if True, only value (without
 645        name and type) is included
 646        - **name** : boolean (default true) - if False, name is not included
 647        - **json_array** : boolean (default false) - if True, Json-object is not used for NtvList
 648        - **maxi**: Integer (default -1) - number of values to include for NtvList
 649        entities. If maxi < 1 all the values are included.
 650        '''
 651        option = kwargs | {'fast': True}
 652        return self.to_obj(def_type=def_type, **option)
 653
 654    def to_obj(self, def_type=None, **kwargs):
 655        '''return the JSON representation of the NTV entity (json-ntv format).
 656
 657        *Parameters*
 658
 659        - **def_type** : NtvType or Namespace (default None) - default type to apply
 660        to the NTV entity
 661        - **encoded** : boolean (default False) - choice for return format
 662        (string/bytes if True, dict/list/tuple else)
 663        - **format**  : string (default 'json')- choice for return format
 664        (json, cbor, obj)
 665        - **simpleval** : boolean (default False) - if True, only value (without
 666        name and type) is included
 667        - **name** : boolean (default true) - if False, name is not included
 668        - **json_array** : boolean (default false) - if True, Json-object is not used for NtvList
 669        - **fast** : boolean (default False) - if True, json is created without conversion
 670        - **maxi**: Integer (default -1) - number of values to include for NtvList
 671        entities. If maxi < 1 all the values are included.
 672        '''
 673        option = {'encoded': False, 'format': 'json', 'fast': False, 'maxi': -1,
 674                  'simpleval': False, 'name': True, 'json_array': False} | kwargs
 675        value = self.obj_value(def_type=def_type, **option)
 676        obj_name = self.json_name(def_type)
 677        if not option['name']:
 678            obj_name[0] = ''
 679        if option['simpleval']:
 680            name = ''
 681        elif option['format'] in ('cbor', 'obj') and not NtvConnector.is_json_class(value):
 682            name = obj_name[0]
 683        else:
 684            name = obj_name[0] + obj_name[1] + obj_name[2]
 685        json_obj = {name: value} if name else value
 686        if option['encoded'] and option['format'] == 'json':
 687            return json.dumps(json_obj, cls=NtvJsonEncoder)
 688        if option['encoded'] and option['format'] == 'cbor':
 689            return NtvConnector.connector()['CborConnec'].to_obj_ntv(json_obj)
 690        return json_obj
 691
 692    @staticmethod
 693    def obj_ntv(value, name='', typ='', single=False):
 694        '''return a json-ntv representation without using Ntv structure.
 695
 696        *Parameters*
 697
 698        - **value** : ntv-value of the json-ntv
 699        - **name** : string (default '') - ntv-name of the json-ntv
 700        - **typ** : string (default '') - ntv_type of the json-ntv
 701        - **single** : boolean (default False) - if True, value is a single object
 702        else value is a set of objetcs.
 703        '''
 704        value = {} if not value else value
 705        name = '' if not name else name
 706        typ = '' if not typ else typ
 707        ntv_list = len(value) != 1 if isinstance(
 708            value, dict) else isinstance(value, list)
 709        if not single and not ntv_list:
 710            raise NtvError('value is not compatible with not single NTV data')
 711        sep = ':' if single else '::'
 712        sep = '' if not typ and (not single or single and not ntv_list) else sep
 713        name += sep + typ
 714        return {name: value} if name else value
 715
 716    def to_json_ntv(self):
 717        ''' create a copy where ntv-value of the self-tree nodes is converted 
 718        in json-value'''
 719        ntv = copy.copy(self)
 720        for leaf in ntv.tree.leaf_nodes:
 721            if isinstance(leaf.ntv_value, (NtvSingle, NtvList)):
 722                leaf.ntv_value = leaf.ntv_value.to_obj()
 723                leaf.ntv_type = NtvType('ntv')
 724            elif not leaf.is_json:
 725                leaf.ntv_value, leaf.ntv_name, type_str = NtvConnector.cast(
 726                    leaf.ntv_value, leaf.ntv_name, leaf.type_str)
 727                leaf.ntv_type = NtvType.add(type_str)
 728                leaf.is_json = True
 729        return ntv
 730
 731    def to_obj_ntv(self, **kwargs):
 732        ''' create a copy where ntv-value of the self-tree nodes is converted 
 733        in object-value
 734
 735        *Parameters*
 736
 737        - **kwargs** : parameters used in NtvConnector class (specific for each Connector)'''
 738        ntv = copy.copy(self)
 739        for leaf in ntv.tree.leaf_nodes:
 740            if (leaf.is_json and leaf.type_str in set(NtvConnector.dic_type.values())
 741                    or leaf.ntv_type is None):
 742                leaf.ntv_value, leaf.ntv_name, type_str = NtvConnector.uncast(
 743                    leaf, **kwargs)
 744                leaf.ntv_type = NtvType.add(type_str) if type_str else None
 745                leaf.is_json = NtvConnector.is_json(leaf.ntv_value)
 746        return ntv
 747
 748    def to_tuple(self, maxi=10):
 749        '''return a nested tuple representation of the NTV entity
 750        (NtvList/NtvSingle, ntv_name, ntv_type, ntv_value).
 751
 752        *Parameters*
 753
 754        - **maxi**: Integer (default 10) - number of values to include for NtvList
 755        entities. If maxi < 1 all the values are included.
 756        '''
 757        clas = self.__class__.__name__
 758        val = self.ntv_value
 759        name = self.ntv_name
 760        typ = None
 761        if self.ntv_type:
 762            typ = self.ntv_type.long_name
 763        if isinstance(self, NtvSingle) and not isinstance(val, NtvSingle):
 764            return (clas, name, typ, val)
 765        if isinstance(self, NtvSingle) and isinstance(val, NtvSingle):
 766            return (clas, name, typ, val.to_tuple(maxi=maxi))
 767        if isinstance(self, NtvList):
 768            maxv = len(self.ntv_value) if maxi < 1 else maxi
 769            return (clas, name, typ, [ntv.to_tuple(maxi=maxi) for ntv in val[:maxv]])
 770        raise NtvError('the ntv entity is not consistent')
 771
 772    def remove(self, first=True, index=None):
 773        '''remove self from its parent entity.
 774        
 775        *parameters*
 776        
 777        - **first** : boolean (default True) - if True only the first instance
 778        else all
 779        - **index** : integer (default None) - index of self in its parent
 780        '''
 781        parent = self.parent
 782        if not parent:
 783            return
 784        idx = parent.ntv_value.index(self) if index is None else index
 785        if not parent[idx] == self:
 786            raise NtvError('the entity is not present at the index')
 787        del parent.ntv_value[idx]
 788        if not first and index is None:
 789            while self in parent:
 790                idx = parent.ntv_value.index(self)
 791                del parent.ntv_value[idx]                
 792        if not self in parent:
 793            self.parent = None
 794        return
 795            
 796    def replace(self, ntv):
 797        '''replace self by ntv in the tree'''
 798        parent = self.parent
 799        if parent:
 800            idx = parent.ntv_value.index(self)
 801            parent.insert(idx, ntv)
 802            del parent[idx+1]
 803            if not self in parent:
 804                self.parent=None
 805        else:
 806            self = ntv
 807
 808    @property
 809    def tree(self):
 810        '''return a tree with included entities (NtvTree object)'''
 811        return NtvTree(self)
 812
 813    @abstractmethod
 814    def obj_value(self):
 815        '''return the ntv_value with different formats defined by kwargs (abstract method)'''
 816
 817    @property
 818    @abstractmethod
 819    def json_array(self):
 820        ''' return the json_array dynamic attribute (abstract method)'''
 821
 822    @abstractmethod
 823    def _obj_sep(self, json_type, def_type):
 824        ''' return separator to include in json_name (abstract method)'''
 825
 826    @staticmethod
 827    def _from_value(value, decode_str=False):
 828        '''return a decoded value
 829
 830        *Parameters*
 831
 832        - **decode_str**: boolean (default False) - if True, string are loaded as json data
 833        '''
 834        if isinstance(value, bytes):
 835            value = Ntv.from_obj({'$cbor': value}).ntv_value
 836        elif decode_str and isinstance(value, str) and value.lstrip() and\
 837                value.lstrip()[0] in '"-{[0123456789tfn':
 838            try:
 839                value = json.loads(value)
 840            except json.JSONDecodeError:
 841                pass
 842        return value
 843
 844    @staticmethod
 845    def decode_json(json_value):
 846        '''return (value, name, type, separator, isjson) of a json object'''
 847        if isinstance(json_value, dict) and len(json_value) == 1:
 848            json_name = list(json_value.keys())[0]
 849            val = json_value[json_name]
 850            return (val, *NtvUtil.from_obj_name(json_name), NtvConnector.is_json(val))
 851        return (json_value, None, None, None, NtvConnector.is_json(json_value))
 852
 853    @staticmethod
 854    def _create_ntvlist(str_typ, def_type, sep, ntv_value, typ_auto, no_typ, ntv_name, fast):
 855        '''return a NtvList with parameters from Ntv.from_obj method'''
 856        def_type = agreg_type(str_typ, def_type, False)
 857        sep_val = ':' if sep and def_type else None
 858        if isinstance(ntv_value, dict):
 859            keys = list(ntv_value.keys())
 860            values = list(ntv_value.values())
 861            ntv_list = [Ntv.from_obj({key: val}, def_type, sep_val, fast=fast)
 862                        for key, val in zip(keys, values)]
 863        else:
 864            ntv_list = [Ntv.from_obj(val, def_type, sep_val, fast=fast)
 865                        for val in ntv_value]
 866        if typ_auto and not def_type and ntv_list:
 867            def_type = ntv_list[0].ntv_type
 868        def_type = 'json' if no_typ else def_type
 869        return NtvList(ntv_list, ntv_name, def_type, typ_auto, fast=fast)
 870
 871    @staticmethod
 872    def _listed(idx):
 873        '''transform a tuple of tuple object in a list of list object'''
 874        return [val if not isinstance(val, tuple) else Ntv._listed(val) for val in idx]
 875
 876
 877class NtvSingle(Ntv):
 878    ''' A NTV-single entity is a Ntv entity not composed with other entities.
 879
 880    *Attributes :*
 881    - no additional attributes to those of parent class `Ntv`
 882
 883    *dynamic values (@property)*
 884    - `json_array`
 885
 886    The additional methods defined in this class are :
 887
 888    *instance methods*
 889    - `obj_value`
 890    '''
 891
 892    def __init__(self, value, ntv_name=None, ntv_type=None, fast=False):
 893        '''NtvSingle constructor.
 894
 895        *Parameters*
 896
 897        - **ntv_name** : String (default None) - name of the NTV entity
 898        - **ntv_type**: String (default None) - type of the entity
 899        - **value**: value of the entity
 900        - **fast**: boolean (default False) - Ntv is created with a list of json values
 901        without control
 902        '''
 903        if not fast:
 904            value, ntv_name, ntv_type = NtvSingle._decode_s(
 905                value, ntv_name, ntv_type)
 906            if ntv_type and isinstance(ntv_type, str) and ntv_type[-1] == '.':
 907                raise NtvError('the ntv_type is not valid')
 908        super().__init__(value, ntv_name, ntv_type)
 909
 910    def __eq__(self, other):
 911        ''' equal if name type and value are equal'''
 912        return self.__class__.__name__ == other.__class__.__name__ and\
 913            self.ntv_name == other.ntv_name and self.ntv_type == other.ntv_type and\
 914            self.ntv_value == other.ntv_value
 915
 916    def __hash__(self):
 917        '''return hash(name) + hash(type) + hash(value)'''
 918        return hash(self.ntv_name) + hash(self.ntv_type) + \
 919            hash(json.dumps(self.ntv_value, cls=NtvJsonEncoder))
 920
 921    def __copy__(self):
 922        ''' Copy all the Ntv tree '''
 923        return self.__class__(copy.copy(self.ntv_value), self.ntv_name,
 924                              self.ntv_type, fast=True)
 925
 926    @property
 927    def json_array(self):
 928        ''' return the json_array dynamic attribute (always False)'''
 929        return False
 930
 931    def obj_value(self, def_type=None, **kwargs):
 932        '''return the ntv_value with different formats defined by kwargs'''
 933        option = {'encoded': False, 'format': 'json',
 934                  'simpleval': False, 'fast': False} | kwargs
 935        if option['fast'] or option['format'] in ('json', 'tuple'):
 936            return self.ntv_value
 937        if option['format'] == 'obj' and self.ntv_value == 'null':
 938            return None
 939        return NtvConnector.uncast(self, **option)[0]
 940
 941    def _obj_sep(self, json_type, def_type=None):
 942        ''' return separator to include in json_name'''
 943        if json_type or not def_type and \
 944            (isinstance(self.ntv_value, list) or
 945             isinstance(self.ntv_value, dict) and len(self.ntv_value) != 1):
 946            return ':'
 947        return ''
 948
 949    @staticmethod
 950    def _decode_s(ntv_value, ntv_name, ntv_type):
 951        '''return adjusted ntv_value, ntv_name, ntv_type'''
 952        is_json = NtvConnector.is_json(ntv_value)
 953        if is_json:
 954            if isinstance(ntv_value, (list)):
 955                ntv_value = [NtvSingle._decode_s(val, '', ntv_type)[
 956                    0] for val in ntv_value]
 957            elif isinstance(ntv_value, (dict)):
 958                ntv_value = {key: NtvSingle._decode_s(val, '', ntv_type)[
 959                    0] for key, val in ntv_value.items()}
 960        elif isinstance(ntv_value, NtvSingle):
 961            ntv_value = ntv_value.to_obj()
 962            return (ntv_value, ntv_name, 'ntv')
 963        else:
 964            ntv_value, name, typ = NtvConnector.cast(ntv_value, ntv_name)  
 965            ntv_type = NtvType(typ) if typ else ntv_type
 966        if not ntv_type:
 967            if is_json:
 968                ntv_type = 'json'
 969            else:
 970                ntv_type = typ
 971                if not ntv_name:
 972                    ntv_name = name
 973        elif not is_json and NtvType(ntv_type) != NtvType(typ):
 974            raise NtvError('ntv_value is not compatible with ntv_type')
 975        return (ntv_value, ntv_name, ntv_type)
 976
 977
 978class NtvList(Ntv):
 979    '''A NTV-list entity is a Ntv entity where:
 980
 981    - ntv_value is a list of NTV entities,
 982    - ntv_type is a default type available for included NTV entities
 983
 984    *Attributes :*
 985    - no additional attributes to those of parent class `Ntv`
 986
 987    *dynamic values (@property)*
 988    - `json_array`
 989
 990    The additional methods defined in this class are :
 991
 992    *instance methods*
 993    - `obj_value`
 994    '''
 995
 996    def __init__(self, list_ntv, ntv_name=None, ntv_type=None, typ_auto=False, fast=False):
 997        '''NtvList constructor.
 998
 999        *Parameters*
1000
1001        - **ntv_name** : String (default None) - name of the NTV entity
1002        - **ntv_type**: String (default None) - default type or namespace of
1003        the included entities
1004        - **list_ntv**: list - list of Ntv objects or obj_value of Ntv objects
1005        - **fast**: boolean (default False) - if True, Ntv is created with a list
1006        of json values without control
1007        - **type_auto**: boolean (default False) - if True, default type for NtvList
1008        is the ntv_type of the first Ntv in the ntv_value'''
1009        if isinstance(list_ntv, NtvList):
1010            ntv_value = [copy.copy(ntv) for ntv in list_ntv.ntv_value]
1011            ntv_type = list_ntv.ntv_type
1012            ntv_name = list_ntv.ntv_name
1013        elif isinstance(list_ntv, list):
1014            ntv_value = [Ntv.from_obj(ntv, ntv_type, ':', fast=fast)
1015                         for ntv in list_ntv]
1016        elif isinstance(list_ntv, dict):
1017            ntv_value = [Ntv.from_obj({key: val}, ntv_type, ':', fast=fast)
1018                         for key, val in list_ntv.items()]
1019        else:
1020            raise NtvError('ntv_value is not a list')
1021        if typ_auto and not ntv_type and len(ntv_value) > 0 and ntv_value[0].ntv_type:
1022            ntv_type = ntv_value[0].ntv_type
1023        super().__init__(ntv_value, ntv_name, ntv_type)
1024        for ntv in self:
1025            ntv.parent = self
1026
1027    @property
1028    def json_array(self):
1029        ''' return the json_array dynamic attribute'''
1030        set_name = {ntv.ntv_name for ntv in self}
1031        return '' in set_name or len(set_name) != len(self) or len(set_name)==1
1032
1033    def __eq__(self, other):
1034        ''' equal if name and value are equal'''
1035        return self.__class__.__name__ == other.__class__.__name__ and\
1036            self.ntv_name == other.ntv_name and self.ntv_value == other.ntv_value
1037
1038    def __hash__(self):
1039        '''return hash(name) + hash(value)'''
1040        return hash(self.ntv_name) + hash(tuple(self.ntv_value))
1041
1042    def __copy__(self):
1043        ''' Copy all the data '''
1044        cop = self.__class__(self)
1045        cop.parent = None
1046        return cop
1047
1048    def __setitem__(self, ind, value):
1049        ''' replace ntv_value item at the `ind` row with `value`'''
1050        if ind < 0 or ind >= len(self):
1051            raise NtvError("out of bounds")
1052        self.ntv_value[ind] = value
1053        if isinstance(value, (NtvSingle, NtvList)):
1054            value.parent = self
1055
1056    def __delitem__(self, ind):
1057        '''remove ntv_value item at the `ind` row'''
1058        if isinstance(ind, int):
1059            self.ntv_value.pop(ind)
1060        else:            
1061            self.ntv_value.pop(self.ntv_value.index(self[ind]))
1062
1063    def append(self, ntv):
1064        ''' add ntv at the end of the list of Ntv entities included'''
1065        old_parent = ntv.parent
1066        if old_parent:
1067            del(old_parent[old_parent.ntv_value.index(ntv)])
1068        self.ntv_value.append(ntv)
1069        ntv.parent = self
1070
1071    def insert(self, idx, ntv):
1072        ''' add ntv at the index idx of the list of Ntv entities included'''
1073        old_parent = ntv.parent
1074        if old_parent:
1075            del(old_parent[old_parent.ntv_value.index(ntv)])
1076        self.ntv_value.insert(idx, ntv)
1077        ntv.parent = self      
1078        
1079    def _obj_sep(self, json_type, def_type=None):
1080        ''' return separator to include in json_name'''
1081        if json_type or (len(self.ntv_value) == 1 and not self.json_array):
1082            return '::'
1083        return ''
1084
1085    def obj_value(self, def_type=None, **kwargs):
1086        '''return the ntv_value with different formats defined by kwargs
1087        '''
1088        option = {'encoded': False, 'format': 'json', 'simpleval': False,
1089                  'json_array': False, 'fast': False, 'maxi': -1} | kwargs
1090        opt2 = option | {'encoded': False}
1091        maxv = len(self.ntv_value) if option['maxi'] < 1 else option['maxi']
1092        def_type = self.ntv_type.long_name if self.ntv_type else def_type
1093        if self.json_array or option['simpleval'] or option['json_array']:
1094            return [ntv.to_obj(def_type=def_type, **opt2) for ntv in self.ntv_value[:maxv]]
1095        values = [ntv.to_obj(def_type=def_type, **opt2)
1096                  for ntv in self.ntv_value[:maxv]]
1097        return {list(val.items())[0][0]: list(val.items())[0][1] for val in values}