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