pyjelly 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

pyjelly/integrations/rdflib/parse.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 from collections.abc import Generator, Iterable
-from typing import IO, Any, Callable
-from typing_extensions import Never, override
+from itertools import chain
+from typing import IO, Any, Callable, Union
+from typing_extensions import Never, Self, override
 
 import rdflib
+from rdflib import Node
 from rdflib.graph import DATASET_DEFAULT_GRAPH_ID, Dataset, Graph
 from rdflib.parser import InputSource
 from rdflib.parser import Parser as RDFLibParser
@@ -12,16 +14,113 @@ from rdflib.parser import Parser as RDFLibParser
 from pyjelly import jelly
 from pyjelly.errors import JellyConformanceError
 from pyjelly.options import StreamTypes
-from pyjelly.parse.decode import Adapter, Decoder, ParserOptions, ParsingMode
+from pyjelly.parse.decode import Adapter, Decoder, ParserOptions
 from pyjelly.parse.ioutils import get_options_and_frames
 
+GraphName = Union[rdflib.URIRef, rdflib.BNode, str]
+
+
+class Triple(tuple[Node, Node, Node]):
+    """
+    Describe RDFLib triple.
+
+    Args:
+        tuple (Node, Node, Node): s/p/o tuple of RDFLib Nodes.
+
+    Returns:
+        Triple: triple as tuple.
+
+    """
+
+    __slots__ = ()
+
+    def __new__(cls, s: Node, p: Node, o: Node) -> Self:
+        return tuple.__new__(cls, (s, p, o))
+
+    @property
+    def s(self) -> Node:
+        return self[0]
+
+    @property
+    def p(self) -> Node:
+        return self[1]
+
+    @property
+    def o(self) -> Node:
+        return self[2]
+
+
+class Quad(tuple[Node, Node, Node, GraphName]):
+    """
+    Describe RDFLib quad.
+
+    Args:
+        tuple (Node, Node, Node, GraphName):
+            s/p/o/g as a tuple of RDFLib nodes and a GraphName,
+
+    Returns:
+        Quad: quad as tuple.
+
+    """
+
+    __slots__ = ()
+
+    def __new__(cls, s: Node, p: Node, o: Node, g: GraphName) -> Self:
+        return tuple.__new__(cls, (s, p, o, g))
+
+    @property
+    def s(self) -> Node:
+        return self[0]
+
+    @property
+    def p(self) -> Node:
+        return self[1]
+
+    @property
+    def o(self) -> Node:
+        return self[2]
+
+    @property
+    def g(self) -> GraphName:
+        return self[3]
+
+
+Statement = Union[Triple, Quad]
+
+
+class Prefix(tuple[str, rdflib.URIRef]):
+    """
+    Describe RDF Prefix(i.e, namespace declaration).
+
+    Args:
+        tuple (str, rdflib.URIRef): expects prefix as a string,
+            and full namespace URI as Rdflib.URIRef.
+
+    Returns:
+        Prefix: prefix as tuple(prefix, iri).
+
+    """
+
+    __slots__ = ()
+
+    def __new__(cls, prefix: str, iri: rdflib.URIRef) -> Self:
+        return tuple.__new__(cls, (prefix, iri))
+
+    @property
+    def prefix(self) -> str:
+        return self[0]
+
+    @property
+    def iri(self) -> rdflib.URIRef:
+        return self[1]
+
 
 class RDFLibAdapter(Adapter):
     """
     RDFLib adapter class, is extended by triples and quads implementations.
 
     Args:
-        Adapter (_type_): abstract adapter class
+        Adapter (): abstract adapter class
 
     """
 
@@ -46,13 +145,15 @@ class RDFLibAdapter(Adapter):
     ) -> rdflib.Literal:
         return rdflib.Literal(lex, lang=language, datatype=datatype)
 
+    @override
+    def namespace_declaration(self, name: str, iri: str) -> Prefix:
+        return Prefix(name, self.iri(iri))
+
 
 def _adapter_missing(feature: str, *, stream_types: StreamTypes) -> Never:
     """
     Raise error if functionality is missing in adapter.
 
-    TODO: currently not used anywhere due to logical types being removed
-
     Args:
         feature (str): function which is not implemented
         stream_types (StreamTypes): what combination of physical/logical types
@@ -79,93 +180,48 @@ class RDFLibTriplesAdapter(RDFLibAdapter):
     """
     Triples adapter RDFLib implementation.
 
