Source code

Download source archive ↓

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        )