feat: proposed Dataset API changes

[recalcitrantsupplant]

This draft PR is intended promote discussion/reach a consensus on the proposed changes to the Dataset API, by concretely describing what the interfaces would look like. As such, at this point in time, it is not intended that all of the required changes to dependencies/tests are implemented.

The following discussion gives context:
#2591
Additionally:

• There is a general writeup in /dataset_api.md
• Examples in examples/datasets.py

Summary of changes:

• Created a separate dataset.py module which contains only the Dataset class
• Removed the inheritance of Dataset from ConjunctiveGraph/Graph
• Stubbed methods / function signatures with expected input and output types
  • Added methods proposed/discussed here Proposed `Dataset` API changes #2591 (comment)
  • Added stubs for other expected methods based on existing and inherited methods.
  • Updated methods for triples, quads, subjects, subjects_objects etc. to accept "slicing" where iterables of terms can be passed in to filter on a set of terms.
  • Added graph= parameter and corresponding Enum for GraphType to allow filtering operations over the Default Graph or all Named Graphs
• Removed ConjunctiveGraph class
• Started removing the identifier attribute on Graph. There will still be many references to this.

[Tpt]

Thank you so much for pushing this!

I allowed myself a few API nits but I have not read the code carefully, please ignore them if they are not relevant

[ajnelson-nist]

Re:

• Removed ConjunctiveGraph class

Does it make sense to apply removal of ConjunctiveGraph in response to #3064 , in advance of accepting this PR? If not globally, then what about in just the JSON-LD serializer?

I'm asking without having reviewed all of the proposed typing here yet.

[namedgraph]

I question the usefulness of this. Why not simply:

d.default_graph.triples()

?

[recalcitrantsupplant]

Providing "default_graph" as a convenience necessarily means there will be more than one way to iterate over the triples. There's no functional change from the current classes here, just name changes, you can already Dataset.triples(context=) and you can also Dataset.default_context.triples()

[namedgraph]

Shouldn't this be equivalent to simply d.quads()? Since the default graph does not produce quads.

[namedgraph]

Or is the graph element of the default graph None?

[recalcitrantsupplant]

Yes the proposal is to have the "graph" of triples in the default graph set to None.

[namedgraph]

My general comment is that I don't like the new arguments of triples() and graphs(). IMO the equivalent result should be achieved using default_graph and get_named_graph(). There shouldn't be multiple ways to achieve the same thing.

If filtering needs to be done, it can be achieved with a simple map() and lambda.

[namedgraph]

for quad in (q for q in d.quads() if q[3] in (None, URIRef("http://example.com/graph-B"))): 

not much longer really.

[recalcitrantsupplant]

Yes I think this is the point to get a broader consensus on. The way I see it, if including the graph parameter:
Pros:

• can restrict "named", "default" enums to only be used in the graph= attribute, and not in the quads methods.
• can separate concerns a bit better, similar to how dataset clauses are used in SPARQL. E.g. set up an instance with graph= to restrict the scope to certain named graphs, then at runtime graphs can be passed in using quads
• provides a convenience/clean interface for what is a common pattern (for me at least!)

Cons:

• two ways to do the same thing, as you've pointed out.

[namedgraph]

Maybe I'm too used to Jena where Dataset is used via getDefaultModel and getNamedModel, but I don't really see myself needing the new parameters 🤷‍♂️

[namedgraph]

d.triples() doesn't really make sense? There should be Graph.triples() and Dataset.quads() only?

[recalcitrantsupplant]

I'm comfortable with it - SPARQL queries in triplestores where named graphs are used frequently omit the graph, only having basic graph patterns, and we understand this to be across all graphs?

[namedgraph]

Union graph is an extension feature though, not a feature of an RDF dataset.

[namedgraph]

One more question arised while I commenting: what is the graph component for the default graph in ds.graph() result?
It used to be DATASET_DEFAULT_GRAPH_ID = URIRef("urn:x-rdflib:default"), but now that the Graph.identifier is gone, what is it?
It would make sense to use None, but then the signature of Dataset.quad() becomes ambiguous in the case of quads(None, None, None, None) -- is the last None a wildcard or does it signify the default graph?

[recalcitrantsupplant]

Re:

• Removed ConjunctiveGraph class

Does it make sense to apply removal of ConjunctiveGraph in response to #3064 , in advance of accepting this PR? If not globally, then what about in just the JSON-LD serializer?

I'm asking without having reviewed all of the proposed typing here yet.

I wouldn't think so - as ConjunctiveGraph is used in a few different places and there's an inheritance hierarchy that removing it would break, so it's not a simple change. The JSON-LD serializer could potentially switch to Dataset while leaving ConjunctiveGraph in though, I haven't looked at it.

[recalcitrantsupplant]

One more question arised while I commenting: what is the graph component for the default graph in ds.graph() result? It used to be DATASET_DEFAULT_GRAPH_ID = URIRef("urn:x-rdflib:default"), but now that the Graph.identifier is gone, what is it? It would make sense to use None, but then the signature of Dataset.quad() becomes ambiguous in the case of quads(None, None, None, None) -- is the last None a wildcard or does it signify the default graph?

Good question. I would suggest None is an expected result/output from methods and can means that results are from the default graph, but that we are not in fact making them equivalent. When providing input to functions, None != default graph, and a user should not use it to mean this. The following methods can be used to unambiguously refer to the default graph:

ds.triples(graph="default")
ds.quads(graph="default")
ds.default_graph.triples()
etc.