Source code

Download source archive ↓

src/rdflib/plugins/shared/jsonld/context.py

1"""
2Implementation of the JSON-LD Context structure. See: http://json-ld.org/
3"""
4
5# https://github.com/RDFLib/rdflib-jsonld/blob/feature/json-ld-1.1/rdflib_jsonld/context.py
6from __future__ import annotations
7
8from collections import namedtuple
9from typing import (
10    TYPE_CHECKING,
11    Any,
12    Collection,
13    Dict,
14    Generator,
15    List,
16    Optional,
17    Set,
18    Tuple,
19    Union,
20)
21from urllib.parse import urljoin, urlsplit
22
23from rdflib.namespace import RDF
24
25from .errors import (
26    INVALID_CONTEXT_ENTRY,
27    INVALID_REMOTE_CONTEXT,
28    RECURSIVE_CONTEXT_INCLUSION,
29)
30from .keys import (
31    BASE,
32    CONTAINER,
33    CONTEXT,
34    GRAPH,
35    ID,
36    IMPORT,
37    INCLUDED,
38    INDEX,
39    JSON,
40    LANG,
41    LIST,
42    NEST,
43    NONE,
44    PREFIX,
45    PROPAGATE,
46    PROTECTED,
47    REV,
48    SET,
49    TYPE,
50    VALUE,
51    VERSION,
52    VOCAB,
53)
54from .util import norm_url, source_to_json, split_iri
55
56NODE_KEYS = {GRAPH, ID, INCLUDED, JSON, LIST, NEST, NONE, REV, SET, TYPE, VALUE, LANG}
57
58
59class Defined(int):
60    pass
61
62
63UNDEF = Defined(0)
64
65# From <https://tools.ietf.org/html/rfc3986#section-2.2>
66URI_GEN_DELIMS = (":", "/", "?", "#", "[", "]", "@")
67
68_ContextSourceType = Union[
69    List[Union[Dict[str, Any], str, None]], Dict[str, Any], str, None
70]
71
72
73class Context:
74    def __init__(
75        self,
76        source: _ContextSourceType = None,
77        base: Optional[str] = None,
78        version: Optional[float] = 1.1,
79    ):
80        self.version: float = version or 1.1
81        self.language = None
82        self.vocab: Optional[str] = None
83        self._base: Optional[str]
84        self.base = base
85        self.doc_base = base
86        self.terms: Dict[str, Any] = {}
87        # _alias maps NODE_KEY to list of aliases
88        self._alias: Dict[str, List[str]] = {}
89        self._lookup: Dict[Tuple[str, Any, Union[Defined, str], bool], Term] = {}
90        self._prefixes: Dict[str, Any] = {}
91        self.active = False
92        self.parent: Optional[Context] = None
93        self.propagate = True
94        self._context_cache: Dict[str, Any] = {}
95        if source:
96            self.load(source)
97
98    @property
99    def base(self) -> Optional[str]:
100        return self._base
101
102    @base.setter
103    def base(self, base: Optional[str]):
104        if base:
105            hash_index = base.find("#")
106            if hash_index > -1:
107                base = base[0:hash_index]
108        self._base = (
109            self.resolve_iri(base)
110            if (hasattr(self, "_base") and base is not None)
111            else base
112        )
113        self._basedomain = "%s://%s" % urlsplit(base)[0:2] if base else None
114
115    def subcontext(self, source: Any, propagate: bool = True) -> Context:
116        # IMPROVE: to optimize, implement SubContext with parent fallback support
117        parent = self.parent if self.propagate is False else self
118        # type error: Item "None" of "Optional[Context]" has no attribute "_subcontext"
119        return parent._subcontext(source, propagate)  # type: ignore[union-attr]
120
121    def _subcontext(self, source: Any, propagate: bool) -> Context:
122        ctx = Context(version=self.version)
123        ctx.propagate = propagate
124        ctx.parent = self
125        ctx.language = self.language
126        ctx.vocab = self.vocab
127        ctx.base = self.base
128        ctx.doc_base = self.doc_base
129        ctx._alias = {k: l[:] for k, l in self._alias.items()}  # noqa: E741
130        ctx.terms = self.terms.copy()
131        ctx._lookup = self._lookup.copy()
132        ctx._prefixes = self._prefixes.copy()
133        ctx._context_cache = self._context_cache
134        ctx.load(source)
135        return ctx
136
137    def _clear(self) -> None:
138        self.language = None
139        self.vocab = None
140        self.terms = {}
141        self._alias = {}
142        self._lookup = {}
143        self._prefixes = {}
144        self.active = False
145        self.propagate = True
146
147    def get_context_for_term(self, term: Optional[Term]) -> Context:
148        if term and term.context is not UNDEF:
149            return self._subcontext(term.context, propagate=True)
150        return self
151
152    def get_context_for_type(self, node: Any) -> Optional[Context]:
153        if self.version >= 1.1:
154            rtype = self.get_type(node) if isinstance(node, dict) else None
155            if not isinstance(rtype, list):
156                rtype = [rtype] if rtype else []
157
158            typeterm = None
159            for rt in rtype:
160                try:
161                    typeterm = self.terms.get(rt)
162                except TypeError:
163                    # extra lenience, triggers if type is set to a literal
164                    pass
165                if typeterm is not None:
166                    break
167
168            if typeterm and typeterm.context:
169                subcontext = self.subcontext(typeterm.context, propagate=False)
170                if subcontext:
171                    return subcontext
172
173        return self.parent if self.propagate is False else self
174
175    def get_id(self, obj: Dict[str, Any]) -> Any:
176        return self._get(obj, ID)
177
178    def get_type(self, obj: Dict[str, Any]) -> Any:
179        return self._get(obj, TYPE)
180
181    def get_language(self, obj: Dict[str, Any]) -> Any:
182        return self._get(obj, LANG)
183
184    def get_value(self, obj: Dict[str, Any]) -> Any:
185        return self._get(obj, VALUE)
186
187    def get_graph(self, obj: Dict[str, Any]) -> Any:
188        return self._get(obj, GRAPH)
189
190    def get_list(self, obj: Dict[str, Any]) -> Any:
191        return self._get(obj, LIST)
192
193    def get_set(self, obj: Dict[str, Any]) -> Any:
194        return self._get(obj, SET)
195
196    def get_rev(self, obj: Dict[str, Any]) -> Any:
197        return self._get(obj, REV)
198
199    def _get(self, obj: Dict[str, Any], key: str) -> Any:
200        for alias in self._alias.get(key, []):
201            if alias in obj:
202                return obj.get(alias)
203        return obj.get(key)
204
205    # type error: Missing return statement
206    def get_key(self, key: str) -> str:  # type: ignore[return]
207        for alias in self.get_keys(key):
208            return alias
209
210    def get_keys(self, key: str) -> Generator[str, None, None]:
211        if key in self._alias:
212            for alias in self._alias[key]:
213                yield alias
214        yield key
215
216    lang_key = property(lambda self: self.get_key(LANG))
217    id_key = property(lambda self: self.get_key(ID))
218    type_key = property(lambda self: self.get_key(TYPE))
219    value_key = property(lambda self: self.get_key(VALUE))
220    list_key = property(lambda self: self.get_key(LIST))
221    rev_key = property(lambda self: self.get_key(REV))
222    graph_key = property(lambda self: self.get_key(GRAPH))
223
224    def add_term(
225        self,
226        name: str,
227        idref: str,
228        coercion: Union[Defined, str] = UNDEF,
229        container: Union[Collection[Any], str, Defined] = UNDEF,
230        index: Optional[Union[str, Defined]] = None,
231        language: Optional[Union[str, Defined]] = UNDEF,
232        reverse: bool = False,
233        context: Any = UNDEF,
234        prefix: Optional[bool] = None,
235        protected: bool = False,
236    ):
237        if self.version < 1.1 or prefix is None:
238            prefix = isinstance(idref, str) and idref.endswith(URI_GEN_DELIMS)
239
240        if not self._accept_term(name):
241            return
242
243        if self.version >= 1.1:
244            existing = self.terms.get(name)
245            if existing and existing.protected:
246                return
247
248        if isinstance(container, (list, set, tuple)):
249            container = set(container)
250        elif container is not UNDEF:
251            container = set([container])
252        else:
253            container = set()
254
255        term = Term(
256            idref,
257            name,
258            coercion,
259            container,
260            index,
261            language,
262            reverse,
263            context,
264            prefix,
265            protected,
266        )
267
268        self.terms[name] = term
269
270        container_key: Union[Defined, str]
271        for container_key in (LIST, LANG, SET):  # , INDEX, ID, GRAPH):
272            if container_key in container:
273                break
274        else:
275            container_key = UNDEF
276
277        self._lookup[(idref, coercion or language, container_key, reverse)] = term
278
279        if term.prefix is True:
280            self._prefixes[idref] = name
281
282    def find_term(
283        self,
284        idref: str,
285        coercion: Optional[Union[str, Defined]] = None,
286        container: Union[Defined, str] = UNDEF,
287        language: Optional[str] = None,
288        reverse: bool = False,
289    ):
290        lu = self._lookup
291
292        if coercion is None:
293            coercion = language
294
295        if coercion is not UNDEF and container:
296            found = lu.get((idref, coercion, container, reverse))
297            if found:
298                return found
299
300        if coercion is not UNDEF:
301            found = lu.get((idref, coercion, UNDEF, reverse))
302            if found:
303                return found
304
305        if container:
306            found = lu.get((idref, coercion, container, reverse))
307            if found:
308                return found
309        elif language:
310            found = lu.get((idref, UNDEF, LANG, reverse))
311            if found:
312                return found
313        else:
314            found = lu.get((idref, coercion or UNDEF, SET, reverse))
315            if found:
316                return found
317
318        return lu.get((idref, UNDEF, UNDEF, reverse))
319
320    def resolve(self, curie_or_iri: str) -> str:
321        iri = self.expand(curie_or_iri, False)
322        # type error: Argument 1 to "isblank" of "Context" has incompatible type "Optional[str]"; expected "str"
323        if self.isblank(iri):  # type: ignore[arg-type]
324            # type error: Incompatible return value type (got "Optional[str]", expected "str")
325            return iri  # type: ignore[return-value]
326        # type error: Unsupported right operand type for in ("Optional[str]")
327        if " " in iri:  # type: ignore[operator]
328            return ""
329        # type error: Argument 1 to "resolve_iri" of "Context" has incompatible type "Optional[str]"; expected "str"
330        return self.resolve_iri(iri)  # type: ignore[arg-type]
331
332    def resolve_iri(self, iri: str) -> str:
333        # type error: Argument 1 to "norm_url" has incompatible type "Optional[str]"; expected "str"
334        return norm_url(self._base, iri)  # type: ignore[arg-type]
335
336    def isblank(self, ref: str) -> bool:
337        return ref.startswith("_:")
338
339    def expand(self, term_curie_or_iri: Any, use_vocab: bool = True) -> Optional[str]:
340        if not isinstance(term_curie_or_iri, str):
341            return term_curie_or_iri
342
343        if not self._accept_term(term_curie_or_iri):
344            return ""
345
346        if use_vocab:
347            term = self.terms.get(term_curie_or_iri)
348            if term:
349                return term.id
350
351        is_term, pfx, local = self._prep_expand(term_curie_or_iri)
352        if pfx == "_":
353            return term_curie_or_iri
354
355        if pfx is not None:
356            ns = self.terms.get(pfx)
357            if ns and ns.prefix and ns.id:
358                return ns.id + local
359        elif is_term and use_vocab:
360            if self.vocab:
361                return self.vocab + term_curie_or_iri
362            return None
363
364        return self.resolve_iri(term_curie_or_iri)
365
366    def shrink_iri(self, iri: str) -> str:
367        ns, name = split_iri(str(iri))
368        pfx = self._prefixes.get(ns)
369        if pfx:
370            # type error: Argument 1 to "join" of "str" has incompatible type "Tuple[Any, Optional[str]]"; expected "Iterable[str]"
371            return ":".join((pfx, name))  # type: ignore[arg-type]
372        elif self._base:
373            if str(iri) == self._base:
374                return ""
375            # type error: Argument 1 to "startswith" of "str" has incompatible type "Optional[str]"; expected "Union[str, Tuple[str, ...]]"
376            elif iri.startswith(self._basedomain):  # type: ignore[arg-type]
377                # type error: Argument 1 to "len" has incompatible type "Optional[str]"; expected "Sized"
378                return iri[len(self._basedomain) :]  # type: ignore[arg-type]
379        return iri
380
381    def to_symbol(self, iri: str) -> Optional[str]:
382        iri = str(iri)
383        term = self.find_term(iri)
384        if term:
385            return term.name
386        ns, name = split_iri(iri)
387        if ns == self.vocab:
388            return name
389        pfx = self._prefixes.get(ns)
390        if pfx:
391            # type error: Argument 1 to "join" of "str" has incompatible type "Tuple[Any, Optional[str]]"; expected "Iterable[str]"
392            return ":".join((pfx, name))  # type: ignore[arg-type]
393        return iri
394
395    def load(
396        self,
397        source: _ContextSourceType,
398        base: Optional[str] = None,
399        referenced_contexts: Set[Any] = None,
400    ):
401        self.active = True
402        sources: List[Tuple[Optional[str], Union[Dict[str, Any], str, None]]] = []
403        # "Union[List[Union[Dict[str, Any], str]], List[Dict[str, Any]], List[str]]" : expression
404        # "Union[List[Dict[str, Any]], Dict[str, Any], List[str], str]" : variable
405        source = source if isinstance(source, list) else [source]
406        referenced_contexts = referenced_contexts or set()
407        self._prep_sources(base, source, sources, referenced_contexts)
408        for source_url, source in sources:
409            if source is None:
410                self._clear()
411            else:
412                # type error: Argument 1 to "_read_source" of "Context" has incompatible type "Union[Dict[str, Any], str]"; expected "Dict[str, Any]"
413                self._read_source(source, source_url, referenced_contexts)  # type: ignore[arg-type]
414
415    def _accept_term(self, key: str) -> bool:
416        if self.version < 1.1:
417            return True
418        if key and len(key) > 1 and key[0] == "@" and key[1].isalnum():
419            return key in NODE_KEYS
420        else:
421            return True
422
423    def _prep_sources(
424        self,
425        base: Optional[str],
426        inputs: Union[List[Union[Dict[str, Any], str, None]], List[str]],
427        sources: List[Tuple[Optional[str], Union[Dict[str, Any], str, None]]],
428        referenced_contexts: Set[str],
429        in_source_url: Optional[str] = None,
430    ):
431        for source in inputs:
432            source_url = in_source_url
433            new_base = base
434            if isinstance(source, str):
435                source_url = source
436                source_doc_base = base or self.doc_base
437                new_ctx = self._fetch_context(
438                    source, source_doc_base, referenced_contexts
439                )
440                if new_ctx is None:
441                    continue
442                else:
443                    if base:
444                        if TYPE_CHECKING:
445                            # if base is not None, then source_doc_base won't be
446                            # none due to how it is assigned.
447                            assert source_doc_base is not None
448                        new_base = urljoin(source_doc_base, source_url)
449                    source = new_ctx
450
451            if isinstance(source, dict):
452                if CONTEXT in source:
453                    source = source[CONTEXT]
454                    # type ignore: Incompatible types in assignment (expression has type "List[Union[Dict[str, Any], str, None]]", variable has type "Union[Dict[str, Any], str, None]")
455                    source = source if isinstance(source, list) else [source]  # type: ignore[assignment]
456
457            if isinstance(source, list):
458                # type error: Statement is unreachable
459                self._prep_sources(  # type: ignore[unreachable]
460                    new_base, source, sources, referenced_contexts, source_url
461                )
462            else:
463                sources.append((source_url, source))
464
465    def _fetch_context(
466        self, source: str, base: Optional[str], referenced_contexts: Set[str]
467    ):
468        # type error: Value of type variable "AnyStr" of "urljoin" cannot be "Optional[str]"
469        source_url = urljoin(base, source)  # type: ignore[type-var]
470
471        if source_url in referenced_contexts:
472            raise RECURSIVE_CONTEXT_INCLUSION
473
474        # type error: Argument 1 to "add" of "set" has incompatible type "Optional[str]"; expected "str"
475        referenced_contexts.add(source_url)  # type: ignore[arg-type]
476
477        if source_url in self._context_cache:
478            return self._context_cache[source_url]
479
480        # type error: Incompatible types in assignment (expression has type "Optional[Any]", variable has type "str")
481        source_json, _ = source_to_json(source_url)
482        if source_json and CONTEXT not in source_json:
483            raise INVALID_REMOTE_CONTEXT
484
485        # type error: Invalid index type "Optional[str]" for "Dict[str, Any]"; expected type "str"
486        self._context_cache[source_url] = source_json  # type: ignore[index]
487
488        return source_json
489
490    def _read_source(
491        self,
492        source: Dict[str, Any],
493        source_url: Optional[str] = None,
494        referenced_contexts: Optional[Set[str]] = None,
495    ):
496        imports = source.get(IMPORT)
497        if imports:
498            if not isinstance(imports, str):
499                raise INVALID_CONTEXT_ENTRY
500
501            imported = self._fetch_context(
502                imports, self.base, referenced_contexts or set()
503            )
504            if not isinstance(imported, dict):
505                raise INVALID_CONTEXT_ENTRY
506
507            imported = imported[CONTEXT]
508            imported.update(source)
509            source = imported
510
511        self.vocab = source.get(VOCAB, self.vocab)
512        self.version = source.get(VERSION, self.version)
513        protected = source.get(PROTECTED, False)
514
515        for key, value in source.items():
516            if key in {VOCAB, VERSION, IMPORT, PROTECTED}:
517                continue
518            elif key == PROPAGATE and isinstance(value, bool):
519                self.propagate = value
520            elif key == LANG:
521                self.language = value
522            elif key == BASE:
523                if not source_url and not imports:
524                    self.base = value
525            else:
526                self._read_term(source, key, value, protected)
527
528    def _read_term(
529        self,
530        source: Dict[str, Any],
531        name: str,
532        dfn: Union[Dict[str, Any], str],
533        protected: bool = False,
534    ) -> None:
535        idref = None
536        if isinstance(dfn, dict):
537            # term = self._create_term(source, key, value)
538            rev = dfn.get(REV)
539            protected = dfn.get(PROTECTED, protected)
540
541            coercion = dfn.get(TYPE, UNDEF)
542            if coercion and coercion not in (ID, TYPE, VOCAB):
543                coercion = self._rec_expand(source, coercion)
544
545            idref = rev or dfn.get(ID, UNDEF)
546            if idref == TYPE:
547                idref = str(RDF.type)
548                coercion = VOCAB
549            elif idref is not UNDEF:
550                idref = self._rec_expand(source, idref)
551            elif ":" in name:
552                idref = self._rec_expand(source, name)
553            elif self.vocab:
554                idref = self.vocab + name
555
556            context = dfn.get(CONTEXT, UNDEF)
557
558            self.add_term(
559                name,
560                idref,
561                coercion,
562                dfn.get(CONTAINER, UNDEF),
563                dfn.get(INDEX, UNDEF),
564                dfn.get(LANG, UNDEF),
565                bool(rev),
566                context,
567                dfn.get(PREFIX),
568                protected=protected,
569            )
570        else:
571            if isinstance(dfn, str):
572                if not self._accept_term(dfn):
573                    return
574                idref = self._rec_expand(source, dfn)
575            # type error: Argument 2 to "add_term" of "Context" has incompatible type "Optional[str]"; expected "str"
576            self.add_term(name, idref, protected=protected)  # type: ignore[arg-type]
577
578        if idref in NODE_KEYS:
579            self._alias.setdefault(idref, []).append(name)
580        else:
581            # undo aliases that may have been inherited from parent context
582            for v in self._alias.values():
583                if name in v:
584                    v.remove(name)
585
586    def _rec_expand(
587        self, source: Dict[str, Any], expr: Optional[str], prev: Optional[str] = None
588    ) -> Optional[str]:
589        if expr == prev or expr in NODE_KEYS:
590            return expr
591
592        nxt: Optional[str]
593        # type error: Argument 1 to "_prep_expand" of "Context" has incompatible type "Optional[str]"; expected "str"
594        is_term, pfx, nxt = self._prep_expand(expr)  # type: ignore[arg-type]
595        if pfx:
596            iri = self._get_source_id(source, pfx)
597            if iri is None:
598                if pfx + ":" == self.vocab:
599                    return expr
600                else:
601                    term = self.terms.get(pfx)
602                    if term:
603                        iri = term.id
604
605            if iri is None:
606                nxt = expr
607            else:
608                nxt = iri + nxt
609        else:
610            nxt = self._get_source_id(source, nxt) or nxt
611            if ":" not in nxt and self.vocab:
612                return self.vocab + nxt
613
614        return self._rec_expand(source, nxt, expr)
615
616    def _prep_expand(self, expr: str) -> Tuple[bool, Optional[str], str]:
617        if ":" not in expr:
618            return True, None, expr
619        pfx, local = expr.split(":", 1)
620        if not local.startswith("//"):
621            return False, pfx, local
622        else:
623            return False, None, expr
624
625    def _get_source_id(self, source: Dict[str, Any], key: str) -> Optional[str]:
626        # .. from source dict or if already defined
627        term = source.get(key)
628        if term is None:
629            dfn = self.terms.get(key)
630            if dfn:
631                term = dfn.id
632        elif isinstance(term, dict):
633            term = term.get(ID)
634        return term
635
636    def _term_dict(self, term: Term) -> Union[Dict[str, Any], str]:
637        tdict: Dict[str, Any] = {}
638        if term.type != UNDEF:
639            tdict[TYPE] = self.shrink_iri(term.type)
640        if term.container:
641            tdict[CONTAINER] = list(term.container)
642        if term.language != UNDEF:
643            tdict[LANG] = term.language
644        if term.reverse:
645            tdict[REV] = term.id
646        else:
647            tdict[ID] = term.id
648        if tdict.keys() == {ID}:
649            return tdict[ID]
650        return tdict
651
652    def to_dict(self) -> Dict[str, Any]:
653        """
654        Returns a dictionary representation of the context that can be
655        serialized to JSON.
656
657        Returns:
658            a dictionary representation of the context.
659        """
660        r = {v: k for (k, v) in self._prefixes.items()}
661        r.update({term.name: self._term_dict(term) for term in self._lookup.values()})
662        if self.base:
663            r[BASE] = self.base
664        if self.language:
665            r[LANG] = self.language
666        return r
667
668
669Term = namedtuple(
670    "Term",
671    "id, name, type, container, index, language, reverse, context," "prefix, protected",
672)
673
674Term.__new__.__defaults__ = (UNDEF, UNDEF, UNDEF, UNDEF, False, UNDEF, False, False)