NTV.json_ntv.namespace

  1# -*- coding: utf-8 -*-
  2"""
  3@author: Philippe@loco-labs.io
  4
  5The `namespace` module is part of the `NTV.json_ntv` package ([specification document](
  6https://loco-philippe.github.io/ES/JSON%20semantic%20format%20(JSON-NTV).htm)).
  7
  8It contains the `Namespace`, `Datatype`, `DatatypeError` classes and
  9the functions `agreg_type`, `from_file`, `mapping`, `relative_type` and `str_type`.
 10
 11Namespace and Datatype entities are used to define NTVtype.
 12
 13For more information, see the
 14[user guide](https://loco-philippe.github.io/NTV/documentation/user_guide.html)
 15or the [github repository](https://github.com/loco-philippe/NTV).
 16
 17"""
 18import configparser
 19from pathlib import Path
 20import json
 21import requests
 22
 23import json_ntv
 24from json_ntv.ntv_util import NtvUtil
 25from json_ntv.ntv_validate import Validator
 26
 27SCH_ORG = 'https://schema.org/'
 28
 29
 30def agreg_type(str_typ, def_type, single):
 31    '''aggregate str_typ and def_type to return an Datatype or a Namespace if not single
 32
 33    *Parameters*
 34
 35        - **str_typ** : Datatype or String (long_name) - Datatype to aggregate
 36        - **def_typ** : Datatype or String (long_name) - default Datatype or Namespace
 37        - **single** : Boolean - Ntv entity concerned (True if NtvSingle)'''
 38    if isinstance(str_typ, Datatype):
 39        str_typ = str_typ.long_name
 40    def_type = str_type(def_type, single)
 41    if not str_typ and (not single or isinstance(def_type, Datatype)):
 42        return def_type
 43    if not str_typ:
 44        return Datatype('json')
 45    clas = Namespace if str_typ[-1] == '.' else Datatype
 46    if not def_type:
 47        return clas.add(str_typ)
 48    if clas == Datatype or clas == Namespace and not single:
 49        try:
 50            return clas.add(str_typ)
 51        except DatatypeError:
 52            for typ in _join_type(def_type.long_name, str_typ):
 53                try:
 54                    return clas.add(typ)
 55                except DatatypeError:
 56                    pass
 57    raise DatatypeError(str_typ + ' and ' +
 58                        def_type.long_name + ' are incompatible')
 59
 60
 61def from_file(file, name, long_parent=None):
 62    '''create a set of Datatype and Namespace associated to a custom Namespace
 63
 64    *Parameters*
 65
 66        - **file** : .ini file - description of the Datatype and Namespace
 67        - **name** : string - name of the root custom Namespace
 68        - **long_parent** : longname of the parent Namespace of the root Namespace
 69    '''
 70    long_parent = '' if not long_parent else long_parent
 71    if name[0] != '$':
 72        raise DatatypeError(name + ' is not a custom Datatype')
 73    if long_parent not in Namespace.namespaces():
 74        raise DatatypeError(long_parent + ' is not a valid Datatype')
 75    schema_nsp = Namespace(name, long_parent)
 76    config = configparser.ConfigParser()
 77    config.read(file)
 78    if name not in config.sections():
 79        raise DatatypeError(name + ' is not present in ' + str(file))
 80    _add_namespace(config, schema_nsp)
 81
 82
 83def mapping(typ=None, func=None):
 84    '''Affect a validate function (func) to a Datatype (typ) '''
 85    if typ and func:
 86        Datatype(typ).validate = func
 87    else:
 88        if isinstance(typ, str):
 89            func_lis = [typ + '_valid']
 90        elif isinstance(typ, (list, tuple)):
 91            func_lis = [typ_str + '_valid' for typ_str in typ]
 92        else:
 93            func_lis = [typ_str + '_valid' for typ_str in Datatype._types_]
 94        for func_str in func_lis:
 95            if func_str in Validator.__dict__:
 96                Datatype(func_str[:-6]).validate = Validator.__dict__[func_str]
 97
 98
 99def relative_type(str_def, str_typ):
