Source code

Download source archive ↓

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    )