Add a cbd_subject() method

[Natureshadow]

Summary of changes

This PR adds a new Graph.cbd_subject() method. It is the counter-part to Graph.cbd(): It checks whether the graph is a CBD for some resource and, if it is, returns the subject of that resource.

I need this for implementing federation between graphs, where incoming pushes shall be ckecked to be CBDs because CBDs are nice to test against ACLs (cf. https://socialhub.activitypub.rocks/t/formalizing-inbox-posts-to-be-cbds/3123)

It also adds a Graph.roots() method returning the roots of the graph, used as a utility in cbd_subject, but also useful otherwise.

Checklist

• [x] Checked that there aren't other open pull requests for the same change.
• [x] Added tests for any changes that have a runtime impact.
• [x] Checked that all tests and type checking passes.
• For changes that have a potential impact on users of this project:
  • [ ] Updated relevant documentation to avoid inaccuracies.
  • [x] Considered adding additional documentation.
  • [ ] Considered adding an example in ./examples for new features.
  • [ ] Considered updating our changelog (CHANGELOG.md).
• [ ] Considered granting push permissions to the PR branch, so maintainers can fix minor issues and keep your PR up to date.

[coveralls]

Coverage: 90.865% (+0.01%) from 90.854% when pulling 76fbb4eb0d493662bef295e59170125f4ec11f1a on Natureshadow:is-cbd into e103078be6c75b2f9a1dc515abffcdf6a674407d on RDFLib:main.

[aucampia]

Thanks for the PR @Natureshadow, as this is an enhancement I will want some feedback from other maintainers also, and I will still think about it a bit and maybe extend the docstrings a bit just to make sure I understand the intent.

[aucampia]

PRs to V6 is closed until further notice. See this for more details:

• https://github.com/RDFLib/rdflib/discussions/2395

[aucampia]

PRs to V6 is closed until further notice. See this for more details:

• RDFLib V6 and V7 #2395

We will be open for PRs again once this is resolved:

• https://github.com/RDFLib/rdflib/pull/2402

[aucampia]

Graph.cbd_subject() is a very special case I think, it may be useful in some select circumstances, but I think it will be the first thing we drop if we ever rework things as the surface area of RDFLib is already way too big for the maintenance resources. I will be open to integrating something like this in rdflib._contrib where we don't have any API guarantees.

I will leave this open but as of right now my main priority is improving quality.

[ashleysommer]

I've reviewed this, and I'm not particularly sure of its utility.

I don't think "roots" of a graph is a real linked-data or RDF concept. It looks like it returns all nodes that are in the subject position in any triple in the graph, but never in the object position of any triple in the graph.

That really only works where properties are top-down, eg a DCAT Catalog, where all children defined on the catalog with dcterms:hasPart. It doesn't work where children reference their parents, eg, a Dataset where all records use void:inDataset. In this case graph.roots() doesn't return the Dataset.

The assertion that a CBD graph will contain exactly 1 root is also incorrect. graph.cbd(uri) will also include in the graph triples where ?uri is the object (that is part of the definition of concise bounded description, or DESCRIBE in SPARQL). So for most CBD graphs, the graph.roots() call will return zero items.

Finally, the use of cbd_subjects() seems like a very special case like @aucampia said. I feel like you could do the same with some careful graph.isomorphic() calls in your application.