100    '''return relative str_typ string from Datatype or Namespace str_def
101
102    *Parameters*
103
104        - **str_def** : String - long_name of the Namespace or Datatype
105        - **str_type** : String - long_name of Ntvtype to be relative '''
106    if not str_def and not str_typ:
107        return ''
108    if str_def == str_typ:
109        return ''
110    if not str_def or str_def not in str_typ:
111        return str_typ
112    if not str_typ and str_def[-1] != ".":
113        return str_def
114    str_def_split = str_def.split('.')[:-1]
115    str_typ_split = str_typ.split('.')
116    ind = 0
117    for ind, name in enumerate(str_typ_split):
118        if name not in str_def_split:
119            break
120    return '.'.join(str_typ_split[ind:])
121
122
123def str_type(long_name, single):
124    ''' create a Datatype or a Namespace from a string
125
126    *Parameters*
127
128        - **long_name** : String - name of the Namespace or Datatype
129        - **single** : Boolean - If True, default type is 'json', else None'''
130    if not long_name and single:
131        return Datatype('json')
132    if not long_name and not single:
133        return None
134    if long_name.__class__.__name__ in ['Datatype', 'Namespace']:
135        return long_name
136    if not isinstance(long_name, str):
137        raise DatatypeError('the long_name is not a string')
138    if long_name[-1] == '.':
139        return Namespace.add(long_name)
140    return Datatype(long_name)
141
142
143def _add_namespace(config, namesp):
144    '''create the child Namespace and the child Datatype of the parent namespace'''
145    if namesp.name in config.sections():
146        confname = config[namesp.name]
147        if 'namespace' in confname:
148            for nspname in json.loads(confname['namespace']):
149                nsp = Namespace(nspname, namesp, force=True)
150                _add_namespace(config, nsp)
151        if 'type' in confname:
152            for typ in json.loads(confname['type']):
153                Datatype(typ, namesp, force=True)
154
155
156def _join_type(namesp, str_typ):
157    '''join Namespace string and Datatype or Namespace string'''
158    namesp_sp = namesp.split('.')
159    str_typ_sp = str_typ.split('.')
160    idx = -1
161    if str_typ_sp[0] in namesp_sp:
162        idx = namesp_sp.index(str_typ_sp[0])
163        if namesp_sp[idx:] != str_typ_sp[:len(namesp_sp[idx:])]:
164            idx = -1
165    if idx > -1:
166        namesp_sp = namesp_sp[:idx]
167    return ['.'.join(namesp_sp[:i+1]+str_typ_sp) for i in range(len(namesp_sp)-1, -1, -1)]
168
169
170def _isin_schemaorg(name, prop=True, typ=None):
171    ''' return True if a schema.org Property is present and associated to a Type
172    or if a schema.org Type is present'''
173    n_org = name if prop else name[:-1]
174    t_org = typ[:-1] if typ else None
175    req_name = requests.get(
176        SCH_ORG + n_org, allow_redirects=True, timeout=10).content.decode()
177    if not prop:
178        return 'Type</ti' in req_name
179    is_prop = 'Property</ti' in req_name
180    if not t_org:
181        return is_prop
182    if is_prop:
183        return '/' + n_org in requests.get(SCH_ORG + t_org, allow_redirects=True,
184                                           timeout=10).content.decode()
185    return False
186
187
188class TypeBase(NtvUtil):
189    ''' type of NTV entities.
190
191    *Attributes :*
192
193    - **name** : String - name of the type
194    - **nspace** : Namespace - namespace associated
195    - **custom** : boolean - True if not referenced
196    - **validate** : function (default None) - validate function
197
198    The methods defined in this class are :
199
200    *staticmethods*
201    - `types`
202    - `add`
203
204    *dynamic values (@property)*
205    - `category`
206    - `json_type`
207    - `gen_type`
208    - `long_name`
209
210    *instance methods*
211    - `isin_namespace`
212    '''
213
214    @staticmethod
215    def types():
216        '''return the list of TypeBase created'''
217        return [nam.long_name for nam in NtvUtil._types_.values()]
218
219    @classmethod
220    def add(cls, long_name, module=False, force=False, validate=None):
221        '''activate and return a valid TypeBase defined by the long name
222
223        *parameters :*
224
225        - **long_name** : String - absolut name of the TypeBase
226        - **module** : boolean (default False) - if True search data in the
227        local .ini file, else in the distant repository
228        - **validate** : function (default None) - validate function to include
229        '''
230        if long_name == '':
231            return None
232        if long_name in cls.types():
233            return NtvUtil._types_[long_name]
234        split_name = long_name.rsplit('.', 1)
235        if split_name[-1] == '':
236            raise DatatypeError(long_name + ' is not a valid TypeBase')
237        if len(split_name) == 1:
238            return cls(split_name[0], force=force, validate=validate)
239        if len(split_name) == 2:
240            nspace = Namespace.add(
241                split_name[0]+'.', module=module, force=force)
242            return cls(split_name[1], nspace, force=force)
243        raise DatatypeError(long_name + ' is not a valid TypeBase')
244
245    def __init__(self, name, nspace=None, force=False, validate=None):
246        '''TypeBase constructor.
247
248        *Parameters*
249
250        - **name** : string - name of the Type
251        - **nspace** : Namespace (default None) - namespace associated
252        - **force** : boolean (default False) - if True, no Namespace control
253        - **validate** : function (default None) - validate function to include'''
254        if isinstance(name, TypeBase):
255            self.name = name.name
256            self.nspace = name.nspace
257            self.custom = name.custom
258            self.validate = name.validate
259            # self.gen_type = name.gen_type
260            # self.long_name = name.long_name
261            return
262        if not name or not isinstance(name, str):
263            raise DatatypeError('null name is not allowed')
264        if not name and not nspace:
265            name = 'json'
266        if not nspace:
267            nspace = NtvUtil._namespaces_['']
268        if nspace.file and SCH_ORG in nspace.file:
269            if not _isin_schemaorg(name, typ=nspace.name):
270                raise DatatypeError(name +
271                                    ' is not a schema.org Property associated to the ' +
272                                    nspace.name + 'Type ')
273        else:
274            if not (name[0] == '$' or force or name in nspace.content['type']):
275                raise DatatypeError(
276                    name + ' is not defined in ' + nspace.long_name)
277        self.name = name
278        self.nspace = nspace
279        self.custom = nspace.custom or name[0] == '$'
280        # self.gen_type = '' if self.custom else self.nspace.content['type'][self.name]
281        # self.long_name = self.nspace.long_name + self.name
282        if validate:
283            self.validate = validate
284        NtvUtil._types_[self.long_name] = self
285        return
286
287    def __eq__(self, other):
288        ''' equal if name and nspace are equal'''
289        if self is None and other is None:
290            return True
291        if self is None or other is None:
292            return False
293        if self.__class__.__name__ != other.__class__.__name__:
294            return False
295        return self.name == other.name and self.nspace == other.nspace
296
297    def __hash__(self):
298        '''return hash(name) + hash(nspace)'''
299        return hash(self.name) + hash(self.nspace)
300
301    def __str__(self):
302        '''return string format'''
303        return self.long_name
304
305    def __repr__(self):
306        '''return classname and long name'''
307        return self.__class__.__name__ + '(' + self.long_name + ')'
308
309    @property
310    def json_type(self):
311        '''return the json type of the TypeBase'''
312        if self.custom:
313            return ''
314        prop = self.nspace.content['type'][self.name]
315        if isinstance(prop, list):
316            return prop[1]
317        return 'json'
318
319    @property
320    def category(self):
321        '''return the category of the TypeBase'''
322        if self.custom:
323            return ''
324        prop = self.nspace.content['type'][self.name]
325        if isinstance(prop, list):
326            return prop[2]
327        return 'local'
328
329    @property
330    def gen_type(self):
331        '''return the generic type of the TypeBase'''
332        if self.custom:
333            return ''
334        prop = self.nspace.content['type'][self.name]
335        if isinstance(prop, list):
336            return prop[0]
337        return prop
338
339    @property
340    def long_name(self):
341        '''return a string with the absolute name'''
342        return self.nspace.long_name + self.name
343
344    def isin_namespace(self, long_name):
345        '''return the number of level between self and nspace, -1 if None'''
346        return self.nspace.is_child(Namespace.add(long_name))
347
348
349class Datatype(TypeBase):
350    ''' The Datatype of NTV entities is composed with a TypeBase and an optional
351    extension.
352
353    *Attributes :*
354
355    - **name** : String - name of the Datatype
356    - **base_name** : String - name of the TypeBase
357    - **nspace** : Namespace - namespace associated
358    - **custom** : boolean - True if not referenced
359    - **validate** : function (default None) - validate function
360    - **typebase** : TypeBase - TypeBase of the Datatype
361    - **extension** : String (default None) - extension of the TypeBase
362
363    The methods defined in this class are :
364
365    *classmethod*
366    - `add`
367
368    *dynamic values (@property)*
369    - `category`
370    - `json_type`
371    - `gen_type`
372    - `long_name` (TypeBase)
373
374    *staticmethods*
375    - `types` (TypeBase)
376
377    *instance methods*
378    - `isin_namespace` (TypeBase)
379    - `validate` (TypeBase)
380    '''
381
382    def __init__(self, full_name, module=False, force=False, validate=None):
383        '''DataType constructor.
384
385        *Parameters*
386
387        - **full_name** : String - absolut name of the Datatype
388        - **module** : boolean (default False) - if True search data in the
389        local .ini file, else in the distant repository
390        - **force** : boolean (default False) - if True, no Namespace control
391        - **validate** : function (default None) - validate function to include'''
392        if isinstance(full_name, Datatype):
393            self.name = full_name.name
394            self.base_name = full_name.base_name
395            self.typebase = full_name.typebase
396            self.extension = full_name.extension
397            return
398        spl_name = full_name.split('[', maxsplit=1)
399        long_base = spl_name[0]
400        self.extension = spl_name[1][:-1] if len(spl_name) == 2 else None
401        self.typebase = TypeBase.add(long_base, module, force, validate)
402        ext_str = '[' + self.extension + ']' if self.extension else ''
403        self.base_name = self.typebase.name
404        self.name = self.typebase.name + ext_str
405        return
406
407    @property
408    def gen_type(self):
409        '''return the generic type of the Datatype'''
410        return self.typebase.gen_type
411
412    @property
413    def json_type(self):
414        '''return the json type of the Datatype'''
415        return self.typebase.json_type
416
417    @property
418    def category(self):
419        '''return the category of the Datatype'''
420        return self.typebase.category
421
422    @property
423    def nspace(self):
424        '''return the nspace of the Datatype'''
425        return self.typebase.nspace
426
427    @property
428    def custom(self):
429        '''return the custom of the Datatype'''
430        return self.typebase.custom
431
432    @property
433    def validate(self):
434        '''return the validate of the Datatype'''
435        return self.typebase.validate
436
437    @classmethod
438    def add(cls, long_name, module=False, force=False, validate=None):
439        '''method eqivalent to the constructor'''
440        return cls(long_name, module, force, validate)
441
442
443class Namespace(NtvUtil):
444    ''' Namespace of NTV entities.
445
446    *Attributes :*
447
448    - **name** : String - name of the namespace
449    - **file** : string - location of the file init
450    - **content** : dict - {'type': <list of ntv_type names>,
451                            'namespace': <list of namespace names>}
452    - **parent** : Namespace - parent namespace
453    - **custom** : boolean - True if not referenced
454
455    The methods defined in this class are :
456
457    *staticmethods*
458    - `namespaces`
459
460    *classmethods*
461    - `add`
462
463    *dynamic values (@property)*
464    - `long_name`
465
466    *instance methods*
467    - `is_child`
468    - `is_parent`
469    '''
470    _pathconfig_ = 'https://raw.githubusercontent.com/loco-philippe/NTV/master/json_ntv/config/'
471    _global_ = "NTV_global_namespace.ini"
472
473    @staticmethod
474    def namespaces():
475        '''return the list of Namespace created'''
476        return [nam.long_name for nam in NtvUtil._namespaces_.values()]
477
478    @classmethod
479    def add(cls, long_name, module=False, force=False):
480        '''activate and return a valid Namespace defined by the long_name.
481
482        *parameters :*
483
484        - **long_name** : String - absolut name of the Namespace
485        - **module** : boolean (default False) - if True search data in the
486        local .ini file, else in the distant repository
487        '''
488        if long_name in Namespace.namespaces():
489            return NtvUtil._namespaces_[long_name]
490        split_name = long_name.rsplit('.', 2)
491        if len(split_name) == 1 or split_name[-1] != '':
492            raise DatatypeError(long_name + ' is not a valid Namespace')
493        if len(split_name) == 2:
494            return cls(split_name[0]+'.', module=module, force=force)
495        if len(split_name) == 3:
496            parent = Namespace.add(split_name[0]+'.', force=force)
497            return cls(split_name[1]+'.', parent, module=module, force=force)
498        raise DatatypeError(long_name + ' is not a valid Namespace')
499
500    def __init__(self, name='', parent=None, module=False, force=False):
501        '''
502        Namespace constructor.
503
504        *Parameters*
505
506        - **name** : String - name of the namespace
507        - **parent** : Namespace - parent namespace
508        - **module** : boolean (default False) - if True search data in the
509                        local .ini file, else in the distant repository
510        - **content** : dict : {'type': <list of ntv_type names>,
511                                'namespace': <list of namespace names>}
512        '''
513        if name and not parent:
514            parent = NtvUtil._namespaces_['']
515        if parent and parent.file and SCH_ORG in parent.file:
516            if not _isin_schemaorg(name, False):
517                raise DatatypeError(name + ' is not a schema.org Type ')
518        else:
519            if name and not (name[0] == '$' or force or name in parent.content['namespace']):
520                raise DatatypeError(
521                    name + ' is not defined in ' + parent.long_name)
522        self.name = name
523        self.parent = parent
524        self.custom = parent.custom or name[0] == '$' if parent else False
525        self.file = Namespace._file(
526            self.parent, self.name, self.custom, module)
527        self.content = Namespace._content(
528            self.file, self.name, self.custom, module)
529        NtvUtil._namespaces_[self.long_name] = self
530
531    def __eq__(self, other):
532        ''' equal if name and parent are equal'''
533        if self is None and other is None:
534            return True
535        if self is None or other is None:
536            return False
537        if self.__class__.__name__ != other.__class__.__name__:
538            return False
539        return self.name == other.name and self.parent == other.parent
540
541    def __hash__(self):
542        '''return hash(name) + hash(parent)'''
543        return hash(self.name) + hash(self.parent)
544
545    def __str__(self):
546        '''return string format'''
547        return self.long_name
548
549    def __repr__(self):
550        '''return classname and long name'''
551        return self.__class__.__name__ + '(' + self.long_name + ')'
552
553    @staticmethod
554    def _file(parent, name, custom, module):
555        '''return the file name of the Namespace configuration
556
557        *parameters :*
558
559        - **parent** : Namespace - Parent of the Namespace
560        - **name** : String - name of the Namespace
561        - **custom** : boolean - if True, return None (custom Namespace)
562        - **module** : boolean (default False) - if True search data in the
563        local .ini file, else in the distant repository
564        '''
565        if custom:
566            return None
567        if parent:
568            if 'schema.org' in parent.file or name == 'org.':
569                return SCH_ORG
570            config = configparser.ConfigParser()
571            if module:
572                p_file = Path(parent.file).stem + Path(parent.file).suffix
573                config.read(Path(json_ntv.__file__).parent / 'config' / p_file)
574            else:
575                config.read_string(requests.get(
576                    parent.file, allow_redirects=True, timeout=10).content.decode())
577            return Namespace._pathconfig_ + json.loads(config['data']['namespace'])[name]
578        return Namespace._pathconfig_ + Namespace._global_
579
580    @staticmethod
581    def _content(file, name, custom, module):
582        '''return the content of the Namespace configuration
583
584        *parameters :*
585
586        - **file** : string - file name of the parent Namespace
587        - **name** : string - name of the Namespace
588        - **custom** : boolean - if True, return empty dict (custom Namespace)
589        - **module** : boolean (default False) - if True search data in the
590        local .ini file, else in the distant repository
591
592        *return :*
593
594        - dict : {'type': <list of ntv_type names>,
595                  'namespace': <list of namespace names>}
596        '''
597        if custom or 'schema.org' in file:
598            return {'type': {}, 'namespace': {}}
599        config = configparser.ConfigParser()
600        if module:
601            p_file = Path(file).stem + Path(file).suffix
602            config.read(Path(json_ntv.__file__).parent / 'config' / p_file)
603        else:
604            config.read_string(requests.get(
605                file, allow_redirects=True, timeout=10).content.decode())
606        config_name = config['data']['name']
607        if config_name != name:
608            raise DatatypeError(file + ' is not correct')
609        return {'type': json.loads(config['data']['type']),
610                'namespace': json.loads(config['data']['namespace'])}
611
612    @property
613    def long_name(self):
614        '''return a string with the absolute name'''
615        if self.parent is None or self.parent.name == '':
616            return self.name
617        return self.parent.long_name + self.name
618
619    def is_child(self, nspace):
620        '''return the number of level between self and nspace, -1 if None'''
621        parent = self.parent
622        if self == nspace:
623            return 0
624        if not self.name:
625            return -1
626        rang = 1
627        while parent.name != '' and parent != nspace:
628            rang += 1
629            parent = parent.parent
630        if parent == nspace:
631            return rang
632        return -1
633
634    def is_parent(self, nspace):
635        '''return the number of level between self and nspace, -1 if None'''
636        return nspace.is_child(self)
637
638
639class DatatypeError(Exception):
640    ''' Datatype or Namespace Exception'''
641
642
643nroot = Namespace(module=True)
644for root_typ in nroot.content['type']:
645    # typ = Datatype(root_typ, module=True,
646    Datatype(root_typ, module=True,
647             validate=Validator.__dict__[root_typ + '_valid'])
648# mapping(Datatype.types())
649typ_json = Datatype('json')