src/rdflib/plugins/serializers/hext.py
1"""
2HextuplesSerializer RDF graph serializer for RDFLib.
3See <https://github.com/ontola/hextuples> for details about the format.
4"""
5
6from __future__ import annotations
7
8import json
9import warnings
10from typing import IO, Any, Callable, List, Optional, Type, Union, cast
11
12from rdflib.graph import DATASET_DEFAULT_GRAPH_ID, ConjunctiveGraph, Dataset, Graph
13from rdflib.namespace import RDF, XSD
14from rdflib.serializer import Serializer
15from rdflib.term import BNode, IdentifiedNode, Literal, URIRef
16
17try:
18 import orjson
19
20 _HAS_ORJSON = True
21except ImportError:
22 orjson = None # type: ignore[assignment, unused-ignore]
23 _HAS_ORJSON = False
24
25__all__ = ["HextuplesSerializer"]
26
27
28class HextuplesSerializer(Serializer):
29 """
30 Serializes RDF graphs to NTriples format.
31 """
32
33 contexts: List[Union[Graph, IdentifiedNode]]
34 dumps: Callable
35
36 def __new__(cls, store: Union[Graph, Dataset, ConjunctiveGraph]):
37 if _HAS_ORJSON:
38 cls.str_local_id: Union[str, Any] = orjson.Fragment(b'"localId"')
39 cls.str_global_id: Union[str, Any] = orjson.Fragment(b'"globalId"')
40 cls.empty: Union[str, Any] = orjson.Fragment(b'""')
41 cls.lang_str: Union[str, Any] = orjson.Fragment(
42 b'"' + RDF.langString.encode("utf-8") + b'"'
43 )
44 cls.xsd_string: Union[str, Any] = orjson.Fragment(
45 b'"' + XSD.string.encode("utf-8") + b'"'
46 )
47 else:
48 cls.str_local_id = "localId"
49 cls.str_global_id = "globalId"
50 cls.empty = ""
51 cls.lang_str = f"{RDF.langString}"
52 cls.xsd_string = f"{XSD.string}"
53 return super(cls, cls).__new__(cls)
54
55 def __init__(self, store: Union[Graph, Dataset, ConjunctiveGraph]):
56 self.default_context: Optional[Union[Graph, IdentifiedNode]]
57 self.graph_type: Union[Type[Graph], Type[Dataset], Type[ConjunctiveGraph]]
58 if isinstance(store, (Dataset, ConjunctiveGraph)):
59 self.graph_type = (
60 Dataset if isinstance(store, Dataset) else ConjunctiveGraph
61 )
62 self.contexts = list(store.contexts())
63 if store.default_context:
64 self.default_context = store.default_context
65 self.contexts.append(store.default_context)
66 else:
67 self.default_context = None
68 else:
69 self.graph_type = Graph
70 self.contexts = [store]
71 self.default_context = None
72
73 Serializer.__init__(self, store)
74
75 def serialize(
76 self,
77 stream: IO[bytes],
78 base: Optional[str] = None,
79 encoding: Optional[str] = "utf-8",
80 **kwargs: Any,
81 ) -> None:
82 if base is not None:
83 warnings.warn(
84 "base has no meaning for Hextuples serialization. "
85 "I will ignore this value"
86 )
87
88 if encoding not in [None, "utf-8"]:
89 warnings.warn(
90 f"Hextuples files are always utf-8 encoded. "
91 f"I was passed: {encoding}, "
92 "but I'm still going to use utf-8 anyway!"
93 )
94
95 if self.store.formula_aware is True:
96 raise Exception(
97 "Hextuple serialization can't (yet) handle formula-aware stores"
98 )
99 context: Union[Graph, IdentifiedNode]
100 context_str: Union[bytes, str]
101 for context in self.contexts:
102 for triple in context:
103 # Generate context string just once, because it doesn't change
104 # for every triple in this context
105 context_str = cast(
106 Union[str, bytes],
107 (
108 self.empty
109 if self.graph_type is Graph
110 else (
111 orjson.Fragment('"' + self._context_str(context) + '"')
112 if _HAS_ORJSON
113 else self._context_str(context)
114 )
115 ),
116 )
117 hl = self._hex_line(triple, context_str)
118 if hl is not None:
119 stream.write(hl if _HAS_ORJSON else hl.encode())
120
121 def _hex_line(self, triple, context_str: Union[bytes, str]):
122 if isinstance(
123 triple[0], (URIRef, BNode)
124 ): # exclude QuotedGraph and other objects
125 # value
126 value = (
127 triple[2]
128 if isinstance(triple[2], Literal)
129 else self._iri_or_bn(triple[2])
130 )
131
132 # datatype
133 if isinstance(triple[2], URIRef):
134 # datatype = "http://www.w3.org/1999/02/22-rdf-syntax-ns#namedNode"
135 datatype = self.str_global_id
136 elif isinstance(triple[2], BNode):
137 # datatype = "http://www.w3.org/1999/02/22-rdf-syntax-ns#blankNode"
138 datatype = self.str_local_id
139 elif isinstance(triple[2], Literal):
140 if triple[2].datatype is not None:
141 datatype = f"{triple[2].datatype}"
142 else:
143 if triple[2].language is not None: # language
144 datatype = self.lang_str
145 else:
146 datatype = self.xsd_string
147 else:
148 return None # can't handle non URI, BN or Literal Object (QuotedGraph)
149
150 # language
151 if isinstance(triple[2], Literal):
152 if triple[2].language is not None:
153 language = f"{triple[2].language}"
154 else:
155 language = self.empty
156 else:
157 language = self.empty
158 line_list = [
159 self._iri_or_bn(triple[0]),
160 triple[1],
161 value,
162 datatype,
163 language,
164 context_str,
165 ]
166 outline: Union[str, bytes]
167 if _HAS_ORJSON:
168 outline = orjson.dumps(line_list, option=orjson.OPT_APPEND_NEWLINE)
169 else:
170 outline = json.dumps(line_list) + "\n"
171 return outline
172 else: # do not return anything for non-IRIs or BNs, e.g. QuotedGraph, Subjects
173 return None
174
175 def _iri_or_bn(self, i_):
176 if isinstance(i_, URIRef):
177 return f"{i_}"
178 elif isinstance(i_, BNode):
179 return f"{i_.n3()}"
180 else:
181 return None
182
183 def _context_str(self, context: Union[Graph, IdentifiedNode]) -> str:
184 context_identifier: IdentifiedNode = (
185 context.identifier if isinstance(context, Graph) else context
186 )
187 if context_identifier == DATASET_DEFAULT_GRAPH_ID:
188 return ""
189 if self.default_context is not None:
190 if (
191 isinstance(self.default_context, IdentifiedNode)
192 and context_identifier == self.default_context
193 ):
194 return ""
195 elif (
196 isinstance(self.default_context, Graph)
197 and context_identifier == self.default_context.identifier
198 ):
199 return ""
200 if self.graph_type is Graph:
201 # Only emit a context name when serializing a Dataset or ConjunctiveGraph
202 return ""
203 return (
204 f"{context_identifier}"
205 if isinstance(context_identifier, URIRef)
206 else context_identifier.n3()
207 )