Source code

Download source archive ↓

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