Deprecate ConjunctiveGraph (#2405) (#2786)

* Deprecate ConjunctiveGraph (#2405)

* docs: deprecate ConjunctiveGraph (#2405)

---------

Co-authored-by: Nicholas Car <[email protected]>

docs/intro_to_parsing.rst

@@ -116,7 +116,7 @@ Working with multi-graphs
 -------------------------
 
 To read and query multi-graphs, that is RDF data that is context-aware, you need to use rdflib's
-:class:`rdflib.ConjunctiveGraph` or :class:`rdflib.Dataset` class. These are extensions to :class:`rdflib.Graph` that
+:class:`rdflib.Dataset` class. This an extension to :class:`rdflib.Graph` that
 know all about quads (triples + graph IDs).
 
 If you had this multi-graph data file (in the ``trig`` format, using new-style ``PREFIX`` statement (not the older

docs/merging.rst

@@ -25,7 +25,7 @@ In RDFLib, blank nodes are given unique IDs when parsing, so graph merging can b
 ``graph`` now contains the merged graph of ``input1`` and ``input2``. 
 
 
-.. note:: However, the set-theoretic graph operations in RDFLib are assumed to be performed in sub-graphs of some larger data-base (for instance, in the context of a :class:`~rdflib.graph.ConjunctiveGraph`) and assume shared blank node IDs, and therefore do NOT do *correct* merging, i.e.:: 
+.. note:: However, the set-theoretic graph operations in RDFLib are assumed to be performed in sub-graphs of some larger data-base (for instance, in the context of a :class:`~rdflib.graph.Dataset`) and assume shared blank node IDs, and therefore do NOT do *correct* merging, i.e.:: 
 
 		  from rdflib import Graph
 

docs/plugin_parsers.rst

@@ -32,9 +32,8 @@ xml       :class:`~rdflib.plugins.parsers.rdfxml.RDFXMLParser`
 
 Multi-graph IDs
 ---------------
-Note that for correct parsing of multi-graph data, e.g. Trig, HexT, etc., into a ``ConjunctiveGraph`` or a ``Dataset``,
-as opposed to a context-unaware ``Graph``, you will need to set the ``publicID`` of the ``ConjunctiveGraph`` a 
-``Dataset`` to the identifier of the ``default_context`` (default graph), for example::
+Note that for correct parsing of multi-graph data, e.g. Trig, HexT, etc., into a ``Dataset``,
+as opposed to a context-unaware ``Graph``, you will need to set the ``publicID`` of the ``Dataset`` to the identifier of the ``default_context`` (default graph), for example::
 
     d = Dataset()
     d.parse(

rdflib/graph.py

@@ -19,6 +19,9 @@
 Conjunctive Graph
 -----------------
 
+.. warning::
+    ConjunctiveGraph is deprecated, use :class:`~rdflib.graph.Dataset` instead.
+
 A Conjunctive Graph is the most relevant collection of graphs that are
 considered to be the boundary for closed world assumptions.  This
 boundary is equivalent to that of the store instance (which is itself
@@ -249,6 +252,7 @@
 import logging
 import pathlib
 import random
+import warnings
 from io import BytesIO
 from typing import (
     IO,
@@ -1893,6 +1897,9 @@ class ConjunctiveGraph(Graph):
     """A ConjunctiveGraph is an (unnamed) aggregation of all the named
     graphs in a store.
 
+    .. warning::
+        ConjunctiveGraph is deprecated, use :class:`~rdflib.graph.Dataset` instead.
+
     It has a ``default`` graph, whose name is associated with the
     graph throughout its life. :meth:`__init__` can take an identifier
     to use as the name of this default graph or it will assign a
@@ -1910,6 +1917,14 @@ def __init__(
         default_graph_base: Optional[str] = None,
     ):
         super(ConjunctiveGraph, self).__init__(store, identifier=identifier)
+
+        if type(self) is ConjunctiveGraph:
+            warnings.warn(
+                "ConjunctiveGraph is deprecated, use Dataset instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         assert self.store.context_aware, (
             "ConjunctiveGraph must be backed by" " a context aware store."
         )

test/test_conjunctivegraph/test_conjunctive_graph.py

@@ -57,6 +57,13 @@ def test_context_namespaces():
     assert ("ex", ns) in g.namespace_manager.namespaces()
 
 
+def test_deprecated():
+    with pytest.warns(
+        DeprecationWarning, match="ConjunctiveGraph is deprecated, use Dataset instead."
+    ):
+        ConjunctiveGraph()
+
+
 def get_graph_ids_tests():
     def check(kws):
         cg = ConjunctiveGraph()

test/test_dataset/test_dataset.py

@@ -1,6 +1,7 @@
 import os
 import shutil
 import tempfile
+import warnings
 from test.data import CONTEXT1, LIKES, PIZZA, TAREK
 from test.utils.namespace import EGSCHEME
 
@@ -261,3 +262,14 @@ def test_subgraph_without_identifier() -> None:
     ) == ("genid", genid_prefix)
 
     assert f"{subgraph.identifier}".startswith(genid_prefix)
+
+
+def test_not_deprecated():
+    """
+    Ensure Dataset does not trigger the deprecation warning
+    from the ConjunctiveGraph superclass.
+    """
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        Dataset()