Source code

Download source archive ↓

src/rdflib/plugins/sparql/results/xmlresults.py

1"""A Parser for SPARQL results in XML:
2
3http://www.w3.org/TR/rdf-sparql-XMLres/
4
5Bits and pieces borrowed from:
6http://projects.bigasterisk.com/sparqlhttp/
7
8Authors: Drew Perttula, Gunnar Aastrand Grimnes
9"""
10
11from __future__ import annotations
12
13import logging
14import xml.etree.ElementTree as xml_etree  # noqa: N813
15from io import BytesIO
16from typing import (
17    IO,
18    TYPE_CHECKING,
19    Any,
20    BinaryIO,
21    Dict,
22    Optional,
23    Sequence,
24    TextIO,
25    Tuple,
26    Union,
27    cast,
28)
29from xml.dom import XML_NAMESPACE
30from xml.sax.saxutils import XMLGenerator
31from xml.sax.xmlreader import AttributesNSImpl
32
33from rdflib.query import Result, ResultException, ResultParser, ResultSerializer
34from rdflib.term import BNode, Identifier, Literal, URIRef, Variable
35
36try:
37    # https://adamj.eu/tech/2021/12/29/python-type-hints-optional-imports/
38    import lxml.etree as lxml_etree
39
40    FOUND_LXML = True
41except ImportError:
42    FOUND_LXML = False
43
44SPARQL_XML_NAMESPACE = "http://www.w3.org/2005/sparql-results#"
45RESULTS_NS_ET = "{%s}" % SPARQL_XML_NAMESPACE
46
47log = logging.getLogger(__name__)
48
49
50class XMLResultParser(ResultParser):
51    """A Parser for SPARQL results in XML."""
52
53    # TODO FIXME: content_type should be a keyword only arg.
54    def parse(self, source: IO, content_type: Optional[str] = None) -> Result:  # type: ignore[override]
55        return XMLResult(source)
56
57
58class XMLResult(Result):
59    def __init__(self, source: IO, content_type: Optional[str] = None):
60        parser_encoding: Optional[str] = None
61        if hasattr(source, "encoding"):
62            if TYPE_CHECKING:
63                assert isinstance(source, TextIO)
64            parser_encoding = "utf-8"
65            source_str = source.read()
66            source = BytesIO(source_str.encode(parser_encoding))
67        else:
68            if TYPE_CHECKING:
69                assert isinstance(source, BinaryIO)
70
71        if FOUND_LXML:
72            lxml_parser = lxml_etree.XMLParser(huge_tree=True, encoding=parser_encoding)
73            tree = cast(
74                xml_etree.ElementTree,
75                lxml_etree.parse(source, parser=lxml_parser),
76            )
77        else:
78            xml_parser = xml_etree.XMLParser(encoding=parser_encoding)
79            tree = xml_etree.parse(source, parser=xml_parser)
80
81        boolean = tree.find(RESULTS_NS_ET + "boolean")
82        results = tree.find(RESULTS_NS_ET + "results")
83
84        if boolean is not None:
85            type_ = "ASK"
86        elif results is not None:
87            type_ = "SELECT"
88        else:
89            raise ResultException("No RDF result-bindings or boolean answer found!")
90
91        Result.__init__(self, type_)
92
93        if type_ == "SELECT":
94            self.bindings = []
95            for result in results:  # type: ignore[union-attr]
96                if result.tag != f"{RESULTS_NS_ET}result":
97                    # This is here because with lxml this also gets comments,
98                    # not just elements. Also this should not operate on non
99                    # "result" elements.
100                    continue
101                r = {}
102                for binding in result:
103                    if binding.tag != f"{RESULTS_NS_ET}binding":
104                        # This is here because with lxml this also gets
105                        # comments, not just elements. Also this should not
106                        # operate on non "binding" elements.
107                        continue
108                    # type error: error: Argument 1 to "Variable" has incompatible type "Union[str, None, Any]"; expected "str"
109                    # NOTE on type error: Element.get() can return None, and
110                    # this will invariably fail if passed into Variable
111                    # constructor as value
112                    r[Variable(binding.get("name"))] = parseTerm(binding[0])  # type: ignore[arg-type] # FIXME
113                self.bindings.append(r)
114
115            self.vars = [
116                # type error: Argument 1 to "Variable" has incompatible type "Optional[str]"; expected "str"
117                # NOTE on type error: Element.get() can return None, and this
118                # will invariably fail if passed into Variable constructor as
119                # value
120                Variable(x.get("name"))  # type: ignore[arg-type] # FIXME
121                for x in tree.findall(
122                    "./%shead/%svariable" % (RESULTS_NS_ET, RESULTS_NS_ET)
123                )
124            ]
125
126        else:
127            self.askAnswer = boolean.text.lower().strip() == "true"  # type: ignore[union-attr]
128
129
130def parseTerm(element: xml_etree.Element) -> Union[URIRef, Literal, BNode]:
131    """rdflib object (Literal, URIRef, BNode) for the given
132    elementtree element"""
133    tag, text = element.tag, element.text
134    if tag == RESULTS_NS_ET + "literal":
135        if text is None:
136            text = ""
137        datatype = None
138        lang = None
139        if element.get("datatype", None):
140            # type error: Argument 1 to "URIRef" has incompatible type "Optional[str]"; expected "str"
141            datatype = URIRef(element.get("datatype"))  # type: ignore[arg-type]
142        elif element.get("{%s}lang" % XML_NAMESPACE, None):
143            lang = element.get("{%s}lang" % XML_NAMESPACE)
144
145        ret = Literal(text, datatype=datatype, lang=lang)
146
147        return ret
148    elif tag == RESULTS_NS_ET + "uri":
149        # type error: Argument 1 to "URIRef" has incompatible type "Optional[str]"; expected "str"
150        return URIRef(text)  # type: ignore[arg-type]
151    elif tag == RESULTS_NS_ET + "bnode":
152        return BNode(text)
153    else:
154        raise TypeError("unknown binding type %r" % element)
155
156
157class XMLResultSerializer(ResultSerializer):
158    """Serializes SPARQL results into XML format."""
159
160    def __init__(self, result: Result):
161        ResultSerializer.__init__(self, result)
162
163    def serialize(self, stream: IO, encoding: str = "utf-8", **kwargs: Any) -> None:
164        writer = SPARQLXMLWriter(stream, encoding)
165        if self.result.type == "ASK":
166            writer.write_header([])
167            # type error: Argument 1 to "write_ask" of "SPARQLXMLWriter" has incompatible type "Optional[bool]"; expected "bool"
168            writer.write_ask(self.result.askAnswer)  # type: ignore[arg-type]
169        else:
170            # type error: Argument 1 to "write_header" of "SPARQLXMLWriter" has incompatible type "Optional[List[Variable]]"; expected "Sequence[Variable]"
171            writer.write_header(self.result.vars)  # type: ignore[arg-type]
172            writer.write_results_header()
173            for b in self.result.bindings:
174                writer.write_start_result()
175                for key, val in b.items():
176                    writer.write_binding(key, val)
177
178                writer.write_end_result()
179
180        writer.close()
181
182
183# TODO: Rewrite with ElementTree?
184class SPARQLXMLWriter:
185    """
186    Python saxutils-based SPARQL XML Writer
187    """
188
189    def __init__(self, output: IO, encoding: str = "utf-8"):
190        writer = XMLGenerator(output, encoding)
191        writer.startDocument()
192        writer.startPrefixMapping("", SPARQL_XML_NAMESPACE)
193        writer.startPrefixMapping("xml", XML_NAMESPACE)
194        writer.startElementNS(
195            (SPARQL_XML_NAMESPACE, "sparql"), "sparql", AttributesNSImpl({}, {})
196        )
197        self.writer = writer
198        self._output = output
199        self._encoding = encoding
200        self._results = False
201
202    def write_header(self, allvarsL: Sequence[Variable]) -> None:
203        self.writer.startElementNS(
204            (SPARQL_XML_NAMESPACE, "head"), "head", AttributesNSImpl({}, {})
205        )
206        for i in range(0, len(allvarsL)):
207            attr_vals = {
208                (None, "name"): str(allvarsL[i]),
209            }
210            attr_qnames = {
211                (None, "name"): "name",
212            }
213            self.writer.startElementNS(
214                (SPARQL_XML_NAMESPACE, "variable"),
215                "variable",
216                # type error: Argument 1 to "AttributesNSImpl" has incompatible type "Dict[Tuple[None, str], str]"; expected "Mapping[Tuple[str, str], str]"
217                # type error: Argument 2 to "AttributesNSImpl" has incompatible type "Dict[Tuple[None, str], str]"; expected "Mapping[Tuple[str, str], str]"  [arg-type]
218                AttributesNSImpl(attr_vals, attr_qnames),  # type: ignore[arg-type]
219            )
220            self.writer.endElementNS((SPARQL_XML_NAMESPACE, "variable"), "variable")
221        self.writer.endElementNS((SPARQL_XML_NAMESPACE, "head"), "head")
222
223    def write_ask(self, val: bool) -> None:
224        self.writer.startElementNS(
225            (SPARQL_XML_NAMESPACE, "boolean"), "boolean", AttributesNSImpl({}, {})
226        )
227        self.writer.characters(str(val).lower())
228        self.writer.endElementNS((SPARQL_XML_NAMESPACE, "boolean"), "boolean")
229
230    def write_results_header(self) -> None:
231        self.writer.startElementNS(
232            (SPARQL_XML_NAMESPACE, "results"), "results", AttributesNSImpl({}, {})
233        )
234        self._results = True
235
236    def write_start_result(self) -> None:
237        self.writer.startElementNS(
238            (SPARQL_XML_NAMESPACE, "result"), "result", AttributesNSImpl({}, {})
239        )
240        self._resultStarted = True
241
242    def write_end_result(self) -> None:
243        assert self._resultStarted
244        self.writer.endElementNS((SPARQL_XML_NAMESPACE, "result"), "result")
245        self._resultStarted = False
246
247    def write_binding(self, name: Variable, val: Identifier) -> None:
248        assert self._resultStarted
249
250        attr_vals: Dict[Tuple[Optional[str], str], str] = {
251            (None, "name"): str(name),
252        }
253        attr_qnames: Dict[Tuple[Optional[str], str], str] = {
254            (None, "name"): "name",
255        }
256        self.writer.startElementNS(
257            (SPARQL_XML_NAMESPACE, "binding"),
258            "binding",
259            # type error: Argument 1 to "AttributesNSImpl" has incompatible type "Dict[Tuple[None, str], str]"; expected "Mapping[Tuple[str, str], str]"
260            # type error: Argument 2 to "AttributesNSImpl" has incompatible type "Dict[Tuple[None, str], str]"; expected "Mapping[Tuple[str, str], str]"
261            AttributesNSImpl(attr_vals, attr_qnames),  # type: ignore[arg-type, unused-ignore]
262        )
263
264        if isinstance(val, URIRef):
265            self.writer.startElementNS(
266                (SPARQL_XML_NAMESPACE, "uri"), "uri", AttributesNSImpl({}, {})
267            )
268            self.writer.characters(val)
269            self.writer.endElementNS((SPARQL_XML_NAMESPACE, "uri"), "uri")
270        elif isinstance(val, BNode):
271            self.writer.startElementNS(
272                (SPARQL_XML_NAMESPACE, "bnode"), "bnode", AttributesNSImpl({}, {})
273            )
274            self.writer.characters(val)
275            self.writer.endElementNS((SPARQL_XML_NAMESPACE, "bnode"), "bnode")
276        elif isinstance(val, Literal):
277            attr_vals = {}
278            attr_qnames = {}
279            if val.language:
280                attr_vals[(XML_NAMESPACE, "lang")] = val.language
281                attr_qnames[(XML_NAMESPACE, "lang")] = "xml:lang"
282            elif val.datatype:
283                attr_vals[(None, "datatype")] = val.datatype
284                attr_qnames[(None, "datatype")] = "datatype"
285
286            self.writer.startElementNS(
287                (SPARQL_XML_NAMESPACE, "literal"),
288                "literal",
289                # type error: Argument 1 to "AttributesNSImpl" has incompatible type "Dict[Tuple[Optional[str], str], str]"; expected "Mapping[Tuple[str, str], str]"
290                # type error: Argument 2 to "AttributesNSImpl" has incompatible type "Dict[Tuple[Optional[str], str], str]"; expected "Mapping[Tuple[str, str], str]"
291                AttributesNSImpl(attr_vals, attr_qnames),  # type: ignore[arg-type, unused-ignore]
292            )
293            self.writer.characters(val)
294            self.writer.endElementNS((SPARQL_XML_NAMESPACE, "literal"), "literal")
295
296        else:
297            raise Exception("Unsupported RDF term: %s" % val)
298
299        self.writer.endElementNS((SPARQL_XML_NAMESPACE, "binding"), "binding")
300
301    def close(self) -> None:
302        if self._results:
303            self.writer.endElementNS((SPARQL_XML_NAMESPACE, "results"), "results")
304        self.writer.endElementNS((SPARQL_XML_NAMESPACE, "sparql"), "sparql")
305        self.writer.endDocument()