src/rdflib/plugins/serializers/longturtle.py
1"""
2LongTurtle RDF graph serializer for RDFLib.
3See http://www.w3.org/TeamSubmission/turtle/ for syntax specification.
4
5This variant, longturtle as opposed to just turtle, makes some small format changes
6to turtle - the original turtle serializer. It:
7
8* uses PREFIX instead of @prefix
9* uses BASE instead of @base
10* adds a new line at RDF.type, or 'a'
11* adds a newline and an indent for all triples with more than one object (object list)
12* adds a new line and ';' for the last triple in a set with '.'
13 on the start of the next line
14* uses default encoding (encode()) is used instead of "latin-1"
15
16- Nicholas Car, 2023
17"""
18
19from __future__ import annotations
20
21import warnings
22from typing import IO, Any, Optional
23
24from rdflib.compare import to_canonical_graph
25from rdflib.exceptions import Error
26from rdflib.graph import Graph, _TripleType
27from rdflib.namespace import RDF
28from rdflib.term import BNode, Literal, URIRef
29
30from .turtle import RecursiveSerializer
31
32__all__ = ["LongTurtleSerializer"]
33
34SUBJECT = 0
35VERB = 1
36OBJECT = 2
37
38_GEN_QNAME_FOR_DT = False
39_SPACIOUS_OUTPUT = False
40
41
42class LongTurtleSerializer(RecursiveSerializer):
43 """LongTurtle, a Turtle serialization format.
44
45 When the optional parameter `canon` is set to `True`, the graph is canonicalized
46 before serialization. This normalizes blank node identifiers and allows for
47 deterministic serialization of the graph. Useful when consistent outputs are required.
48 """
49
50 short_name = "longturtle"
51 indentString = " "
52
53 def __init__(self, store):
54 self._ns_rewrite = {}
55 self._canon = False
56 super(LongTurtleSerializer, self).__init__(store)
57 self.keywords = {RDF.type: "a"}
58 self.reset()
59 self.stream = None
60 self._spacious: bool = _SPACIOUS_OUTPUT
61
62 def addNamespace(self, prefix, namespace):
63 # Turtle does not support prefixes that start with _
64 # if they occur in the graph, rewrite to p_blah
65 # this is more complicated since we need to make sure p_blah
66 # does not already exist. And we register namespaces as we go, i.e.
67 # we may first see a triple with prefix _9 - rewrite it to p_9
68 # and then later find a triple with a "real" p_9 prefix
69
70 # so we need to keep track of ns rewrites we made so far.
71
72 if (prefix > "" and prefix[0] == "_") or self.namespaces.get(
73 prefix, namespace
74 ) != namespace:
75 if prefix not in self._ns_rewrite:
76 p = "p" + prefix
77 while p in self.namespaces:
78 p = "p" + p
79 self._ns_rewrite[prefix] = p
80
81 prefix = self._ns_rewrite.get(prefix, prefix)
82
83 super(LongTurtleSerializer, self).addNamespace(prefix, namespace)
84 return prefix
85
86 def canonize(self):
87 """Apply canonicalization to the store.
88
89 This normalizes blank node identifiers and allows for deterministic
90 serialization of the graph.
91 """
92 if not self._canon:
93 return
94
95 namespace_manager = self.store.namespace_manager
96 store = to_canonical_graph(self.store)
97 content = store.serialize(format="application/n-triples")
98 lines = content.split("\n")
99 lines.sort()
100 graph = Graph()
101 graph.parse(
102 data="\n".join(lines), format="application/n-triples", skolemize=True
103 )
104 graph = graph.de_skolemize()
105 graph.namespace_manager = namespace_manager
106 self.store = graph
107
108 def reset(self):
109 super(LongTurtleSerializer, self).reset()
110 self._shortNames = {}
111 self._started = False
112 self._ns_rewrite = {}
113 self.canonize()
114
115 def serialize(
116 self,
117 stream: IO[bytes],
118 base: Optional[str] = None,
119 encoding: Optional[str] = None,
120 spacious: Optional[bool] = None,
121 **kwargs: Any,
122 ) -> None:
123 self._canon = kwargs.get("canon", False)
124 self.reset()
125 self.stream = stream
126 # if base is given here, use, if not and a base is set for the graph use that
127 if base is not None:
128 self.base = base
129 elif self.store.base is not None:
130 self.base = self.store.base
131
132 if spacious is not None:
133 self._spacious = spacious
134
135 self.preprocess()
136 subjects_list = self.orderSubjects()
137
138 self.startDocument()
139
140 firstTime = True
141 for subject in subjects_list:
142 if self.isDone(subject):
143 continue
144 if firstTime:
145 firstTime = False
146 if self.statement(subject) and not firstTime:
147 self.write("\n")
148
149 self.endDocument()
150
151 self.base = None
152
153 def preprocessTriple(self, triple: _TripleType) -> None:
154 super(LongTurtleSerializer, self).preprocessTriple(triple)
155 for i, node in enumerate(triple):
156 if i == VERB:
157 if node in self.keywords:
158 # predicate is a keyword
159 continue
160 if (
161 self.base is not None
162 and isinstance(node, URIRef)
163 and node.startswith(self.base)
164 and "#" not in node.replace(self.base, "")
165 and "/" not in node.replace(self.base, "")
166 ):
167 # predicate corresponds to base namespace
168 continue
169 # Don't use generated prefixes for subjects and objects
170 self.get_pname(node, gen_prefix=(i == VERB))
171 if isinstance(node, Literal) and node.datatype:
172 self.get_pname(node.datatype, gen_prefix=_GEN_QNAME_FOR_DT)
173 p = triple[1]
174 if isinstance(p, BNode): # hmm - when is P ever a bnode?
175 self._references[p] += 1
176
177 def get_pname(self, uri, gen_prefix=True):
178 if not isinstance(uri, URIRef):
179 return None
180
181 try:
182 parts = self.store.compute_qname(uri, generate=gen_prefix)
183 except Exception:
184 # is the uri a namespace in itself?
185 pfx = self.store.store.prefix(uri)
186
187 if pfx is not None:
188 parts = (pfx, uri, "")
189 else:
190 # nothing worked
191 return None
192
193 prefix, namespace, local = parts
194
195 # To understand treatment of % character refer to Productions for terminal PLX at
196 # https://www.w3.org/TR/turtle/#grammar-production-PLX
197 # Only % NOT followed by two hex chars requires manual backslash escaping
198 local = local.replace(r"(", r"\(").replace(r")", r"\)")
199 local = self.LOCALNAME_PECRENT_CHARACTER_REQUIRING_ESCAPE_REGEX.sub(
200 "\\%", local
201 )
202
203 # PName cannot end with .
204 if local.endswith("."):
205 return None
206
207 prefix = self.addNamespace(prefix, namespace)
208
209 return "%s:%s" % (prefix, local)
210
211 def getQName(self, uri, gen_prefix=True):
212 warnings.warn(
213 "LongTurtleSerializer.getQName is deprecated, use LongTurtleSerializer.get_pname instead.",
214 DeprecationWarning,
215 stacklevel=2,
216 )
217 return self.get_pname(uri, gen_prefix)
218
219 def startDocument(self):
220 self._started = True
221 ns_list = sorted(self.namespaces.items())
222
223 if self.base:
224 self.write(self.indent() + "BASE <%s>\n" % self.base)
225 for prefix, uri in ns_list:
226 self.write(self.indent() + "PREFIX %s: <%s>\n" % (prefix, uri))
227 if ns_list and self._spacious:
228 self.write("\n")
229
230 def endDocument(self):
231 if self._spacious:
232 self.write("\n")
233
234 def statement(self, subject):
235 self.subjectDone(subject)
236 return self.s_squared(subject) or self.s_default(subject)
237
238 def s_default(self, subject):
239 self.write("\n" + self.indent())
240 self.path(subject, SUBJECT)
241 self.write("\n" + self.indent())
242 self.predicateList(subject)
243 self.write("\n.")
244 return True
245
246 def s_squared(self, subject):
247 if (self._references[subject] > 0) or not isinstance(subject, BNode):
248 return False
249 self.write("\n" + self.indent() + "[]")
250 self.predicateList(subject, newline=False)
251 self.write("\n.")
252 return True
253
254 def path(self, node, position, newline=False):
255 if not (
256 self.p_squared(node, position) or self.p_default(node, position, newline)
257 ):
258 raise Error("Cannot serialize node '%s'" % (node,))
259
260 def p_default(self, node, position, newline=False):
261 if position != SUBJECT and not newline:
262 self.write(" ")
263 self.write(self.label(node, position))
264 return True
265
266 def label(self, node, position):
267 if node == RDF.nil:
268 return "()"
269 if position is VERB and node in self.keywords:
270 return self.keywords[node]
271 if isinstance(node, Literal):
272 return node._literal_n3(
273 use_plain=True,
274 qname_callback=lambda dt: self.get_pname(dt, _GEN_QNAME_FOR_DT),
275 )
276 else:
277 node = self.relativize(node)
278
279 return self.get_pname(node, position == VERB) or node.n3()
280
281 def p_squared(
282 self,
283 node,
284 position,
285 ):
286 if (
287 not isinstance(node, BNode)
288 or node in self._serialized
289 or self._references[node] > 1
290 or position == SUBJECT
291 ):
292 return False
293
294 if self.isValidList(node):
295 # this is a list
296 self.depth += 2
297 self.write(" (\n")
298 self.depth -= 2
299 self.doList(node)
300 self.write("\n" + self.indent() + ")")
301 else:
302 # this is a Blank Node
303 self.subjectDone(node)
304 self.write("\n" + self.indent(1) + "[\n")
305 self.depth += 1
306 self.predicateList(node)
307 self.depth -= 1
308 self.write("\n" + self.indent(1) + "]")
309
310 return True
311
312 def isValidList(self, l_):
313 """
314 Checks if l is a valid RDF list, i.e. no nodes have other properties.
315 """
316 try:
317 if self.store.value(l_, RDF.first) is None:
318 return False
319 except Exception:
320 return False
321 while l_:
322 if l_ != RDF.nil and len(list(self.store.predicate_objects(l_))) != 2:
323 return False
324 l_ = self.store.value(l_, RDF.rest)
325 return True
326
327 def doList(self, l_):
328 i = 0
329 while l_:
330 item = self.store.value(l_, RDF.first)
331 if item is not None:
332 if i == 0:
333 self.write(self.indent(1))
334 else:
335 self.write("\n" + self.indent(1))
336 self.path(item, OBJECT, newline=True)
337 self.subjectDone(l_)
338 l_ = self.store.value(l_, RDF.rest)
339 i += 1
340
341 def predicateList(self, subject, newline=False):
342 properties = self.buildPredicateHash(subject)
343 propList = self.sortProperties(properties)
344 if len(propList) == 0:
345 return
346 self.write(self.indent(1))
347 self.verb(propList[0], newline=True)
348 self.objectList(properties[propList[0]])
349 for predicate in propList[1:]:
350 self.write(" ;\n" + self.indent(1))
351 self.verb(predicate, newline=True)
352 self.objectList(properties[predicate])
353 self.write(" ;")
354
355 def verb(self, node, newline=False):
356 self.path(node, VERB, newline)
357
358 def objectList(self, objects):
359 count = len(objects)
360 if count == 0:
361 return
362 depthmod = (count == 1) and 0 or 1
363 self.depth += depthmod
364 first_nl = False
365 if count > 1:
366 if not isinstance(objects[0], BNode):
367 self.write("\n" + self.indent(1))
368 else:
369 self.write(" ")
370 first_nl = True
371 self.path(objects[0], OBJECT, newline=first_nl)
372 for obj in objects[1:]:
373 self.write(" ,")
374 if not isinstance(obj, BNode):
375 self.write("\n" + self.indent(1))
376 self.path(obj, OBJECT, newline=True)
377 self.depth -= depthmod