-    Notes: has internal graph object which tracks
-        triples and namespaces and can get flushed between frames.
+    Notes: returns triple/namespace declaration as soon as receives them.
     """
 
     def __init__(
         self,
         options: ParserOptions,
-        graph_factory: Callable[[], Graph],
-        parsing_mode: ParsingMode = ParsingMode.FLAT,
     ) -> None:
-        super().__init__(options=options, parsing_mode=parsing_mode)
-        self.graph = graph_factory()
-        self.graph_factory = graph_factory
-        self.parsing_mode = parsing_mode
+        super().__init__(options=options)
 
     @override
-    def triple(self, terms: Iterable[Any]) -> Any:
-        self.graph.add(tuple(terms))
-
-    @override
-    def namespace_declaration(self, name: str, iri: str) -> None:
-        self.graph.bind(name, self.iri(iri))
-
-    def frame(self) -> Graph:
-        """
-        Finalize one frame in triples stream.
-
-        Returns:
-           Graph: frame content as a separate Graph
-                and starts a new Graph
-
-        """
-        this_graph = self.graph
-        self.graph = self.graph_factory()
-        return this_graph
+    def triple(self, terms: Iterable[Any]) -> Triple:
+        return Triple(*terms)
 
 
 class RDFLibQuadsBaseAdapter(RDFLibAdapter):
-    def __init__(
-        self,
-        options: ParserOptions,
-        dataset_factory: Callable[[], Dataset],
-        parsing_mode: ParsingMode = ParsingMode.FLAT,
-    ) -> None:
-        super().__init__(options=options, parsing_mode=parsing_mode)
-        self.dataset = dataset_factory()
-        self.dataset_factory = dataset_factory
-
-    @override
-    def frame(self) -> Dataset:
-        current_dataset = self.dataset
-        self.dataset = self.dataset_factory()
-        return current_dataset
+    def __init__(self, options: ParserOptions) -> None:
+        super().__init__(options=options)
 
 
 class RDFLibQuadsAdapter(RDFLibQuadsBaseAdapter):
     """
     Extended RDFLib adapter for the QUADS physical type.
 
-    Notes:
-        Adds triples and namespaces directly to
-        dataset, so RDFLib handles the rest.
-
     Args:
-        RDFLibQuadsBaseAdapter (_type_): base quads adapter
+        RDFLibQuadsBaseAdapter (RDFLibAdapter): base quads adapter
             (shared with graphs physical type)
 
     """
 
     @override
-    def namespace_declaration(self, name: str, iri: str) -> None:
-        self.dataset.bind(name, self.iri(iri))
-
-    @override
-    def quad(self, terms: Iterable[Any]) -> Any:
-        self.dataset.add(tuple(terms))
+    def quad(self, terms: Iterable[Any]) -> Quad:
+        return Quad(*terms)
 
 
 class RDFLibGraphsAdapter(RDFLibQuadsBaseAdapter):
     """
     Extension of RDFLibQuadsBaseAdapter for the GRAPHS physical type.
 
-    Notes: introduces graph start/end, checks if graph exists,
-        dataset store management.
+    Notes: introduces graph start/end, checks if graph exists.
 
     Args:
-        RDFLibQuadsBaseAdapter (_type_): base adapter for quads management.
+        RDFLibQuadsBaseAdapter (RDFLibAdapter): base adapter for quads management.
 
     Raises:
         JellyConformanceError: if no graph_start was encountered
@@ -177,14 +233,8 @@ class RDFLibGraphsAdapter(RDFLibQuadsBaseAdapter):
     def __init__(
         self,
         options: ParserOptions,
-        dataset_factory: Callable[[], Dataset],
-        parsing_mode: ParsingMode = ParsingMode.FLAT,
     ) -> None:
-        super().__init__(
-            options=options,
-            dataset_factory=dataset_factory,
-            parsing_mode=parsing_mode,
-        )
+        super().__init__(options=options)
         self._graph_id = None
 
     @property
@@ -198,12 +248,8 @@ class RDFLibGraphsAdapter(RDFLibQuadsBaseAdapter):
         self._graph_id = graph_id
 
     @override
-    def namespace_declaration(self, name: str, iri: str) -> None:
-        self.dataset.bind(name, self.iri(iri))
-
-    @override
-    def triple(self, terms: Iterable[Any]) -> None:
-        self.dataset.add((*terms, self._graph_id))
+    def triple(self, terms: Iterable[Any]) -> Quad:
+        return Quad(*chain(terms, [self._graph_id]))
 
     @override
     def graph_end(self) -> None:
@@ -213,54 +259,42 @@ class RDFLibGraphsAdapter(RDFLibQuadsBaseAdapter):
 def parse_triples_stream(
     frames: Iterable[jelly.RdfStreamFrame],
     options: ParserOptions,
-    graph_factory: Callable[[], Graph],
-    parsing_mode: ParsingMode = ParsingMode.FLAT,
-) -> Generator[Graph]:
+) -> Generator[Iterable[Triple | Prefix]]:
     """
     Parse flat triple stream.
 
     Args:
         frames (Iterable[jelly.RdfStreamFrame]): iterator over stream frames
         options (ParserOptions): stream options
-        graph_factory (Callable): Lambda to construct a graph
-        parsing_mode (ParsingMode): specifies whether this is
-            a flat or grouped parsing.
 
     Yields:
-        Generator[Graph]: RDFLib Graph(s)
+        Generator[Iterable[Triple | Prefix]]:
+            Generator of iterables of Triple or Prefix objects,
+            one iterable per frame.
 
     """
-    adapter = RDFLibTriplesAdapter(
-        options, graph_factory=graph_factory, parsing_mode=parsing_mode
-    )
+    adapter = RDFLibTriplesAdapter(options)
     decoder = Decoder(adapter=adapter)
     for frame in frames:
