src/rdflib/plugins/parsers/nquads.py
1"""
2This is a rdflib plugin for parsing NQuad files into Conjunctive
3graphs that can be used and queried. The store that backs the graph
4*must* be able to handle contexts.
5
6```python
7>>> from rdflib import ConjunctiveGraph, URIRef, Namespace
8>>> g = ConjunctiveGraph()
9>>> data = open("test/data/nquads.rdflib/example.nquads", "rb")
10>>> g.parse(data, format="nquads") # doctest:+ELLIPSIS
11<Graph identifier=... (<class 'rdflib.graph.ConjunctiveGraph'>)>
12>>> assert len(g.store) == 449
13>>> # There should be 16 separate contexts
14>>> assert len([x for x in g.store.contexts()]) == 16
15>>> # is the name of entity E10009 "Arco Publications"?
16>>> # (in graph http://bibliographica.org/entity/E10009)
17>>> # Looking for:
18>>> # <http://bibliographica.org/entity/E10009>
19>>> # <http://xmlns.com/foaf/0.1/name>
20>>> # "Arco Publications"
21>>> # <http://bibliographica.org/entity/E10009>
22>>> s = URIRef("http://bibliographica.org/entity/E10009")
23>>> FOAF = Namespace("http://xmlns.com/foaf/0.1/")
24>>> assert(g.value(s, FOAF.name).eq("Arco Publications"))
25
26```
27"""
28
29from __future__ import annotations
30
31from codecs import getreader
32from typing import Any, MutableMapping, Optional
33
34from rdflib.exceptions import ParserError as ParseError
35from rdflib.graph import ConjunctiveGraph, Dataset, Graph
36from rdflib.parser import InputSource
37
38# Build up from the NTriples parser:
39from rdflib.plugins.parsers.ntriples import W3CNTriplesParser, r_tail, r_wspace
40from rdflib.term import BNode
41
42__all__ = ["NQuadsParser"]
43
44_BNodeContextType = MutableMapping[str, BNode]
45
46
47class NQuadsParser(W3CNTriplesParser):
48
49 # type error: Signature of "parse" incompatible with supertype "W3CNTriplesParser"
50 def parse( # type: ignore[override]
51 self,
52 inputsource: InputSource,
53 sink: Graph,
54 bnode_context: Optional[_BNodeContextType] = None,
55 skolemize: bool = False,
56 **kwargs: Any,
57 ):
58 """Parse inputsource as an N-Quads file.
59
60 Args:
61 inputsource: The source of N-Quads-formatted data.
62 sink: The graph where parsed quads will be stored.
63 bnode_context: Optional dictionary mapping blank node identifiers to
64 [`BNode`][rdflib.term.BNode] instances.
65 See `.W3CNTriplesParser.parse` for more details.
66 skolemize: Whether to skolemize blank nodes.
67
68 Returns:
69 The Dataset containing the parsed quads.
70
71 Raises:
72 AssertionError: If the sink store is not context-aware.
73 ParseError: If the input is not a file-like object or contains invalid lines.
74 """
75 assert (
76 sink.store.context_aware
77 ), "NQuadsParser must be given a context-aware store."
78 # Set default_union to True to mimic ConjunctiveGraph behavior
79 ds = Dataset(store=sink.store, default_union=True)
80 ds_default = ds.default_context # the DEFAULT_DATASET_GRAPH_ID
81 new_default_context = None
82 if isinstance(sink, (Dataset, ConjunctiveGraph)):
83 new_default_context = sink.default_context
84 elif sink.identifier is not None:
85 if sink.identifier == ds_default.identifier:
86 new_default_context = sink
87 else:
88 new_default_context = ds.get_context(sink.identifier)
89
90 if new_default_context is not None:
91 ds.default_context = new_default_context
92 ds.remove_graph(ds_default) # remove the original unused default graph
93 # type error: Incompatible types in assignment (expression has type "ConjunctiveGraph", base class "W3CNTriplesParser" defined the type as "Union[DummySink, NTGraphSink]")
94 self.sink: Dataset = ds # type: ignore[assignment]
95 self.skolemize = skolemize
96
97 source = inputsource.getCharacterStream()
98 if not source:
99 source = inputsource.getByteStream()
100 source = getreader("utf-8")(source)
101
102 if not hasattr(source, "read"):
103 raise ParseError("Item to parse must be a file-like object.")
104
105 self.file = source
106 self.buffer = ""
107 while True:
108 self.line = __line = self.readline()
109 if self.line is None:
110 break
111 try:
112 self.parseline(bnode_context)
113 except ParseError as msg:
114 raise ParseError("Invalid line (%s):\n%r" % (msg, __line))
115
116 return self.sink
117
118 def parseline(self, bnode_context: Optional[_BNodeContextType] = None) -> None:
119 self.eat(r_wspace)
120 if (not self.line) or self.line.startswith("#"):
121 return # The line is empty or a comment
122
123 subject = self.subject(bnode_context)
124 self.eat(r_wspace)
125
126 predicate = self.predicate()
127 self.eat(r_wspace)
128
129 obj = self.object(bnode_context)
130 self.eat(r_wspace)
131
132 context = self.uriref() or self.nodeid(bnode_context)
133 self.eat(r_tail)
134
135 if self.line:
136 raise ParseError("Trailing garbage")
137 # Must have a context aware store - add on a normal Graph
138 # discards anything where the ctx != graph.identifier
139 if context:
140 self.sink.get_context(context).add((subject, predicate, obj))
141 else:
142 self.sink.default_context.add((subject, predicate, obj))