`lodkit.ttl` could overload `__or__` for chaining

[lu-pl]

from collections.abc import Iterator
import itertools
from typing import Self

from lodkit import _Triple, ttl
from rdflib import Namespace, RDF, RDFS


ex = Namespace("https://example.com/")

class chainable_ttl(ttl):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self._chain: list[ttl] = []

    def __iter__(self) -> Iterator[_Triple]:
        yield from super().__iter__()
        yield from itertools.chain.from_iterable(self._chain)

    def __or__(self, other: ttl) -> Self:
        self._chain.append(other)
        return self


t1 = chainable_ttl(ex.s, (RDF.type, ex["class"]))
t2 = chainable_ttl(ex.s, (RDFS.label, "label"))

triples: ttl = t1 | t2

graph = triples.to_graph()
print(graph.serialize())

Result:

@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

<https://example.com/s> a <https://example.com/class> ;
    rdfs:label "label" .

[lu-pl]

The current PR implements a TripleChain class that essentially is wrapper around itertools..chain that defined __or__.

class _ToGraphMixin:
    def to_graph(self: Iterable[_Triple], graph: Graph | None = None) -> Graph:
        """Generate a graph instance from a ttl Iterator."""
        _graph = Graph() if graph is None else graph

        for triple in self:
            _graph.add(triple)
        return _graph

class TripleChain(Iterator[_Triple], _ToGraphMixin):
    def __init__(self, *triples: Iterable[_Triple]) -> None:
        self._triples = itertools.chain.from_iterable(triples)

    def __iter__(self) -> Self:
        return self

    def __next__(self) -> _Triple:
        return next(self._triples)

    def __or__(self, other: Iterable[_Triple]) -> Self:
        return self.__class__(self, other)

This allows to do the following:

t1: ttl = ...
t2: ttl = ...
t3: ttl = ...

triples: TripleChain = t1 | t2 | t3
graph: Graph = triples.to_graph()

assert not list(triples)

lodkit.ttl implements __or__ which returns a TripleChain initialized with itself.

[lu-pl]

I am unhappy with this for several reasons and the PR might never get merged.

What bugs me the most is the apparent Iterable/Iterator mismatch; lodkit.ttl is an Iterable and not an Iterator, its iteration behavior and calls to to_graph are reproducible - which is actually the desired behavior here.

TripleChain on the other hand should be an Iterator, not just an Iterable. E.g. if one chains objects of type Iterable[_Triple] and Iterator[_Triple], the chain abstraction becomes non-deterministic on multiple iterations because some elements in the chain will be exhausted on successive iterations. This also means that to_graph on a TripleChain exhausts the TripleChain - to_graph on a lodkit.ttl object however does not.

[lu-pl]

Note: TripleChain might still be somewhat surprising and overloading __or__ is generally wonky imo, but as long as lodkit.ttl does not overload __or__, the TripleChain construct could actually be useful.

[lu-pl]

#47 implements a TripleChain iterator without overloading of __or__.