-        g = decoder.decode_frame(frame)
-        if g is not None:
-            yield g
-
-    if parsing_mode is ParsingMode.FLAT:
-        yield adapter.graph
+        yield decoder.iter_rows(frame)
+    return
 
 
 def parse_quads_stream(
     frames: Iterable[jelly.RdfStreamFrame],
     options: ParserOptions,
-    dataset_factory: Callable[[], Dataset],
-    parsing_mode: ParsingMode = ParsingMode.FLAT,
-) -> Generator[Dataset]:
+) -> Generator[Iterable[Quad | Prefix]]:
     """
     Parse flat quads stream.
 
     Args:
         frames (Iterable[jelly.RdfStreamFrame]): iterator over stream frames
         options (ParserOptions): stream options
-        dataset_factory (Callable): Lambda to construct a dataset
-        parsing_mode (ParsingMode): specifies whether this is
-            a flat or grouped parsing.
 
     Yields:
-        Generator[Dataset]: RDFLib dataset(s)
+        Generator[Iterable[Quad | Prefix]]:
+            Generator of iterables of Quad or Prefix objects,
+            one iterable per frame.
 
     """
     adapter_class: type[RDFLibQuadsBaseAdapter]
@@ -268,26 +302,18 @@ def parse_quads_stream(
         adapter_class = RDFLibQuadsAdapter
     else:
         adapter_class = RDFLibGraphsAdapter
-    adapter = adapter_class(
-        options=options,
-        dataset_factory=dataset_factory,
-        parsing_mode=parsing_mode,
-    )
+    adapter = adapter_class(options=options)
     decoder = Decoder(adapter=adapter)
     for frame in frames:
-        ds = decoder.decode_frame(frame)
-        if ds is not None:
-            yield ds
-
-    if parsing_mode is ParsingMode.FLAT:
-        yield adapter.dataset
+        yield decoder.iter_rows(frame)
+    return
 
 
 def parse_jelly_grouped(
     inp: IO[bytes],
-    graph_factory: Callable[[], Graph],
-    dataset_factory: Callable[[], Dataset],
-) -> Generator[Any] | Generator[Graph] | Generator[Dataset]:
+    graph_factory: Callable[[], Graph] = lambda: Graph(),
+    dataset_factory: Callable[[], Dataset] = lambda: Dataset(),
+) -> Generator[Graph] | Generator[Dataset]:
     """
     Take jelly file and return generators based on the detected logical type.
 
@@ -295,38 +321,52 @@ def parse_jelly_grouped(
 
     Args:
         inp (IO[bytes]): input jelly buffered binary stream
-        graph_factory (Callable): lambda to construct a Graph
-        dataset_factory (Callable): lambda to construct a Dataset
+        graph_factory (Callable): lambda to construct a Graph.
+            By default creates an empty in-memory Graph,
+            but you can pass something else here.
+        dataset_factory (Callable): lambda to construct a Dataset.
+            By default creates an empty in-memory Dataset,
+            but you can pass something else here.
 
     Raises:
         NotImplementedError: is raised if a logical type is not implemented
 
     Yields:
-        Generator[Any] | Generator[Dataset] | Generator[Graph]:
+        Generator[Graph] | Generator[Dataset]:
             returns generators for graphs/datasets based on the type of input
 
     """
     options, frames = get_options_and_frames(inp)
-
     if options.stream_types.physical_type == jelly.PHYSICAL_STREAM_TYPE_TRIPLES:
-        yield from parse_triples_stream(
+        for graph in parse_triples_stream(
             frames=frames,
             options=options,
-            graph_factory=graph_factory,
-            parsing_mode=ParsingMode.GROUPED,
-        )
+        ):
+            sink = graph_factory()
+            for graph_item in graph:
+                if isinstance(graph_item, Prefix):
+                    sink.bind(graph_item.prefix, graph_item.iri)
+                else:
+                    sink.add(graph_item)
+            yield sink
         return
