Proposal: rename "Structure and dependencies" discussion category to "Development"

[aucampia]

We need some place to discuss development related issues and "Structure and dependencies" is close enough but not quite there. Specifically I want something broad enough to cover contribution guidelines, use of conventional commits, architecture etc.

Please vote using thumbs up/down reactions on this topic:

[ghost]

I'm down with this.

After you raised the LSP violations issue, I've been minded to propose something similar and promote the LSP violation issue into a sub-discussion of development because, on reflection, from a domain modelling perspective, it makes no sense for Dataset to be a subclass of Graph, it just ain't so.

ATM, I'm working my way through the Graph nethods with a view to removing the inappropriate inheritance from Dataset and migrating the common functionality into a Mixin class - or small population of Mixin classes if there are arguments for the latter approach. It'd be useful to have somewhere to post analysis/pseudocode for discussion.

[ghost]

Graph cheatsheet

Initialization:

__init__(
    store: Union[Store, str] = "default",
    identifier: Optional[Union[IdentifiedNode, str]] = None,
    namespace_manager: Optional[NamespaceManager] = None,
    base: Optional[str] = None,
    bind_namespaces: "_NamespaceSetString" = "core",
)

Properties:

base: str
identifier: Node
_bind_namespaces: str  # selector
store: Store
self.context_aware: Boolean, determined by Store implementation
self.formula_aware: Boolean, determined by Store implementation

Core methods:

__contains__(self, triple): if triple in G
__getitem__(self, item):  # e.g. All friends and friends of friends of Bob `g[bob : FOAF.knows * "+"]`
__hash__(self):  # Misleading? “return hash(self.identifier)”
__iter__(self) -> Generator["_TripleType", None, None]:
__len__(self): # return self.__store.__len__(context=self.identifier)
__reduce__(self):
__repr__(self):
__str__(self):

Comparators:

__cmp__(self, other):
__eq__(self, other):
__ge__(self, other):
__gt__(self, other):
__le__(self, other):
__lt__(self, other):

Operators:

__add__(self, other: "Graph") -> "Graph":
__iadd__(self: "_GraphT", other: Iterable["_TripleType"]) -> "_GraphT":
__isub__(self: "_GraphT", other: Iterable["_TripleType"]) -> "_GraphT":
__mul__(self, other: "Graph") -> "Graph":
__sub__(self, other: "Graph") -> "Graph":
__xor__(self, other):

identifier(self) -> Node:  # Property, self.identier
n3(self):  # Return an n3 identifier for the Graph
toPython(self):  # “return self”

Namespaces:

absolutize(self, uri, defrag=1):  # Turn uri into an absolute URI if it's not one already
bind(self, prefix, namespace, override=True, replace=False) -> None:
compute_qname(self, uri, generate=True):
namespace_manager(self) -> NamespaceManager:
namespace_manager(self, nm: NamespaceManager):
namespaces(self):
qname(self, uri):

Retrieve:

