src/rdflib/plugins/parsers/hext.py
1"""
2This is a rdflib plugin for parsing Hextuple files, which are Newline-Delimited JSON
3(ndjson) files, into Conjunctive. The store that backs the graph *must* be able to
4handle contexts, i.e. multiple graphs.
5"""
6
7from __future__ import annotations
8
9import json
10import warnings
11from io import TextIOWrapper
12from typing import TYPE_CHECKING, Any, BinaryIO, List, Optional, TextIO, Union
13
14from rdflib.graph import ConjunctiveGraph, Dataset, Graph
15from rdflib.parser import InputSource, Parser
16from rdflib.term import BNode, Literal, URIRef
17
18try:
19 import orjson
20
21 _HAS_ORJSON = True
22except ImportError:
23 orjson = None # type: ignore[assignment, unused-ignore]
24 _HAS_ORJSON = False
25
26if TYPE_CHECKING:
27 from io import BufferedReader
28
29__all__ = ["HextuplesParser"]
30
31
32class HextuplesParser(Parser):
33 """
34 An RDFLib parser for Hextuples
35 """
36
37 def __init__(self):
38 super(HextuplesParser, self).__init__()
39 self.default_context: Optional[Graph] = None
40 self.skolemize = False
41
42 def _parse_hextuple(
43 self, ds: Union[Dataset, ConjunctiveGraph], tup: List[Union[str, None]]
44 ) -> None:
45 # all values check
46 # subject, predicate, value, datatype cannot be None
47 # language and graph may be None
48 if tup[0] is None or tup[1] is None or tup[2] is None or tup[3] is None:
49 raise ValueError(
50 f"subject, predicate, value, datatype cannot be None. Given: {tup}"
51 )
52
53 # 1 - subject
54 s: Union[URIRef, BNode]
55 if tup[0].startswith("_"):
56 s = BNode(value=tup[0].replace("_:", ""))
57 if self.skolemize:
58 s = s.skolemize()
59 else:
60 s = URIRef(tup[0])
61
62 # 2 - predicate
63 p = URIRef(tup[1])
64
65 # 3 - value
66 o: Union[URIRef, BNode, Literal]
67 if tup[3] == "globalId":
68 o = URIRef(tup[2])
69 elif tup[3] == "localId":
70 o = BNode(value=tup[2].replace("_:", ""))
71 if self.skolemize:
72 o = o.skolemize()
73 else: # literal
74 if tup[4] is None:
75 o = Literal(tup[2], datatype=URIRef(tup[3]))
76 else:
77 o = Literal(tup[2], lang=tup[4])
78
79 # 6 - context
80 if tup[5] is not None:
81 c = (
82 BNode(tup[5].replace("_:", ""))
83 if tup[5].startswith("_:")
84 else URIRef(tup[5])
85 )
86 if isinstance(c, BNode) and self.skolemize:
87 c = c.skolemize()
88
89 ds.get_context(c).add((s, p, o))
90 elif self.default_context is not None:
91 self.default_context.add((s, p, o))
92 else:
93 raise Exception("No context to parse into!")
94
95 # type error: Signature of "parse" incompatible with supertype "Parser"
96 def parse(self, source: InputSource, graph: Graph, skolemize: bool = False, **kwargs: Any) -> None: # type: ignore[override]
97 if kwargs.get("encoding") not in [None, "utf-8"]:
98 warnings.warn(
99 f"Hextuples files are always utf-8 encoded, "
100 f"I was passed: {kwargs.get('encoding')}, "
101 "but I'm still going to use utf-8"
102 )
103
104 assert (
105 graph.store.context_aware
106 ), "Hextuples Parser needs a context-aware store!"
107
108 self.skolemize = skolemize
109 # Set default_union to True to mimic ConjunctiveGraph behavior
110 ds = Dataset(store=graph.store, default_union=True)
111 ds_default = ds.default_context # the DEFAULT_DATASET_GRAPH_ID
112 if isinstance(graph, (Dataset, ConjunctiveGraph)):
113 self.default_context = graph.default_context
114 elif graph.identifier is not None:
115 if graph.identifier == ds_default.identifier:
116 self.default_context = graph
117 else:
118 self.default_context = ds.get_context(graph.identifier)
119 else:
120 # mypy thinks this is unreachable, but graph.identifier can be None
121 self.default_context = ds_default # type: ignore[unreachable]
122 if self.default_context is not ds_default:
123 ds.default_context = self.default_context
124 ds.remove_graph(ds_default) # remove the original unused default graph
125
126 try:
127 text_stream: Optional[TextIO] = source.getCharacterStream()
128 except (AttributeError, LookupError):
129 text_stream = None
130 try:
131 binary_stream: Optional[BinaryIO] = source.getByteStream()
132 except (AttributeError, LookupError):
133 binary_stream = None
134
135 if text_stream is None and binary_stream is None:
136 raise ValueError(
137 f"Source does not have a character stream or a byte stream and cannot be used {type(source)}"
138 )
139 if TYPE_CHECKING:
140 assert text_stream is not None or binary_stream is not None
141 use_stream: Union[TextIO, BinaryIO]
142 if _HAS_ORJSON:
143 if binary_stream is not None:
144 use_stream = binary_stream
145 else:
146 if TYPE_CHECKING:
147 assert isinstance(text_stream, TextIOWrapper)
148 use_stream = text_stream
149 loads = orjson.loads
150 else:
151 if text_stream is not None:
152 use_stream = text_stream
153 else:
154 if TYPE_CHECKING:
155 assert isinstance(binary_stream, BufferedReader)
156 use_stream = TextIOWrapper(binary_stream, encoding="utf-8")
157 loads = json.loads
158
159 for line in use_stream: # type: Union[str, bytes]
160 if len(line) == 0 or line.isspace():
161 # Skipping empty lines because this is what was being done before for the first and last lines, albeit in an rather indirect way.
162 # The result is that we accept input that would otherwise be invalid.
163 # Possibly we should just let this result in an error.
164 continue
165 # this complex handing is because the 'value' component is
166 # allowed to be "" but not None
167 # all other "" values are treated as None
168 raw_line: List[str] = loads(line)
169 hex_tuple_line = [x if x != "" else None for x in raw_line]
170 if raw_line[2] == "":
171 hex_tuple_line[2] = ""
172 self._parse_hextuple(ds, hex_tuple_line)