-
-    if options.stream_types.physical_type in (
+    elif options.stream_types.physical_type in (
         jelly.PHYSICAL_STREAM_TYPE_QUADS,
         jelly.PHYSICAL_STREAM_TYPE_GRAPHS,
     ):
-        yield from parse_quads_stream(
+        for dataset in parse_quads_stream(
             frames=frames,
             options=options,
-            dataset_factory=dataset_factory,
-            parsing_mode=ParsingMode.GROUPED,
-        )
+        ):
+            sink = dataset_factory()
+            for item in dataset:
+                if isinstance(item, Prefix):
+                    sink.bind(item.prefix, item.iri)
+                else:
+                    s, p, o, graph_name = item
+                    context = sink.get_context(graph_name)
+                    sink.add((s, p, o, context))
+            yield sink
         return
 
     physical_type_name = jelly.PhysicalStreamType.Name(
@@ -336,50 +376,89 @@ def parse_jelly_grouped(
     raise NotImplementedError(msg)
 
 
+def parse_jelly_to_graph(
+    inp: IO[bytes],
+    graph_factory: Callable[[], Graph] = lambda: Graph(),
+    dataset_factory: Callable[[], Dataset] = lambda: Dataset(),
+) -> Graph | Dataset:
+    """
+    Add statements from Generator to provided Graph/Dataset.
+
+    Args:
+        inp (IO[bytes]): input jelly stream.
+        graph_factory (Callable[[], Graph]): factory to create Graph.
+            By default creates an empty in-memory Graph,
+            but you can pass something else here.
+        dataset_factory (Callable[[], Dataset]): factory to create Dataset.
+            By default creates an empty in-memory Dataset,
+            but you can pass something else here.
+
+    Returns:
+        Dataset | Graph: Dataset or Graph with statements.
+
+    """
+    options, frames = get_options_and_frames(inp)
+
+    if options.stream_types.physical_type == jelly.PHYSICAL_STREAM_TYPE_TRIPLES:
+        sink = graph_factory()
+    if options.stream_types.physical_type in (
+        jelly.PHYSICAL_STREAM_TYPE_QUADS,
+        jelly.PHYSICAL_STREAM_TYPE_GRAPHS,
+    ):
+        quad_sink = dataset_factory()
+        sink = quad_sink
+
+    for item in parse_jelly_flat(inp=inp, frames=frames, options=options):
+        if isinstance(item, Prefix):
+            sink.bind(item.prefix, item.iri)
+        if isinstance(item, Triple):
+            sink.add(item)
+        if isinstance(item, Quad):
+            s, p, o, graph_name = item
+            context = quad_sink.get_context(graph_name)
+            quad_sink.add((s, p, o, context))
+    return sink
+
+
 def parse_jelly_flat(
     inp: IO[bytes],
-    graph_factory: Callable[[], Graph],
-    dataset_factory: Callable[[], Dataset],
-) -> Any | Dataset | Graph:
+    frames: Iterable[jelly.RdfStreamFrame] | None = None,
+    options: ParserOptions | None = None,
+) -> Generator[Statement | Prefix]:
     """
-    Parse jelly file with FLAT physical type into one Graph/Dataset.
+    Parse jelly file with FLAT physical type into a Generator of stream events.
 
     Args:
-        inp (IO[bytes]): input jelly buffered binary stream
-        graph_factory (Callable): lambda to construct a Graph
-        dataset_factory (Callable): lambda to construct a Dataset
+        inp (IO[bytes]): input jelly buffered binary stream.
+        frames (Iterable[jelly.RdfStreamFrame | None):
+            jelly frames if read before.
+        options (ParserOptions | None): stream options
+            if read before.
 
     Raises:
         NotImplementedError: if physical type is not supported
 
-    Returns:
-        RDFLib Graph or Dataset
+    Yields:
+        Generator[Statement | Prefix]: Generator of stream events
 
     """
-    options, frames = get_options_and_frames(inp)
+    if not frames or not options:
+        options, frames = get_options_and_frames(inp)
 
     if options.stream_types.physical_type == jelly.PHYSICAL_STREAM_TYPE_TRIPLES:
-        return next(
-            parse_triples_stream(
-                frames=frames,
-                options=options,
-                graph_factory=graph_factory,
-                parsing_mode=ParsingMode.FLAT,
-            )
-        )
-
+        for triples in parse_triples_stream(frames=frames, options=options):
+            yield from triples
+        return
     if options.stream_types.physical_type in (
         jelly.PHYSICAL_STREAM_TYPE_QUADS,
         jelly.PHYSICAL_STREAM_TYPE_GRAPHS,
     ):
-        return next(
-            parse_quads_stream(
-                frames=frames,
-                options=options,
-                dataset_factory=dataset_factory,
-                parsing_mode=ParsingMode.FLAT,
-            )
-        )
+        for quads in parse_quads_stream(
+            frames=frames,
+            options=options,
+        ):
+            yield from quads
+        return
     physical_type_name = jelly.PhysicalStreamType.Name(
         options.stream_types.physical_type
     )
@@ -404,7 +483,7 @@ class RDFLibJellyParser(RDFLibParser):
         if inp is None:
             msg = "expected source to be a stream of bytes"
             raise TypeError(msg)
-        parse_jelly_flat(
+        parse_jelly_to_graph(
             inp,
             graph_factory=lambda: Graph(store=sink.store, identifier=sink.identifier),
             dataset_factory=lambda: Dataset(store=sink.store),

pyjelly/integrations/rdflib/serialize.py

@@ -1,12 +1,14 @@
+# ruff: noqa: I001
 from __future__ import annotations
 
 from collections.abc import Generator
 from functools import singledispatch
-from typing import IO, Any
+from typing import Any, IO
 from typing_extensions import override
 
 import rdflib
-from rdflib.graph import DATASET_DEFAULT_GRAPH_ID, Dataset, Graph, QuotedGraph
+from rdflib import Graph
+from rdflib.graph import DATASET_DEFAULT_GRAPH_ID, Dataset, QuotedGraph
 from rdflib.serializer import Serializer as RDFLibSerializer
 
 from pyjelly import jelly
@@ -18,7 +20,7 @@ from pyjelly.serialize.streams import (
     SerializerOptions,
     Stream,
     TripleStream,
-)
+)  # ruff: enable
 
 
 class RDFLibTermEncoder(TermEncoder):
@@ -61,7 +63,10 @@ def namespace_declarations(store: Graph, stream: Stream) -> None:
 
 
 @singledispatch
-def stream_frames(stream: Stream, data: Graph) -> Generator[jelly.RdfStreamFrame]:  # noqa: ARG001
+def stream_frames(
+    stream: Stream,
+    data: Graph,  # noqa: ARG001
+) -> Generator[jelly.RdfStreamFrame]:
     msg = f"invalid stream implementation {stream}"
     raise TypeError(msg)
 
@@ -165,6 +170,48 @@ def graphs_stream_frames(
         yield frame
 
 
+def guess_options(sink: Graph | Dataset) -> SerializerOptions:
+    """
+    Guess the serializer options based on the store type.
+
+    >>> guess_options(Graph()).logical_type
+    1
+    >>> guess_options(Dataset()).logical_type
+    2
+    """
+    logical_type = (
+        jelly.LOGICAL_STREAM_TYPE_FLAT_QUADS
+        if isinstance(sink, Dataset)
+        else jelly.LOGICAL_STREAM_TYPE_FLAT_TRIPLES
+    )
+    return SerializerOptions(logical_type=logical_type)
+
+
+def guess_stream(options: SerializerOptions, sink: Graph | Dataset) -> Stream:
+    """
+    Return an appropriate stream implementation for the given options.
+
+    Notes: if base(!) logical type is GRAPHS and Dataset is given,
+        initializes TripleStream
+
+    >>> graph_ser = RDFLibJellySerializer(Graph())
+    >>> ds_ser = RDFLibJellySerializer(Dataset())
+
+    >>> type(guess_stream(guess_options(graph_ser.store), graph_ser.store))
+    <class 'pyjelly.serialize.streams.TripleStream'>
+    >>> type(guess_stream(guess_options(ds_ser.store), ds_ser.store))
+    <class 'pyjelly.serialize.streams.QuadStream'>
+    """
+    stream_cls: type[Stream]
+    if (options.logical_type % 10) != jelly.LOGICAL_STREAM_TYPE_GRAPHS and isinstance(
+        sink, Dataset
+    ):
+        stream_cls = QuadStream
+    else:
+        stream_cls = TripleStream
+    return stream_cls.for_rdflib(options=options)
+
+
 class RDFLibJellySerializer(RDFLibSerializer):
     """
     RDFLib serializer for writing graphs in Jelly RDF stream format.
@@ -180,43 +227,6 @@ class RDFLibJellySerializer(RDFLibSerializer):
             raise NotImplementedError(msg)
         super().__init__(store)
 
-    def guess_options(self) -> SerializerOptions:
-        """
-        Guess the serializer options based on the store type.
-
-        >>> RDFLibJellySerializer(Graph()).guess_options().logical_type
-        1
-        >>> RDFLibJellySerializer(Dataset()).guess_options().logical_type
-        2
-        """
-        logical_type = (
-            jelly.LOGICAL_STREAM_TYPE_FLAT_QUADS
-            if isinstance(self.store, Dataset)
-            else jelly.LOGICAL_STREAM_TYPE_FLAT_TRIPLES
-        )
-        return SerializerOptions(logical_type=logical_type)
-
-    def guess_stream(self, options: SerializerOptions) -> Stream:
-        """
-        Return an appropriate stream implementation for the given options.
-
-        >>> graph_ser = RDFLibJellySerializer(Graph())
-        >>> ds_ser = RDFLibJellySerializer(Dataset())
-
-        >>> type(graph_ser.guess_stream(graph_ser.guess_options()))
-        <class 'pyjelly.serialize.streams.TripleStream'>
-        >>> type(ds_ser.guess_stream(ds_ser.guess_options()))
-        <class 'pyjelly.serialize.streams.QuadStream'>
-        """
-        stream_cls: type[Stream]
-        if options.logical_type != jelly.LOGICAL_STREAM_TYPE_GRAPHS and isinstance(
-            self.store, Dataset
-        ):
-            stream_cls = QuadStream
-        else:
-            stream_cls = TripleStream
-        return stream_cls.for_rdflib(options=options)
-
     @override
     def serialize(  # type: ignore[override]
         self,
@@ -240,9 +250,56 @@ class RDFLibJellySerializer(RDFLibSerializer):
 
         """
         if options is None:
-            options = self.guess_options()
+            options = guess_options(self.store)
         if stream is None:
-            stream = self.guess_stream(options)
+            stream = guess_stream(options, self.store)
         write = write_delimited if stream.options.params.delimited else write_single
         for stream_frame in stream_frames(stream, self.store):
             write(stream_frame, out)
+
+
+def grouped_stream_to_frames(
+    sink_generator: Generator[Graph] | Generator[Dataset],
+    options: SerializerOptions | None = None,
+) -> Generator[jelly.RdfStreamFrame]:
+    """
+    Transform Graphs/Datasets into Jelly frames, one frame per Graph/Dataset.
+
+    Note: options are guessed if not provided.
+
+    Args:
+        sink_generator (Generator[Graph] | Generator[Dataset]): Generator of
+            Graphs/Dataset to transform.
+        options (SerializerOptions | None, optional): stream options to use.
+            Options are guessed based on the sink store type. Defaults to None.
+
+    Yields:
+        Generator[jelly.RdfStreamFrame]: produced Jelly frames
+
+    """
+    stream = None
+    for sink in sink_generator:
+        if not stream:
+            if options is None:
+                options = guess_options(sink)
+            stream = guess_stream(options, sink)
+        yield from stream_frames(stream, sink)
+
+
+def grouped_stream_to_file(
+    stream: Generator[Graph] | Generator[Dataset],
+    output_file: IO[bytes],
+    **kwargs: Any,
+) -> None:
+    """
+    Write stream of Graphs/Datasets to a binary file.
+
+    Args:
+        stream (Generator[Graph] | Generator[Dataset]): Generator of
+            Graphs/Dataset to transform.
+        output_file (IO[bytes]): opened output file.
+        **kwargs (Any): options to pass to stream.
+
+    """
+    for frame in grouped_stream_to_frames(stream, **kwargs):
+        write_delimited(frame, output_file)

pyjelly/jelly/rdf_pb2.py

@@ -2,7 +2,7 @@
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # NO CHECKED-IN PROTOBUF GENCODE
 # source: rdf.proto
-# Protobuf Python Version: 5.29.0
+# Protobuf Python Version: 6.31.0
 """Generated protocol buffer code."""
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import descriptor_pool as _descriptor_pool
@@ -11,8 +11,8 @@ from google.protobuf import symbol_database as _symbol_database
 from google.protobuf.internal import builder as _builder
 _runtime_version.ValidateProtobufRuntimeVersion(
     _runtime_version.Domain.PUBLIC,
-    5,
-    29,
+    6,
+    31,
     0,
     '',
     'rdf.proto'

pyjelly/jelly/rdf_pb2.pyi

@@ -2,7 +2,8 @@ from google.protobuf.internal import containers as _containers
 from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import message as _message
-from typing import ClassVar as _ClassVar, Iterable as _Iterable, Mapping as _Mapping, Optional as _Optional, Union as _Union
+from collections.abc import Iterable as _Iterable, Mapping as _Mapping
+from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
 
 DESCRIPTOR: _descriptor.FileDescriptor
 

pyjelly/parse/decode.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from abc import ABCMeta, abstractmethod
-from collections.abc import Iterable, Sequence
+from collections.abc import Iterable, Iterator, Sequence
 from enum import Enum, auto
 from typing import Any, ClassVar, NamedTuple
 from typing_extensions import Never
@@ -166,23 +166,23 @@ class Decoder:
     def options(self) -> ParserOptions:
         return self.adapter.options
 
-    def decode_frame(self, frame: jelly.RdfStreamFrame) -> Any:
+    def iter_rows(self, frame: jelly.RdfStreamFrame) -> Iterator[Any]:
         """
-        Decode a frame to custom object based on adapter implementation.
+        Iterate through rows in the frame.
 
         Args:
             frame (jelly.RdfStreamFrame): jelly frame
-
-        Returns:
-            Any: custom obj based on adapter logic
+        Yields:
+            Iterator[Any]: decoded rows
 
         """
         for row_owner in frame.rows:
             row = getattr(row_owner, row_owner.WhichOneof("row"))
-            self.decode_row(row)
-        if self.adapter.parsing_mode is ParsingMode.GROUPED:
-            return self.adapter.frame()
-        return None
+            decoded_row = self.decode_row(row)
+            if isinstance(
+                row, (jelly.RdfTriple, jelly.RdfQuad, jelly.RdfNamespaceDeclaration)
+            ):
+                yield decoded_row
 
     def decode_row(self, row: Any) -> Any | None:
         """

pyjelly/parse/ioutils.py

@@ -55,8 +55,7 @@ def delimited_jelly_hint(header: bytes) -> bool:
 
 def frame_iterator(inp: IO[bytes]) -> Generator[jelly.RdfStreamFrame]:
     while frame := parse_length_prefixed(jelly.RdfStreamFrame, inp):
-        if frame.rows:
-            yield frame
+        yield frame
 
 
 def get_options_and_frames(
@@ -82,14 +81,21 @@ def get_options_and_frames(
     inp.seek(-len(bytes_read), os.SEEK_CUR)
 
     if is_delimited:
+        first_frame = None
+        skipped_frames = []
         frames = frame_iterator(inp)
-        first_frame = next(frames, None)
+        for frame in frames:
+            if not frame.rows:
+                skipped_frames.append(frame)
+            else:
+                first_frame = frame
+                break
         if first_frame is None:
             msg = "No non-empty frames found in the stream"
             raise JellyConformanceError(msg)
 
         options = options_from_frame(first_frame, delimited=True)
-        return options, chain((first_frame,), frames)
+        return options, chain(skipped_frames, (first_frame,), frames)
 
     frame = parse(jelly.RdfStreamFrame, inp.read())
 

pyjelly/serialize/flows.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from collections import UserList
 from collections.abc import Iterable
 from dataclasses import dataclass
-from typing import ClassVar
+from typing import Any, ClassVar
 from typing_extensions import override
 
 from pyjelly import jelly
@@ -16,11 +16,24 @@ class FrameFlow(UserList[jelly.RdfStreamRow]):
     Abstract base class for producing Jelly frames from RDF stream rows.
 
     Collects stream rows and assembles them into RdfStreamFrame objects when ready.
+
+    Allows for passing LogicalStreamType, required for
+        logical subtypes and non-delimited streams.
     """
 
     logical_type: jelly.LogicalStreamType
     registry: ClassVar[dict[jelly.LogicalStreamType, type[FrameFlow]]] = {}
 
+    def __init__(
+        self,
+        initlist: Iterable[jelly.RdfStreamRow] | None = None,
+        *,
+        logical_type: jelly.LogicalStreamType | None = None,
+        **__kwargs: Any,
+    ) -> None:
+        super().__init__(initlist)
+        self.logical_type = logical_type or self.__class__.logical_type
+
     def frame_from_graph(self) -> jelly.RdfStreamFrame | None:
         """
         Treat the current rows as a graph and produce a frame.
@@ -71,15 +84,6 @@ class ManualFrameFlow(FrameFlow):
 
     logical_type = jelly.LOGICAL_STREAM_TYPE_UNSPECIFIED
 
-    def __init__(
-        self,
-        initlist: Iterable[jelly.RdfStreamRow] | None = None,
-        *,
-        logical_type: jelly.LogicalStreamType = jelly.LOGICAL_STREAM_TYPE_UNSPECIFIED,
-    ) -> None:
-        super().__init__(initlist)
-        self.logical_type = logical_type
-
 
 @dataclass
 class BoundedFrameFlow(FrameFlow):
@@ -92,13 +96,15 @@ class BoundedFrameFlow(FrameFlow):
     logical_type = jelly.LOGICAL_STREAM_TYPE_UNSPECIFIED
     frame_size: int
 
+    @override
     def __init__(
         self,
         initlist: Iterable[jelly.RdfStreamRow] | None = None,
+        logical_type: jelly.LogicalStreamType | None = None,
         *,
         frame_size: int | None = None,
     ) -> None:
-        super().__init__(initlist)
+        super().__init__(initlist, logical_type=logical_type)
         self.frame_size = frame_size or DEFAULT_FRAME_SIZE
 
     @override
@@ -153,7 +159,6 @@ class DatasetsFrameFlow(FrameFlow):
         return self.to_stream_frame()
 
 
-# TODO(Nastya): issue #184
 FLOW_DISPATCH: dict[jelly.LogicalStreamType, type[FrameFlow]] = {
     jelly.LOGICAL_STREAM_TYPE_FLAT_TRIPLES: FlatTriplesFrameFlow,
     jelly.LOGICAL_STREAM_TYPE_FLAT_QUADS: FlatQuadsFrameFlow,
@@ -166,18 +171,23 @@ def flow_for_type(logical_type: jelly.LogicalStreamType) -> type[FrameFlow]:
     """
     Return flow based on logical type requested.
 
+    Note: uses base logical type for subtypes (i.e., SUBJECT_GRAPHS uses
+        the same flow as its base type GRAPHS).
+
     Args:
         logical_type (jelly.LogicalStreamType): logical type requested.
 
     Raises:
-        NotImplementedError: if logical type not supported.
+        NotImplementedError: if (base) logical stream type is not supported.
 
     Returns:
         type[FrameFlow]: FrameFlow for respective logical type.
 
     """
     try:
-        return FLOW_DISPATCH[logical_type]
+        base_logical_type_value = logical_type % 10
+        base_name = jelly.LogicalStreamType.Name(base_logical_type_value)
+        return FLOW_DISPATCH[getattr(jelly.LogicalStreamType, base_name)]
     except KeyError:
         msg = (
             "unsupported logical stream type: "

pyjelly/serialize/streams.py

@@ -78,9 +78,12 @@ class Stream:
                 jelly.LOGICAL_STREAM_TYPE_FLAT_TRIPLES,
                 jelly.LOGICAL_STREAM_TYPE_FLAT_QUADS,
             ):
-                flow = flow_class(frame_size=self.options.frame_size)  # type: ignore[call-overload]
+                flow = flow_class(
+                    logical_type=self.options.logical_type,
+                    frame_size=self.options.frame_size,
+                )
             else:
-                flow = flow_class()
+                flow = flow_class(logical_type=self.options.logical_type)
         else:
             flow = ManualFrameFlow(logical_type=self.options.logical_type)
         return flow

{pyjelly-0.3.0.dist-info → pyjelly-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyjelly
-Version: 0.3.0
+Version: 0.4.0
 Summary: Jelly-RDF implementation for Python
 Project-URL: Homepage, https://w3id.org/jelly/pyjelly
 Project-URL: Documentation, https://w3id.org/jelly/pyjelly
@@ -28,7 +28,7 @@ Classifier: Topic :: File Formats
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
-Requires-Dist: protobuf>=5.29.3
+Requires-Dist: protobuf>=6.30.0
 Requires-Dist: typing-extensions>=4.12.2
 Provides-Extra: rdflib
 Requires-Dist: rdflib>=7.1.4; extra == 'rdflib'
@@ -50,13 +50,13 @@ Description-Content-Type: text/markdown
 
 ## Getting started
 
-To get started with pyjelly, you can install it via pip:
+Install pyjelly from **[PyPI](https://pypi.org/project/pyjelly/)**:
 
 ```bash
 pip install pyjelly[rdflib]
 ```
 
-To write an RDF graph to a Jelly file, you can use the following code:
+To write an RDF graph to a Jelly file:
 
 ```python
 from rdflib import Graph
@@ -66,7 +66,7 @@ g.parse("http://xmlns.com/foaf/spec/index.rdf")
 g.serialize(destination="foaf.jelly", format="jelly")
 ```
 
-To read a Jelly file and convert it to an rdflib Graph, you can use:
+To read a Jelly file and convert it to an rdflib `Graph`:
 
 ```python
 from rdflib import Graph
@@ -75,19 +75,19 @@ g = Graph()
 g.parse("foaf.jelly", format="jelly")
 ```
 
-**See more examples, [API reference](https://w3id.org/jelly/pyjelly/dev/api), and more in the [documentation](https://w3id.org/jelly/pyjelly).**
+**See [our documentation](https://w3id.org/jelly/pyjelly) for [further examples](https://w3id.org/jelly/pyjelly/dev/getting-started/), a full [API reference](https://w3id.org/jelly/pyjelly/dev/api), and more.**
 
 ## Contributing and support
 
 This project is being actively developed – you can stay tuned by [watching this repository](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications#subscription-options).
 
-You can also join the **[Jelly Discord chat](https://discord.gg/A8sN5XwVa5)** to ask questions about pyjelly and to be up-to-date with the development activities.
+Join the **[Jelly Discord chat](https://discord.gg/A8sN5XwVa5)** to ask questions about pyjelly and to be up-to-date with the development activities.
 
 ### Commercial support
 
 **[NeverBlink](https://neverblink.eu)** provides commercial support services for Jelly, including implementing custom features, system integrations, implementations for new frameworks, benchmarking, and more.
 
-## Contributing
+### Contributing
 
 If you'd like to contribute, check out our [contributing guidelines](CONTRIBUTING.md).
 

{pyjelly-0.3.0.dist-info → pyjelly-0.4.0.dist-info}/RECORD

@@ -6,23 +6,23 @@ pyjelly/_proto/patch.proto,sha256=gASUm0xDG9J1advNoq_cCsJYxudTbQaiZQBq4oW3kw4,52
 pyjelly/_proto/rdf.proto,sha256=EKxyG421B4m0Wx5-6jjojdga_hA3jpZfF6-T3lMc0hI,12763
 pyjelly/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pyjelly/integrations/rdflib/__init__.py,sha256=lpIz6iildMf5bDvj3aBqZJ7kgKFrTx_tsqSb6PkLis0,552
-pyjelly/integrations/rdflib/parse.py,sha256=wbWyWgFVtxZsftx5v8zYDGUo2e-HuYpppzARil8CFwI,11974
-pyjelly/integrations/rdflib/serialize.py,sha256=Hr8DuXPtv59WSl__D2wodpbPefTuhLwPqf7tcQ6VFUU,8001
+pyjelly/integrations/rdflib/parse.py,sha256=_H4f5qUU0IvMPaq1Tnm2UF1aXX-DY1qPn_7GmoIa4V0,13717
+pyjelly/integrations/rdflib/serialize.py,sha256=etFY10HjmsjmuR6BjvWw32f2zBThW26mTGFn67jcOdc,9524
 pyjelly/jelly/__init__.py,sha256=9kacwn8Ew_1fcgj1abz6miEz-AtUdPT2ltFWaRIE5VE,126
-pyjelly/jelly/rdf_pb2.py,sha256=L_fPtDaURFCpLIMqVdl4RwiWyVgEFOwtB4-If3MpoSg,8952
-pyjelly/jelly/rdf_pb2.pyi,sha256=-Vv2HlpUWhaKPEb0YXOTx21cIKoqoBmTY8U6HPMUcLw,11789
+pyjelly/jelly/rdf_pb2.py,sha256=qjgS3kQnCJqoOmgzvgk1BeYxGbeDX2zygJPc2vDjRts,8952
+pyjelly/jelly/rdf_pb2.pyi,sha256=-gxZO-r2wyN68l83XomySz60c82SZmoPKh1HxamBjZs,11816
 pyjelly/parse/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pyjelly/parse/decode.py,sha256=ss7tCUA9klcYRfeUPxTgISL700b9cdkcuNeAk1AE8XQ,13271
-pyjelly/parse/ioutils.py,sha256=DLAxb4WlFUkWJOeqVhfJYlY9afVv4YFF7SbI5WqmmaQ,3250
+pyjelly/parse/decode.py,sha256=ERgCLzBvbkJWTlg3RT0p-h8J60KNqpQ4mj_-JHoD7kg,13299
+pyjelly/parse/ioutils.py,sha256=O3wRtL5tf1WyIZ1LTfHjHwjKEGrhIWqFisOWjYmspNg,3434
 pyjelly/parse/lookup.py,sha256=1AbdZEycLC4tRfh3fgF5hv5PrhwhdWvCUC53iHt-E4c,2193
 pyjelly/serialize/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pyjelly/serialize/encode.py,sha256=WSeqxyBtxpMrWrefhnmNLf8ummzlT0rY7NKoUzFY8NQ,9498
-pyjelly/serialize/flows.py,sha256=6jJNp4oYWmV0O_jqeashOqzWH5Rpke9ix4hqa88b22Q,5010
+pyjelly/serialize/flows.py,sha256=0C2soigJKyHr3xoR-7v0kc1RL8COwnuCRd4iVZpukFU,5524
 pyjelly/serialize/ioutils.py,sha256=2_NaadLfHO3jKR1ZV7aK6jQ09sPKBar9iLFHYwourz8,400
 pyjelly/serialize/lookup.py,sha256=h0lYFjdB6CIuN2DzAW6EE4ILJFUuto3paAK6DG1DZYg,4091
-pyjelly/serialize/streams.py,sha256=FPgYAxwnI99uXAkg6Gl2O9p-akawHDLmB2OuUEczhUU,8315
-pyjelly-0.3.0.dist-info/METADATA,sha256=6Nr1CC-LWE7HjAfeN3ESJG5ZE7lpWC-5rAc8Ci2eeak,4585
-pyjelly-0.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pyjelly-0.3.0.dist-info/entry_points.txt,sha256=kUG0p9zso7HpitdMaQaXEj_KSqgOGsL0Ky9ARbecN1g,339
-pyjelly-0.3.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-pyjelly-0.3.0.dist-info/RECORD,,
+pyjelly/serialize/streams.py,sha256=F_T3k9yLSPtUW2ZaL99hmjlPKmgG4nYNeNXUiee3jEY,8421
+pyjelly-0.4.0.dist-info/METADATA,sha256=iLIzLhRWIN9fj1Fua45fBosWbLS1bQOnLZmVsGbfFQw,4607
+pyjelly-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pyjelly-0.4.0.dist-info/entry_points.txt,sha256=kUG0p9zso7HpitdMaQaXEj_KSqgOGsL0Ky9ARbecN1g,339
+pyjelly-0.4.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pyjelly-0.4.0.dist-info/RECORD,,