all_nodes(self):  # Returns the set of all (subject | object) nodes
cbd(self, resource):  # Retrieves the Concise Bounded Description of a Resource from a Graph
items(self, list):  # Generator over all items in the resource specified by `list` where `list` is an RDF collection.
subjects(  # A generator of (optionally unique) subjects with the given predicate and object
predicates(  # A generator of (optionally unique) predicates with the given subject and object
objects(  # A generator of (optionally unique) objects with the given subject and predicate
subject_objects(  # A generator of (optionally unique) (subject, object) tuples for the given predicate
subject_predicates(  # A generator of (optionally unique) (subject, predicate) tuples for the given object
predicate_objects(  # A generator of (optionally unique) (predicate, object) tuples for the given subject
transitive_objects(self, subject, predicate, remember=None):  # Transitively generate objects for the ``predicate`` relationship - Generated objects belong to the depth-first transitive closure of the ``predicate`` relationship starting at ``subject``
transitive_subjects(self, predicate, object, remember=None):  # Transitively generate subjects for the ``predicate`` relationship - Generated subjects belong to the depth-first transitive closure of the ``predicate`` relationship starting at ``object``
transitiveClosure(self, func, arg, seen=None):  # Generates transitive closure of a user-defined function against the graph
value(subject=None, predicate=RDF.value, object=None, default=None, any=True)  # Get a value for a pair of two criteria,

Modify:

set(self, triple):  # Convenience method to mimick updating the value of object, removes any existing triples for s and p before adding (s, p, o).

Parse:

parse(

Serialize:

serialize(
print(self, format="turtle", encoding="utf-8", out=None):

SPARQL:

query(
update(

Bags:

collection(self, identifier):  # Create a new ``Collection`` instance
resource(self, identifier):  # Create a new ``Resource`` instance.

c14n:

de_skolemize(self, new_graph=None, uriref=None):
skolemize(self, new_graph=None, bnode=None, authority=None, basepath=None):

Structure:

connected(self):  # Check if the Graph is connected. The Graph is considered undirectional
isomorphic(self, other):  # does a very basic check if these graphs are the same, if no BNodes are involved, this is accurate.

Store:

__len__(self, context: Optional["Identifier"]):  # ABC Number of statements in the store.
close(self, commit_pending_transaction=False):
commit(self):
destroy(self, configuration):
open(self, configuration, create=False):
rollback(self):

add(self, triple: _TripleType, context: Optional["Identifier"], quoted: bool = False):  # Adds the given statement to a specific context or to the model.
addN(self, quads: _QuadType]): # Adds each item in the list of statements to a specific context.
contexts(self, triple: Optional[_TripleType])  # ABC Generator over all contexts in the graph.
remove(self, triple: _TripleType, context: Optional["Identifier"]):  # Remove the set of triples matching the pattern from the store
triples_choices(self, _TriplePatternList, context: Optional["Identifier"]):  # ABC A variant of triples that can take a list of terms instead of a single term in any slot
triples(triple_pattern: _TriplePattern, context: Optional["Identifier"])  # ABC A generator over all the triples matching the pattern.

query(self, query, initNs, initBindings, queryGraph, **kwargs) ABC
update(self, update, initNs, initBindings, queryGraph, **kwargs) ABC

add_graph # Store implementation override of NI
remove_graph # Store implementation override of NI

[ghost]

Most of the class-specific code of QuotedGraph(Graph) appears to be redundant, given its inheritance from Graph, OTOH, it burdens the API inessentially in that much of the inherited functionality appears to be rather questionable from a domain-modelling perspective, although not outrageous (e.g. I suppose there might be a use case for calling subject_objects on a QuotedGraph but I'd be pushed to hallucinate a use case for resource).

[ghost]

Also, it'd be useful to have somewhere to punt speculative work ...

Also, in other, as-yet-unexposed-and-incomplete work, I have adapted some of the (rather good) code in Pilon & Carrothers's apparently-abandoned “pymantic” to create a unified set of lark-based RDF parsers for RDFLib. Thus far I have completed hext, ntriples, nquads and turtle for standard RDF and ntriples/nquads for RDF Star. With the 3 standard RDF parsers, I'm seeing 100% scores on the w3 test suite.

I note that RDFLib's N3 parser explicitly extends RDF, so it's up for discussion as to whether this set of lark-based parsers should be published as a plugin or migrated into the main RDFLib codebase.

[aucampia]

hext

I would somewhat favour using the python JSON parser for HexTuples, even though we don't have to, I don't think we will gain much from using lark for it. As for the others I think it will be great to have.

[ghost]

Pymantic demonstrates some interesting (to me, at least) alternative approaches to modelling the domain and I'm minded to suggest that RDFLib might benefit from shifting its model slightly to encompass some of pymantic's approach if it's generally perceived to be of benefit.

F'rinstance while RDFLib is rich in modelling RDF terms, it doesn't offer a specific model for statements, so I've been riffing off've P&G's Triple, roping in Python's dataclasses library to provide basic functionality:

from dataclasses import (
    dataclass,
    FrozenInstanceError,
    asdict,
    fields,
    astuple,
    replace,
)


@dataclass(order=True, frozen=True)
class Triple:

    subject: Optional[Node] = None
    predicate: Optional[Node] = None
    object: Optional[Node] = None

    def __str__(self):
        return str(self.subject) + " " + str(self.predicate) + " " + str(self.object)

    def toString(self):  # noqa: N802
        return str(self)

    def __reduce__(self):
        return (Triple, (self.subject, self.predicate, self.object))

    def toPython(self):  # noqa: N802
        return (
            self.subject.toPython(),
            self.predicate.toPython(),
            self.object.toPython(),
        )


def test_triple():
    t = Triple()
    assert isinstance(t, Triple)
    logger.debug(f"{Triple.__class__}")


def test_triple_args():
    t = Triple(tarek, likes, pizza)
    assert isinstance(t, Triple)

    assert t.subject == tarek

    assert t.predicate == likes

    assert t.__hash__() is not None

    with pytest.raises(FrozenInstanceError, match="cannot assign to field 'subject'"):
        t.subject = michel

    assert str(t) == "urn:example:tarek urn:example:likes urn:example:pizza"

    assert t.toPython() == (
        "urn:example:tarek",
        "urn:example:likes",
        "urn:example:pizza",
    )

    assert asdict(t) == {
        "object": rdflib.term.URIRef("urn:example:pizza"),
        "predicate": rdflib.term.URIRef("urn:example:likes"),
        "subject": rdflib.term.URIRef("urn:example:tarek"),
    }

    t = replace(t, subject=michel)

    assert t.subject == michel