src/rdflib/plugin.py
1"""Plugin support for rdf.
2
3There are a number of plugin points for rdf: parser, serializer,
4store, query processor, and query result. Plugins can be registered
5either through setuptools entry_points or by calling
6rdf.plugin.register directly.
7
8If you have a package that uses a setuptools based `setup.py` you can add the
9following to your setup:
10
11```python
12entry_points = {
13 'rdf.plugins.parser': [
14 'nt = rdf.plugins.parsers.ntriples:NTParser',
15 ],
16 'rdf.plugins.serializer': [
17 'nt = rdf.plugins.serializers.NTSerializer:NTSerializer',
18 ],
19 }
20```
21
22See the [setuptools dynamic discovery of services and plugins](http://peak.telecommunity.com/DevCenter/setuptools#dynamic-discovery-of-services-and-plugins)
23for moreinformation.
24"""
25
26from __future__ import annotations
27
28from importlib.metadata import EntryPoint, entry_points
29from typing import (
30 TYPE_CHECKING,
31 Any,
32 Dict,
33 Generic,
34 Iterator,
35 Optional,
36 Tuple,
37 Type,
38 TypeVar,
39 overload,
40)
41
42import rdflib.plugins.stores.berkeleydb
43from rdflib.exceptions import Error
44from rdflib.parser import Parser
45from rdflib.query import (
46 Processor,
47 Result,
48 ResultParser,
49 ResultSerializer,
50 UpdateProcessor,
51)
52from rdflib.serializer import Serializer
53from rdflib.store import Store
54
55__all__ = [
56 "register",
57 "get",
58 "plugins",
59 "PluginException",
60 "Plugin",
61 "PluginT",
62 "PKGPlugin",
63]
64
65rdflib_entry_points = {
66 "rdf.plugins.store": Store,
67 "rdf.plugins.serializer": Serializer,
68 "rdf.plugins.parser": Parser,
69 "rdf.plugins.resultparser": ResultParser,
70 "rdf.plugins.resultserializer": ResultSerializer,
71 "rdf.plugins.queryprocessor": Processor,
72 "rdf.plugins.queryresult": Result,
73 "rdf.plugins.updateprocessor": UpdateProcessor,
74}
75
76_plugins: Dict[Tuple[str, Type[Any]], Plugin] = {}
77
78
79class PluginException(Error): # noqa: N818
80 pass
81
82
83#: A generic type variable for plugins
84PluginT = TypeVar("PluginT")
85
86
87class Plugin(Generic[PluginT]):
88 def __init__(
89 self, name: str, kind: Type[PluginT], module_path: str, class_name: str
90 ):
91 self.name = name
92 self.kind = kind
93 self.module_path = module_path
94 self.class_name = class_name
95 self._class: Optional[Type[PluginT]] = None
96
97 def getClass(self) -> Type[PluginT]: # noqa: N802
98 if self._class is None:
99 module = __import__(self.module_path, globals(), locals(), [""])
100 self._class = getattr(module, self.class_name)
101 return self._class
102
103
104class PKGPlugin(Plugin[PluginT]):
105 def __init__(self, name: str, kind: Type[PluginT], ep: EntryPoint):
106 self.name = name
107 self.kind = kind
108 self.ep = ep
109 self._class: Optional[Type[PluginT]] = None
110
111 def getClass(self) -> Type[PluginT]: # noqa: N802
112 if self._class is None:
113 self._class = self.ep.load()
114 return self._class
115
116
117def register(name: str, kind: Type[Any], module_path, class_name):
118 """
119 Register the plugin for (name, kind). The module_path and
120 class_name should be the path to a plugin class.
121 """
122 p = Plugin(name, kind, module_path, class_name)
123 _plugins[(name, kind)] = p
124
125
126def get(name: str, kind: Type[PluginT]) -> Type[PluginT]:
127 """
128 Return the class for the specified (name, kind). Raises a
129 PluginException if unable to do so.
130 """
131 try:
132 p: Plugin[PluginT] = _plugins[(name, kind)]
133 except KeyError:
134 raise PluginException("No plugin registered for (%s, %s)" % (name, kind))
135 return p.getClass()
136
137
138all_entry_points = entry_points()
139if hasattr(all_entry_points, "select"):
140 for entry_point, kind in rdflib_entry_points.items():
141 for ep in all_entry_points.select(group=entry_point):
142 _plugins[(ep.name, kind)] = PKGPlugin(ep.name, kind, ep)
143else:
144 # Prior to Python 3.10, this returns a dict instead of the selection interface, which is slightly slower
145 if TYPE_CHECKING:
146 assert isinstance(all_entry_points, dict)
147 for entry_point, kind in rdflib_entry_points.items():
148 for ep in all_entry_points.get(entry_point, []):
149 _plugins[(ep.name, kind)] = PKGPlugin(ep.name, kind, ep)
150
151
152@overload
153def plugins(
154 name: Optional[str] = ..., kind: Type[PluginT] = ...
155) -> Iterator[Plugin[PluginT]]: ...
156
157
158@overload
159def plugins(name: Optional[str] = ..., kind: None = ...) -> Iterator[Plugin]: ...
160
161
162def plugins(
163 name: Optional[str] = None, kind: Optional[Type[PluginT]] = None
164) -> Iterator[Plugin[PluginT]]:
165 """
166 A generator of the plugins.
167
168 Pass in name and kind to filter... else leave None to match all.
169 """
170 for p in _plugins.values():
171 if (name is None or name == p.name) and (kind is None or kind == p.kind):
172 yield p
173
174
175# Register Stores
176
177if rdflib.plugins.stores.berkeleydb.has_bsddb:
178 # Checks for BerkeleyDB before registering it
179 register(
180 "BerkeleyDB",
181 Store,
182 "rdflib.plugins.stores.berkeleydb",
183 "BerkeleyDB",
184 )
185register(
186 "default",
187 Store,
188 "rdflib.plugins.stores.memory",
189 "Memory",
190)
191register(
192 "Memory",
193 Store,
194 "rdflib.plugins.stores.memory",
195 "Memory",
196)
197register(
198 "SimpleMemory",
199 Store,
200 "rdflib.plugins.stores.memory",
201 "SimpleMemory",
202)
203register(
204 "Auditable",
205 Store,
206 "rdflib.plugins.stores.auditable",
207 "AuditableStore",
208)
209register(
210 "Concurrent",
211 Store,
212 "rdflib.plugins.stores.concurrent",
213 "ConcurrentStore",
214)
215
216register(
217 "SPARQLStore",
218 Store,
219 "rdflib.plugins.stores.sparqlstore",
220 "SPARQLStore",
221)
222register(
223 "SPARQLUpdateStore",
224 Store,
225 "rdflib.plugins.stores.sparqlstore",
226 "SPARQLUpdateStore",
227)
228
229# Register Triple Serializers
230register(
231 "application/rdf+xml",
232 Serializer,
233 "rdflib.plugins.serializers.rdfxml",
234 "XMLSerializer",
235)
236register(
237 "xml",
238 Serializer,
239 "rdflib.plugins.serializers.rdfxml",
240 "XMLSerializer",
241)
242register(
243 "pretty-xml",
244 Serializer,
245 "rdflib.plugins.serializers.rdfxml",
246 "PrettyXMLSerializer",
247)
248register(
249 "text/n3",
250 Serializer,
251 "rdflib.plugins.serializers.n3",
252 "N3Serializer",
253)
254register(
255 "n3",
256 Serializer,
257 "rdflib.plugins.serializers.n3",
258 "N3Serializer",
259)
260register(
261 "text/turtle",
262 Serializer,
263 "rdflib.plugins.serializers.turtle",
264 "TurtleSerializer",
265)
266register(
267 "turtle",
268 Serializer,
269 "rdflib.plugins.serializers.turtle",
270 "TurtleSerializer",
271)
272register(
273 "ttl",
274 Serializer,
275 "rdflib.plugins.serializers.turtle",
276 "TurtleSerializer",
277)
278register(
279 "longturtle",
280 Serializer,
281 "rdflib.plugins.serializers.longturtle",
282 "LongTurtleSerializer",
283)
284register(
285 "application/n-triples",
286 Serializer,
287 "rdflib.plugins.serializers.nt",
288 "NTSerializer",
289)
290register(
291 "ntriples",
292 Serializer,
293 "rdflib.plugins.serializers.nt",
294 "NTSerializer",
295)
296register(
297 "nt",
298 Serializer,
299 "rdflib.plugins.serializers.nt",
300 "NTSerializer",
301)
302register(
303 "nt11",
304 Serializer,
305 "rdflib.plugins.serializers.nt",
306 "NT11Serializer",
307)
308register(
309 "json-ld",
310 Serializer,
311 "rdflib.plugins.serializers.jsonld",
312 "JsonLDSerializer",
313)
314register(
315 "application/ld+json",
316 Serializer,
317 "rdflib.plugins.serializers.jsonld",
318 "JsonLDSerializer",
319)
320
321# Register Quad Serializers
322register(
323 "application/n-quads",
324 Serializer,
325 "rdflib.plugins.serializers.nquads",
326 "NQuadsSerializer",
327)
328register(
329 "nquads",
330 Serializer,
331 "rdflib.plugins.serializers.nquads",
332 "NQuadsSerializer",
333)
334register(
335 "application/trix",
336 Serializer,
337 "rdflib.plugins.serializers.trix",
338 "TriXSerializer",
339)
340register(
341 "trix",
342 Serializer,
343 "rdflib.plugins.serializers.trix",
344 "TriXSerializer",
345)
346register(
347 "application/trig",
348 Serializer,
349 "rdflib.plugins.serializers.trig",
350 "TrigSerializer",
351)
352register(
353 "trig",
354 Serializer,
355 "rdflib.plugins.serializers.trig",
356 "TrigSerializer",
357)
358register(
359 "hext",
360 Serializer,
361 "rdflib.plugins.serializers.hext",
362 "HextuplesSerializer",
363)
364register(
365 "patch",
366 Serializer,
367 "rdflib.plugins.serializers.patch",
368 "PatchSerializer",
369)
370
371# Register Triple Parsers
372register(
373 "application/rdf+xml",
374 Parser,
375 "rdflib.plugins.parsers.rdfxml",
376 "RDFXMLParser",
377)
378register(
379 "xml",
380 Parser,
381 "rdflib.plugins.parsers.rdfxml",
382 "RDFXMLParser",
383)
384register(
385 "text/n3",
386 Parser,
387 "rdflib.plugins.parsers.notation3",
388 "N3Parser",
389)
390register(
391 "n3",
392 Parser,
393 "rdflib.plugins.parsers.notation3",
394 "N3Parser",
395)
396register(
397 "text/turtle",
398 Parser,
399 "rdflib.plugins.parsers.notation3",
400 "TurtleParser",
401)
402register(
403 "turtle",
404 Parser,
405 "rdflib.plugins.parsers.notation3",
406 "TurtleParser",
407)
408register(
409 "ttl",
410 Parser,
411 "rdflib.plugins.parsers.notation3",
412 "TurtleParser",
413)
414register(
415 "application/n-triples",
416 Parser,
417 "rdflib.plugins.parsers.ntriples",
418 "NTParser",
419)
420register(
421 "ntriples",
422 Parser,
423 "rdflib.plugins.parsers.ntriples",
424 "NTParser",
425)
426register(
427 "nt",
428 Parser,
429 "rdflib.plugins.parsers.ntriples",
430 "NTParser",
431)
432register(
433 "nt11",
434 Parser,
435 "rdflib.plugins.parsers.ntriples",
436 "NTParser",
437)
438register(
439 "application/ld+json",
440 Parser,
441 "rdflib.plugins.parsers.jsonld",
442 "JsonLDParser",
443)
444register(
445 "json-ld",
446 Parser,
447 "rdflib.plugins.parsers.jsonld",
448 "JsonLDParser",
449)
450
451# Register Quad Parsers
452register(
453 "application/n-quads",
454 Parser,
455 "rdflib.plugins.parsers.nquads",
456 "NQuadsParser",
457)
458register(
459 "nquads",
460 Parser,
461 "rdflib.plugins.parsers.nquads",
462 "NQuadsParser",
463)
464register(
465 "application/trix",
466 Parser,
467 "rdflib.plugins.parsers.trix",
468 "TriXParser",
469)
470register(
471 "trix",
472 Parser,
473 "rdflib.plugins.parsers.trix",
474 "TriXParser",
475)
476register(
477 "application/trig",
478 Parser,
479 "rdflib.plugins.parsers.trig",
480 "TrigParser",
481)
482register(
483 "trig",
484 Parser,
485 "rdflib.plugins.parsers.trig",
486 "TrigParser",
487)
488register(
489 "hext",
490 Parser,
491 "rdflib.plugins.parsers.hext",
492 "HextuplesParser",
493)
494
495# Register RDF Patch Parsers
496register(
497 "patch",
498 Parser,
499 "rdflib.plugins.parsers.patch",
500 "RDFPatchParser",
501)
502
503# Register SPARQL Processors
504register(
505 "sparql",
506 Result,
507 "rdflib.plugins.sparql.processor",
508 "SPARQLResult",
509)
510register(
511 "sparql",
512 Processor,
513 "rdflib.plugins.sparql.processor",
514 "SPARQLProcessor",
515)
516register(
517 "sparql",
518 UpdateProcessor,
519 "rdflib.plugins.sparql.processor",
520 "SPARQLUpdateProcessor",
521)
522
523# Register SPARQL Result Serializers
524register(
525 "xml",
526 ResultSerializer,
527 "rdflib.plugins.sparql.results.xmlresults",
528 "XMLResultSerializer",
529)
530register(
531 "application/sparql-results+xml",
532 ResultSerializer,
533 "rdflib.plugins.sparql.results.xmlresults",
534 "XMLResultSerializer",
535)
536register(
537 "txt",
538 ResultSerializer,
539 "rdflib.plugins.sparql.results.txtresults",
540 "TXTResultSerializer",
541)
542register(
543 "json",
544 ResultSerializer,
545 "rdflib.plugins.sparql.results.jsonresults",
546 "JSONResultSerializer",
547)
548register(
549 "application/sparql-results+json",
550 ResultSerializer,
551 "rdflib.plugins.sparql.results.jsonresults",
552 "JSONResultSerializer",
553)
554register(
555 "csv",
556 ResultSerializer,
557 "rdflib.plugins.sparql.results.csvresults",
558 "CSVResultSerializer",
559)
560register(
561 "text/csv",
562 ResultSerializer,
563 "rdflib.plugins.sparql.results.csvresults",
564 "CSVResultSerializer",
565)
566
567# Register SPARQL Result Parsers
568register(
569 "xml",
570 ResultParser,
571 "rdflib.plugins.sparql.results.xmlresults",
572 "XMLResultParser",
573)
574register(
575 "application/sparql-results+xml",
576 ResultParser,
577 "rdflib.plugins.sparql.results.xmlresults",
578 "XMLResultParser",
579)
580register(
581 "json",
582 ResultParser,
583 "rdflib.plugins.sparql.results.jsonresults",
584 "JSONResultParser",
585)
586register(
587 "application/sparql-results+json",
588 ResultParser,
589 "rdflib.plugins.sparql.results.jsonresults",
590 "JSONResultParser",
591)
592register(
593 "csv",
594 ResultParser,
595 "rdflib.plugins.sparql.results.csvresults",
596 "CSVResultParser",
597)
598register(
599 "text/csv",
600 ResultParser,
601 "rdflib.plugins.sparql.results.csvresults",
602 "CSVResultParser",
603)
604register(
605 "tsv",
606 ResultParser,
607 "rdflib.plugins.sparql.results.tsvresults",
608 "TSVResultParser",
609)
610register(
611 "text/tab-separated-values",
612 ResultParser,
613 "rdflib.plugins.sparql.results.tsvresults",
614 "TSVResultParser",
615)
616
617graph_parsers = {parser.name for parser in plugins(kind=Parser)}
618result_parsers = {parser.name for parser in plugins(kind=ResultParser)}
619graph_result_parsers = graph_parsers - result_parsers
620for parser_name in graph_result_parsers:
621 register(
622 parser_name,
623 ResultParser,
624 "rdflib.plugins.sparql.results.graph",
625 "GraphResultParser",
626 )