Add optional graph argument to Graph.cbd, use for DESCRIBE queries

[mgberg]

Summary of changes

I often find myself wanting to create subgraphs including descriptions of multiple resources, so I end up doing some pattern like this:

src_graph: Graph  # A large graph for which I want a subgraph
out_graph = Graph()
for uri in resources:
    out_graph += src_graph.cbd(uri)

While this works fine, there is overhead every time cbd is called:

1. A new Graph object is created each time.
2. Once triples are added to that new graph, they must be copied over to out_graph, i.e. added to a graph a second time.

This PR adds an optional target_graph argument to the cbd method. If a Graph is provided for that argument, the computed CBD is added directly to that provided graph instead of creating a new graph. Consequently, the above snippet could be written like this to avoid that extra overhead:

src_graph: Graph  # A large graph for which I want a subgraph
out_graph = Graph()
for uri in resources:
    src_graph.cbd(uri, out_graph)

If the target_graph argument is not provided, then it behaves the same as it currently does- it should not break any existing code.

One place where this situation occurs is in the SPARQL DESCRIBE implementation. This PR tweaks that implementation to use this new argument to improve performance.

Checklist

• Checked that there aren't other open pull requests for
  the same change.
• Added tests for any changes that have a runtime impact.
• 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.
  • 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.839% (+0.003%) from 90.836% when pulling cc1e3f5 on corning-incorporated:add-graph-arg-to-cbd into 081a974 on RDFLib:main.

[aucampia]

@mgberg this seems pretty useful. Another way to approach this may be to extract something which computes CBDs into a separate function freestanding, function, and then have that operate on a source and target graph. The benefit there would be that the graph interface remains smaller.

I will think about it a bit.

@westurner @niklasl any feedback from you would be appreciated here.

[westurner]

Maybe def cbd(self, *, target_graph=None)?

[aucampia]

@mgberg it is slightly better to make pull requests from your personal account if you are making them across organizations, that way we can update your PR branch directly with suggestions.

The pull requests mostly looks fine, but I think making target_graph a keyword only argument is probably best.

I will make a PR against your branch doing that and adding some unit tests.

[aucampia]

@mgberg it is slightly better to make pull requests from your personal account if you are making them across organizations, that way we can update your PR branch directly with suggestions.

The pull requests mostly looks fine, but I think making target_graph a keyword only argument is probably best.

I will make a PR against your branch doing that and adding some unit tests.

PR here: corning-incorporated#2

[mgberg]

@mgberg it is slightly better to make pull requests from your personal account if you are making them across organizations, that way we can update your PR branch directly with suggestions.

I'll do that in the future!

[aucampia]

Change looks good to me, thanks @mgberg

[ghost]

👍