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)