Skip to content

Reiterate the docs on entry points #3109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Reiterate the docs on entry points #3109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8869574
Refresh docs on entry points
bswck Apr 4, 2025
cd8c1e9
Fix a cross-ref
bswck Apr 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/intro_to_sparql.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,8 +196,8 @@ Custom Evaluation Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^

For experts, it is possible to override how bits of SPARQL algebra are
evaluated. By using the `setuptools entry-point
<http://pythonhosted.org/distribute/setuptools.html#dynamic-discovery-of-services-and-plugins>`_
evaluated. By using the `entry point
<https://packaging.python.org/guides/creating-and-discovering-plugins/>`_
``rdf.plugins.sparqleval``, or simply adding to an entry to
:data:`rdflib.plugins.sparql.CUSTOM_EVALS`, a custom function can be
registered. The function will be called for each algebra component and
Expand Down
42 changes: 33 additions & 9 deletions docs/plugins.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,45 @@

Plugins
=======

.. toctree::
:maxdepth: 1

plugin_parsers
plugin_serializers
plugin_stores
plugin_query_results

.. image:: /_static/plugins-diagram.*
:alt: rdflib plugin "architecture"
:alt: RDFLib plugin architecture
:width: 450px
:target: _static/plugins-diagram.svg

RDFLib uses Python **entry points** to automatically discover plugins.
This approach allows you to extend RDFLib's functionality by adding custom parsers, serializers, stores, query processors, and result handlers.

Many parts of RDFLib are extensible with plugins, `see setuptools' 'Creating and discovering plugins' <https://packaging.python.org/guides/creating-and-discovering-plugins/>`_. These pages list the plugins included in RDFLib core.
Plugins can also be registered manually using :func:`rdflib.plugin.register`.

Supported entry point groups
----------------------------
- ``rdf.plugins.parser``: custom RDF parsers (:class:`rdflib.parser.Parser` subclasses)
- ``rdf.plugins.serializer``: custom RDF serializers (:class:`rdflib.serializer.Serializer` subclasses)
- ``rdf.plugins.store``: custom store implementations (:class:`rdflib.store.Store` subclasses)
- ``rdf.plugins.queryprocessor``: custom SPARQL query processors (:class:`rdflib.query.Processor` subclasses)
- ``rdf.plugins.updateprocessor``: custom SPARQL update processors (:class:`rdflib.query.UpdateProcessor` subclasses)
- ``rdf.plugins.resultparser``: custom SPARQL result parsers (:class:`rdflib.query.ResultParser` subclasses)
- ``rdf.plugins.resultserializer``: custom SPARQL result serializers (:class:`rdflib.query.ResultSerializer` subclasses)
- ``rdf.plugins.queryresult``: custom SPARQL query result classes (:class:`rdflib.query.Result` subclasses)

Example ``pyproject.toml`` using a PEP 621-compliant tool, e.g. uv:

.. toctree::
:maxdepth: 1
.. code-block:: toml

plugin_parsers
plugin_serializers
plugin_stores
plugin_query_results
[project.entry-points."rdf.plugins.parser"]
nt = "rdf.plugins.parsers.ntriples:NTParser"
"application/n-triples" = "rdf.plugins.parsers.ntriples:NTParser"

[project.entry-points."rdf.plugins.serializer"]
nt = "rdf.plugins.serializers.NTSerializer:NTSerializer"
"application/n-triples" = "rdf.plugins.parsers.ntriples:NTSerializer"

`Learn more about using package metadata for creating and discovering plugins <https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/#using-package-metadata>`_.
9 changes: 1 addition & 8 deletions examples/custom_eval.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,7 @@
asking for ``rdf:type`` triples.

Here the custom eval function is added manually, normally you would use
setuptools and entry_points to do it:
i.e. in your setup.py::

entry_points = {
'rdf.plugins.sparqleval': [
'myfunc = mypackage:MyFunction',
],
}
entry points to do it. See :doc:`/plugins` for more information.
"""

from pathlib import Path
Expand Down
20 changes: 2 additions & 18 deletions rdflib/plugin.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,26 +3,10 @@

There are a number of plugin points for rdf: parser, serializer,
store, query processor, and query result. Plugins can be registered
either through setuptools entry_points or by calling
either automatically through entry points or by calling
rdf.plugin.register directly.

If you have a package that uses a setuptools based setup.py you can add the
following to your setup::

entry_points = {
'rdf.plugins.parser': [
'nt = rdf.plugins.parsers.ntriples:NTParser',
],
'rdf.plugins.serializer': [
'nt = rdf.plugins.serializers.NTSerializer:NTSerializer',
],
}

See the `setuptools dynamic discovery of services and plugins`__ for more
information.

.. __: http://peak.telecommunity.com/DevCenter/setuptools#dynamic-discovery-of-services-and-plugins

For more details, see the :doc:`/plugins` documentation.
"""

from __future__ import annotations
Expand Down