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

pyjelly/integrations/generic/generic_sink.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Generator
+from typing import IO, NamedTuple, Union
+
+DEFAULT_GRAPH_IDENTIFIER = ""
+
+
+class BlankNode:
+    """Class for blank nodes, storing BN's identifier as a string."""
+
+    def __init__(self, identifier: str) -> None:
+        self._identifier: str = identifier
+
+    def __str__(self) -> str:
+        return f"_:{self._identifier}"
+
+    def __repr__(self) -> str:
+        return f"BlankNode(identifier={self._identifier})"
+
+
+class IRI:
+    """Class for IRIs, storing IRI as a string."""
+
+    def __init__(self, iri: str) -> None:
+        self._iri: str = iri
+
+    def __str__(self) -> str:
+        return f"<{self._iri}>"
+
+    def __repr__(self) -> str:
+        return f"IRI({self._iri})"
+
+
+class Literal:
+    """
+    Class for literals.
+
+    Notes:
+        Consists of: lexical form, and optional language tag and datatype.
+        All parts of literal are stored as strings.
+
+    """
+
+    def __init__(
+        self, lex: str, langtag: str | None = None, datatype: str | None = None
+    ) -> None:
+        self._lex: str = lex
+        self._langtag: str | None = langtag
+        self._datatype: str | None = datatype
+
+    def __str__(self) -> str:
+        suffix = ""
+        if self._langtag:
+            suffix = f"@{self._langtag}"
+        elif self._datatype:
+            suffix = f"^^<{self._datatype}>"
+        return f'"{self._lex}"{suffix}'
+
+    def __repr__(self) -> str:
+        return (
+            f"Literal({self._lex!r}, langtag={self._langtag!r}, "
+            f"datatype={self._datatype!r})"
+        )
+
+
+Node = Union[BlankNode, IRI, Literal, "Triple", str]
+
+
+TRIPLE_ARITY = 3
+
+
+class Triple(NamedTuple):
+    """Class for RDF triples."""
+
+    s: Node
+    p: Node
+    o: Node
+
+
+class Quad(NamedTuple):
+    """Class for RDF quads."""
+
+    s: Node
+    p: Node
+    o: Node
+    g: Node
+
+
+class Prefix(NamedTuple):
+    """Class for generic namespace declaration."""
+
+    prefix: str
+    iri: IRI
+
+
+class GenericStatementSink:
+    _store: deque[Triple | Quad]
+
+    def __init__(self, identifier: Node = DEFAULT_GRAPH_IDENTIFIER) -> None:
+        """
+        Initialize statements storage, namespaces dictionary, and parser.
+
+        Notes:
+            _store preserves the order of statements.
+
+        Args:
+            identifier (str, optional): Identifier for a sink.
+                Defaults to DEFAULT_GRAPH_IDENTIFIER.
+
+        """
+        self._store: deque[Triple | Quad] = deque()
+        self._namespaces: dict[str, IRI] = {}
+        self._identifier = identifier
+
+    def add(self, statement: Triple | Quad) -> None:
+        self._store.append(statement)
+
+    def bind(self, prefix: str, namespace: IRI) -> None:
+        self._namespaces.update({prefix: namespace})
+
+    def __iter__(self) -> Generator[Triple | Quad]:
+        yield from self._store
+
+    def __len__(self) -> int:
+        return len(self._store)
+
+    @property
+    def namespaces(self) -> Generator[tuple[str, IRI]]:
+        yield from self._namespaces.items()
+
+    @property
+    def identifier(self) -> Node:
+        return self._identifier
+
+    @property
+    def store(self) -> Generator[Triple | Quad]:
+        yield from self._store
+
+    @property
+    def is_triples_sink(self) -> bool:
+        """
+        Check if the sink contains triples or quads.
+
+        Returns:
+            bool: true, if length of statement is 3.
+
+        """
+        return len(self._store[0]) == TRIPLE_ARITY
+
+    def parse(self, input_file: IO[bytes]) -> None:
+        from pyjelly.integrations.generic.parse import parse_jelly_to_graph
+
+        parsed_result = parse_jelly_to_graph(input_file)
+        self._store = parsed_result._store
+        self._namespaces = parsed_result._namespaces
+        self._identifier = parsed_result._identifier
+
+    def serialize(self, output_file: IO[bytes]) -> None:
+        from pyjelly.integrations.generic.serialize import grouped_stream_to_file
+
+        grouped_stream_to_file((sink for sink in [self]), output_file)

pyjelly/integrations/generic/parse.py

@@ -0,0 +1,339 @@
+from __future__ import annotations
+
+from collections.abc import Generator, Iterable
+from itertools import chain
+from typing import IO, Any, Callable, Union
+from typing_extensions import override
+
+from pyjelly import jelly
+from pyjelly.errors import JellyConformanceError
+from pyjelly.integrations.generic.generic_sink import (
+    IRI,
+    BlankNode,
+    GenericStatementSink,
+    Literal,
+    Prefix,
+    Quad,
+    Triple,
+)
+from pyjelly.parse.decode import Adapter, Decoder, ParserOptions
+from pyjelly.parse.ioutils import get_options_and_frames
+
+Statement = Union[Triple, Quad]
+
+
+class GenericStatementSinkAdapter(Adapter):
+    """
+    Implement Adapter for generic statements.
+
+    Notes:
+        Returns custom RDF terms expected by GenericStatementSink,
+        handles namespace declarations, and quoted triples.
+
+    Args:
+        Adapter (_type_): base Adapter class
+
+    """
+
+    @override
+    def iri(self, iri: str) -> IRI:
+        return IRI(iri)
+
+    @override
+    def bnode(self, bnode: str) -> BlankNode:
+        return BlankNode(bnode)
+
+    @override
+    def default_graph(self) -> str:
+        return ""
+
+    @override
+    def literal(
+        self,
+        lex: str,
+        language: str | None = None,
+        datatype: str | None = None,
+    ) -> Literal:
+        return Literal(lex, language, datatype)
+
+    @override
+    def namespace_declaration(self, name: str, iri: str) -> Prefix:
+        return Prefix(name, self.iri(iri))
+
+    @override
+    def quoted_triple(self, terms: Iterable[Any]) -> Triple:
+        return Triple(*terms)
+
+
+class GenericTriplesAdapter(GenericStatementSinkAdapter):
+    """
+    Triples adapted implementation for GenericStatementSink.
+
+    Args:
+        GenericStatementSinkAdapter (_type_): base GenericStatementSink
+            adapter implementation that handles terms and namespaces.
+
+    """
+
+    def __init__(
+        self,
+        options: ParserOptions,
+    ) -> None:
+        super().__init__(options=options)
+
+    @override
+    def triple(self, terms: Iterable[Any]) -> Triple:
+        return Triple(*terms)
+
+
+class GenericQuadsBaseAdapter(GenericStatementSinkAdapter):
+    def __init__(self, options: ParserOptions) -> None:
+        super().__init__(options=options)
+
+
+class GenericQuadsAdapter(GenericQuadsBaseAdapter):
+    """
+    Extends GenericQuadsBaseAdapter for QUADS physical type.
+
+    Args:
+        GenericQuadsBaseAdapter (_type_): quads adapter that handles
+            base quads processing.
+
+    """
+
+    @override
+    def quad(self, terms: Iterable[Any]) -> Quad:
+        return Quad(*terms)
+
+
+class GenericGraphsAdapter(GenericQuadsBaseAdapter):
+    """
+    Extends GenericQuadsBaseAdapter for GRAPHS physical type.
+
+    Notes:
+        introduces graph start/end, checks if graph exists.
+
+    Args:
+        GenericQuadsBaseAdapter (_type_): quads adapter that handles
+            base quads processing.
+
+    Raises:
+        JellyConformanceError: raised if graph start message was not received.
+
+    """
+
+    _graph_id: str | None
+
+    def __init__(
+        self,
+        options: ParserOptions,
+    ) -> None:
+        super().__init__(options=options)
+        self._graph_id = None
+
+    @property
+    def graph(self) -> None:
+        if self._graph_id is None:
+            msg = "new graph was not started"
+            raise JellyConformanceError(msg)
+
+    @override
+    def graph_start(self, graph_id: str) -> None:
+        self._graph_id = graph_id
+
+    @override
+    def triple(self, terms: Iterable[Any]) -> Quad:
+        return Quad(*chain(terms, [self._graph_id]))
+
+    @override
+    def graph_end(self) -> None:
+        self._graph_id = None
+
+
+def parse_triples_stream(
+    frames: Iterable[jelly.RdfStreamFrame],
+    options: ParserOptions,
+) -> Generator[Iterable[Triple | Prefix]]:
+    """
+    Parse flat triple stream.
+
+    Args:
+        frames (Iterable[jelly.RdfStreamFrame]): iterator over stream frames
+        options (ParserOptions): stream options
+
+    Yields:
+        Generator[Iterable[Triple | Prefix]]:
+            Generator of iterables of Triple or Prefix objects,
+            one iterable per frame.
+
+    """
+    adapter = GenericTriplesAdapter(options)
+    decoder = Decoder(adapter=adapter)
+    for frame in frames:
+        yield decoder.iter_rows(frame)
+    return
+
+
+def parse_quads_stream(
+    frames: Iterable[jelly.RdfStreamFrame],
+    options: ParserOptions,
+) -> Generator[Iterable[Quad | Prefix]]:
+    """
+    Parse flat quads stream.
+
+    Args:
+        frames (Iterable[jelly.RdfStreamFrame]): iterator over stream frames
+        options (ParserOptions): stream options
+
+    Yields:
+        Generator[Iterable[Quad | Prefix]]:
+            Generator of iterables of Quad or Prefix objects,
+            one iterable per frame.
+
+    """
+    adapter_class: type[GenericQuadsBaseAdapter]
+    if options.stream_types.physical_type == jelly.PHYSICAL_STREAM_TYPE_QUADS:
+        adapter_class = GenericQuadsAdapter
+    else:
+        adapter_class = GenericGraphsAdapter
+    adapter = adapter_class(options=options)
+    decoder = Decoder(adapter=adapter)
+    for frame in frames:
+        yield decoder.iter_rows(frame)
+    return
+
+
+def parse_jelly_grouped(
+    inp: IO[bytes],
+    sink_factory: Callable[[], GenericStatementSink] = lambda: GenericStatementSink(),
+) -> Generator[GenericStatementSink]:
+    """
+    Take a jelly file and return generators of generic statements sinks.
+
+    Yields one generic statements sink per frame.
+
+    Args:
+        inp (IO[bytes]): input jelly buffered binary stream
+        sink_factory (Callable): lambda to construct a statement sink.
+            By default creates an empty in-memory GenericStatementSink.
+
+    Raises:
+        NotImplementedError: is raised if a physical type is not implemented
+
+    Yields:
+        Generator[GenericStatementSink]:
+            returns generators for GenericStatementSink, regardless of stream type.
+
+    """
+    options, frames = get_options_and_frames(inp)
+    if options.stream_types.physical_type == jelly.PHYSICAL_STREAM_TYPE_TRIPLES:
+        for graph in parse_triples_stream(
+            frames=frames,
+            options=options,
+        ):
+            sink = sink_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
+    elif options.stream_types.physical_type in (
+        jelly.PHYSICAL_STREAM_TYPE_QUADS,
+        jelly.PHYSICAL_STREAM_TYPE_GRAPHS,
+    ):
+        for dataset in parse_quads_stream(
+            frames=frames,
+            options=options,
+        ):
+            sink = sink_factory()
+            for item in dataset:
+                if isinstance(item, Prefix):
+                    sink.bind(item.prefix, item.iri)
+                else:
+                    sink.add(item)
+            yield sink
+        return
+
+    physical_type_name = jelly.PhysicalStreamType.Name(
+        options.stream_types.physical_type
+    )
+    msg = f"the stream type {physical_type_name} is not supported "
+    raise NotImplementedError(msg)
+
+
+def parse_jelly_to_graph(
+    inp: IO[bytes],
+    sink_factory: Callable[[], GenericStatementSink] = lambda: GenericStatementSink(),
+) -> GenericStatementSink:
+    """
+    Add statements from Generator to GenericStatementSink.
+
+    Args:
+        inp (IO[bytes]): input jelly stream.
+        sink_factory (Callable[[], GenericStatementSink]): factory to create
+            statement sink.
+            By default creates an empty in-memory GenericStatementSink.
+            Has no division for datasets/graphs,
+            utilizes the same underlying data structures.
+
+    Returns:
+        GenericStatementSink: GenericStatementSink with statements.
+
+    """
+    options, frames = get_options_and_frames(inp)
+    sink = sink_factory()
+
+    for item in parse_jelly_flat(inp=inp, frames=frames, options=options):
+        if isinstance(item, Prefix):
+            sink.bind(item.prefix, item.iri)
+        else:
+            sink.add(item)
+    return sink
+
+
+def parse_jelly_flat(
+    inp: IO[bytes],
+    frames: Iterable[jelly.RdfStreamFrame] | None = None,
+    options: ParserOptions | None = None,
+) -> Generator[Statement | Prefix]:
+    """
+    Parse jelly file with FLAT logical type into a Generator of stream events.
+
+    Args:
+        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
+
+    Yields:
+        Generator[Statement | Prefix]: Generator of stream events
+
+    """
+    if not frames or not options:
+        options, frames = get_options_and_frames(inp)
+
+    if options.stream_types.physical_type == jelly.PHYSICAL_STREAM_TYPE_TRIPLES:
+        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,
+    ):
+        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
+    )
+    msg = f"the stream type {physical_type_name} is not supported "
+    raise NotImplementedError(msg)

pyjelly/integrations/generic/serialize.py

@@ -0,0 +1,361 @@
+# ruff: noqa: I001
+from __future__ import annotations
+from typing import cast
+from collections.abc import Generator
+from functools import singledispatch
+from typing import Any, IO
+from itertools import chain
+from pyjelly.integrations.generic.generic_sink import (
+    GenericStatementSink,
+    Quad,
+    Triple,
+    DEFAULT_GRAPH_IDENTIFIER,
+    IRI,
+    BlankNode,
+    Literal,
+    Node,
+)
+
+from pyjelly import jelly
+from pyjelly.serialize.encode import RowsAndTerm, Slot, TermEncoder
+from pyjelly.serialize.ioutils import write_delimited
+from pyjelly.serialize.streams import (
+    GraphStream,
+    QuadStream,
+    SerializerOptions,
+    Stream,
+    TripleStream,
+)  # ruff: enable
+
+QUAD_ARITY = 4
+
+
+class GenericSinkTermEncoder(TermEncoder):
+    def encode_any(self, term: object, slot: Slot) -> RowsAndTerm:
+        """
+        Encode term based on its GenericSink object.
+
+        Args:
+            term (object): term to encode
+            slot (Slot): its place in statement.
+
+        Returns:
+            RowsAndTerm: encoded extra rows and a jelly term to encode
+
+        """
+        if slot is Slot.graph and term == DEFAULT_GRAPH_IDENTIFIER:
+            return self.encode_default_graph()
+
+        if isinstance(term, IRI):
+            return self.encode_iri(term._iri)
+
+        if isinstance(term, Literal):
+            return self.encode_literal(
+                lex=term._lex,
+                language=term._langtag,
+                datatype=term._datatype,
+            )
+
+        if isinstance(term, BlankNode):
+            return self.encode_bnode(term._identifier)
+
+        if isinstance(term, Triple):
+            return self.encode_quoted_triple(term)
+
+        return super().encode_any(term, slot)  # error if not handled
+
+
+def namespace_declarations(store: GenericStatementSink, stream: Stream) -> None:
+    for prefix, namespace in store.namespaces:
+        stream.namespace_declaration(name=prefix, iri=str(namespace))
+
+
+@singledispatch
+def stream_frames(
+    stream: Stream,
+    data: GenericStatementSink | Generator[Quad | Triple],  # noqa: ARG001
+) -> Generator[jelly.RdfStreamFrame]:
+    msg = f"invalid stream implementation {stream}"
+    raise TypeError(msg)
+
+
+@stream_frames.register(TripleStream)
+def triples_stream_frames(
+    stream: TripleStream,
+    data: GenericStatementSink | Generator[Triple],
+) -> Generator[jelly.RdfStreamFrame]:
+    """
+    Serialize a GenericStatementSink into frames using physical type triples stream.
+
+    Args:
+        stream (TripleStream): stream that specifies triples processing
+        data (GenericStatementSink | Generator[Triple]):
+            GenericStatementSink/Statements to serialize.
+
+    Yields:
+        Generator[jelly.RdfStreamFrame]: jelly frames.
+
+    """
+    stream.enroll()
+    if (
+        isinstance(data, GenericStatementSink)
+        and stream.options.params.namespace_declarations
+    ):
+        namespace_declarations(data, stream)
+
+    graphs = (data,)
+    for graph in graphs:
+        for terms in graph:
+            if frame := stream.triple(terms):
+                yield frame
+        if frame := stream.flow.frame_from_graph():
+            yield frame
+    if stream.stream_types.flat and (frame := stream.flow.to_stream_frame()):
+        yield frame
+
+
+@stream_frames.register(QuadStream)
+def quads_stream_frames(
+    stream: QuadStream,
+    data: GenericStatementSink | Generator[Quad],
+) -> Generator[jelly.RdfStreamFrame]:
+    """
+    Serialize a GenericStatementSink into jelly frames using physical type quads stream.
+
+    Args:
+        stream (QuadStream): stream that specifies quads processing
+        data (GenericStatementSink | Generator[Quad]): Dataset to serialize.
+
+    Yields:
+        Generator[jelly.RdfStreamFrame]: jelly frames
+
+    """
+    stream.enroll()
+    if stream.options.params.namespace_declarations:
+        namespace_declarations(data, stream)  # type: ignore[arg-type]
+
+    iterator: Generator[Quad]
+    if isinstance(data, GenericStatementSink):
+        iterator = cast(Generator[Quad], data.store)
+    else:
+        iterator = data
+
+    for terms in iterator:
+        if frame := stream.quad(terms):
+            yield frame
+    if frame := stream.flow.frame_from_dataset():
+        yield frame
+    if stream.stream_types.flat and (frame := stream.flow.to_stream_frame()):
+        yield frame
+
+
+@stream_frames.register(GraphStream)
+def graphs_stream_frames(
+    stream: GraphStream,
+    data: GenericStatementSink | Generator[Quad],
+) -> Generator[jelly.RdfStreamFrame]:
+    """
+    Serialize a GenericStatementSink into jelly frames as a stream of graphs.
+
+    Notes:
+        If flow of DatasetsFrameFlow type, the whole dataset
+        will be encoded into one frame.
+        Graphs are generated from the GenericStatementSink by
+        iterating over statements and yielding one new GenericStatementSink
+        per a sequence of quads with the same g term.
+
+    Args:
+        stream (GraphStream): stream that specifies graphs processing
+        data (GenericStatementSink | Generator[Quad]): Dataset to serialize.
+
+    Yields:
+        Generator[jelly.RdfStreamFrame]: jelly frames
+
+    """
+    stream.enroll()
+    if stream.options.params.namespace_declarations:
+        namespace_declarations(data, stream)  # type: ignore[arg-type]
+
+    statements: Generator[Quad]
+    if isinstance(data, GenericStatementSink):
+        statements = cast(Generator[Quad], data.store)
+        graphs = split_to_graphs(statements)
+    elif iter(data):
+        statements = data
+        graphs = split_to_graphs(statements)
+
+    for graph in graphs:
+        yield from stream.graph(graph_id=graph.identifier, graph=graph)
+
+    if frame := stream.flow.frame_from_dataset():
+        yield frame
+    if stream.stream_types.flat and (frame := stream.flow.to_stream_frame()):
+        yield frame
+
+
+def split_to_graphs(data: Generator[Quad]) -> Generator[GenericStatementSink]:
+    """
+    Split a generator of quads to graphs.
+
+    Notes:
+        New graph is generated by
+        iterating over statements and yielding one new GenericStatementSink
+        per a sequence of quads with the same g term.
+
+    Args:
+        data (Generator[Quad]): generator of quads
+
+    Yields:
+        Generator[GenericStatementSink]: generator of GenericStatementSinks,
+        each having triples in store and identifier set.
+
+    """
+    current_g: Node | None = None
+    current_sink: GenericStatementSink | None = None
+    for statement in data:
+        if current_g != statement.g:
+            if current_sink is not None:
+                yield current_sink
+
+            current_g = statement.g
+            current_sink = GenericStatementSink(identifier=current_g)
+
+        assert current_sink is not None
+        current_sink.add(Triple(statement.s, statement.p, statement.o))
+
+    if current_sink is not None:
+        yield current_sink
+
+
+def guess_options(sink: GenericStatementSink) -> SerializerOptions:
+    """Guess the serializer options based on the store type."""
+    logical_type = (
+        jelly.LOGICAL_STREAM_TYPE_FLAT_TRIPLES
+        if sink.is_triples_sink
+        else jelly.LOGICAL_STREAM_TYPE_FLAT_QUADS
+    )
+    return SerializerOptions(logical_type=logical_type)
+
+
+def guess_stream(options: SerializerOptions, sink: GenericStatementSink) -> Stream:
+    """
+    Return an appropriate stream implementation for the given options.
+
+    Notes: if base(!) logical type is GRAPHS and sink.is_triples_sink is false,
+        initializes TripleStream
+    """
+    stream_cls: type[Stream]
+    if (
+        options.logical_type % 10
+    ) != jelly.LOGICAL_STREAM_TYPE_GRAPHS and not sink.is_triples_sink:
+        stream_cls = QuadStream
+    else:
+        stream_cls = TripleStream
+    if options is not None:
+        lookup_preset = options.lookup_preset
+    return stream_cls(
+        encoder=GenericSinkTermEncoder(lookup_preset=lookup_preset),
+        options=options,
+    )
+
+
+def grouped_stream_to_frames(
+    sink_generator: Generator[GenericStatementSink],
+    options: SerializerOptions | None = None,
+) -> Generator[jelly.RdfStreamFrame]:
+    """
+    Transform multiple GenericStatementSinks into Jelly frames.
+
+    Notes:
+        One frame per GenericStatementSink.
+
+    Note: options are guessed if not provided.
+
+    Args:
+        sink_generator (Generator[GenericStatementSink]): Generator of
+            GenericStatementSink 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[GenericStatementSink],
+    output_file: IO[bytes],
+    **kwargs: Any,
+) -> None:
+    """
+    Write stream of GenericStatementSink to a binary file.
+
+    Args:
+        stream (Generator[GenericStatementSink]): Generator of
+            GenericStatementSink to serialize.
+        output_file (IO[bytes]): output buffered writer.
+        **kwargs (Any): options to pass to stream.
+
+    """
+    for frame in grouped_stream_to_frames(stream, **kwargs):
+        write_delimited(frame, output_file)
+
+
+def flat_stream_to_frames(
+    statements: Generator[Triple | Quad],
+    options: SerializerOptions | None = None,
+) -> Generator[jelly.RdfStreamFrame]:
+    """
+    Serialize a stream of raw GenericStatementSink's triples or quads into Jelly frames.
+
+    Args:
+        statements (Generator[Triple | Quad]):
+          s/p/o triples or s/p/o/g quads to serialize.
+        options (SerializerOptions | None, optional):
+            if omitted, guessed based on the first tuple.
+
+    Yields:
+        Generator[jelly.RdfStreamFrame]: generated frames.
+
+    """
+    first = next(statements, None)
+    if first is None:
+        return
+
+    sink = GenericStatementSink()
+    sink.add(first)
+    if options is None:
+        options = guess_options(sink)
+    stream = guess_stream(options, sink)
+
+    combined: Generator[Triple | Quad] | GenericStatementSink = (
+        item for item in chain([first], statements)
+    )
+
+    yield from stream_frames(stream, combined)
+
+
+def flat_stream_to_file(
+    statements: Generator[Triple | Quad],
+    output_file: IO[bytes],
+    options: SerializerOptions | None = None,
+) -> None:
+    """
+    Write Triple or Quad events to a binary file.
+
+    Args:
+        statements (Generator[Triple | Quad]): statements to serialize.
+        output_file (IO[bytes]): output buffered writer.
+        options (SerializerOptions | None, optional): stream options.
+
+    """
+    for frame in flat_stream_to_frames(statements, options):
+        write_delimited(frame, output_file)

pyjelly/integrations/rdflib/parse.py

@@ -315,7 +315,7 @@ def parse_jelly_grouped(
     dataset_factory: Callable[[], Dataset] = lambda: Dataset(),
 ) -> Generator[Graph] | Generator[Dataset]:
     """
-    Take jelly file and return generators based on the detected logical type.
+    Take jelly file and return generators based on the detected physical type.
 
     Yields one graph/dataset per frame.
 
@@ -329,7 +329,7 @@ def parse_jelly_grouped(
             but you can pass something else here.
 
     Raises:
-        NotImplementedError: is raised if a logical type is not implemented
+        NotImplementedError: is raised if a physical type is not implemented
 
     Yields:
         Generator[Graph] | Generator[Dataset]:
@@ -426,7 +426,7 @@ def parse_jelly_flat(
     options: ParserOptions | None = None,
 ) -> Generator[Statement | Prefix]:
     """
-    Parse jelly file with FLAT physical type into a Generator of stream events.
+    Parse jelly file with FLAT logical type into a Generator of stream events.
 
     Args:
         inp (IO[bytes]): input jelly buffered binary stream.

pyjelly/integrations/rdflib/serialize.py

@@ -1,10 +1,12 @@
 # ruff: noqa: I001
 from __future__ import annotations
-
+from typing import cast
 from collections.abc import Generator
 from functools import singledispatch
 from typing import Any, IO
 from typing_extensions import override
+from itertools import chain
+from pyjelly.integrations.rdflib.parse import Quad, Triple
 
 import rdflib
 from rdflib import Graph
@@ -22,6 +24,8 @@ from pyjelly.serialize.streams import (
     TripleStream,
 )  # ruff: enable
 
+QUAD_ARITY = 4
+
 
 class RDFLibTermEncoder(TermEncoder):
     def encode_any(self, term: object, slot: Slot) -> RowsAndTerm:
@@ -65,7 +69,7 @@ def namespace_declarations(store: Graph, stream: Stream) -> None:
 @singledispatch
 def stream_frames(
     stream: Stream,
-    data: Graph,  # noqa: ARG001
+    data: Graph | Generator[Quad | Triple],  # noqa: ARG001
 ) -> Generator[jelly.RdfStreamFrame]:
     msg = f"invalid stream implementation {stream}"
     raise TypeError(msg)
@@ -74,14 +78,15 @@ def stream_frames(
 @stream_frames.register(TripleStream)
 def triples_stream_frames(
     stream: TripleStream,
-    data: Graph | Dataset,
+    data: Graph | Dataset | Generator[Triple],
 ) -> Generator[jelly.RdfStreamFrame]:
     """
     Serialize a Graph/Dataset into jelly frames.
 
     Args:
         stream (TripleStream): stream that specifies triples processing
-        data (Graph | Dataset): Graph/Dataset to serialize.
+        data (Graph | Dataset | Generator[Triple]):
+            Graph/Dataset/Statements to serialize.
 
     Notes:
         if Dataset is given, its graphs are unpacked and iterated over
@@ -92,24 +97,24 @@ def triples_stream_frames(
 
     """
     stream.enroll()
-    if stream.options.params.namespace_declarations:
+    if isinstance(data, Graph) and stream.options.params.namespace_declarations:
         namespace_declarations(data, stream)
+
     graphs = (data,) if not isinstance(data, Dataset) else data.graphs()
     for graph in graphs:
         for terms in graph:
             if frame := stream.triple(terms):
                 yield frame
-        # this part turns each graph to a frame for graphs logical type
         if frame := stream.flow.frame_from_graph():
             yield frame
     if stream.stream_types.flat and (frame := stream.flow.to_stream_frame()):
         yield frame
 
 
-@stream_frames.register
+@stream_frames.register(QuadStream)
 def quads_stream_frames(
     stream: QuadStream,
-    data: Dataset,
+    data: Dataset | Generator[Quad],
 ) -> Generator[jelly.RdfStreamFrame]:
     """
     Serialize a Dataset into jelly frames.
@@ -119,17 +124,23 @@ def quads_stream_frames(
 
     Args:
         stream (QuadStream): stream that specifies quads processing
-        data (Dataset): Dataset to serialize.
+        data (Dataset | Generator[Quad]): Dataset to serialize.
 
     Yields:
         Generator[jelly.RdfStreamFrame]: jelly frames
 
     """
-    assert isinstance(data, Dataset)
     stream.enroll()
     if stream.options.params.namespace_declarations:
-        namespace_declarations(data, stream)
-    for terms in data.quads():
+        namespace_declarations(data, stream)  # type: ignore[arg-type]
+
+    iterator: Generator[Quad, None, None]
+    if isinstance(data, Dataset):
+        iterator = cast(Generator[Quad, None, None], data.quads())
+    else:
+        iterator = data
+
+    for terms in iterator:
         if frame := stream.quad(terms):
             yield frame
     if frame := stream.flow.frame_from_dataset():
@@ -138,10 +149,10 @@ def quads_stream_frames(
         yield frame
 
 
-@stream_frames.register
+@stream_frames.register(GraphStream)
 def graphs_stream_frames(
     stream: GraphStream,
-    data: Dataset,
+    data: Dataset | Generator[Quad],
 ) -> Generator[jelly.RdfStreamFrame]:
     """
     Serialize a Dataset into jelly frames as a stream of graphs.
@@ -152,18 +163,28 @@ def graphs_stream_frames(
 
     Args:
         stream (GraphStream): stream that specifies graphs processing
-        data (Dataset): Dataset to serialize.
+        data (Dataset | Generator[Quad]): Dataset to serialize.
 
     Yields:
         Generator[jelly.RdfStreamFrame]: jelly frames
 
     """
-    assert isinstance(data, Dataset)
     stream.enroll()
     if stream.options.params.namespace_declarations:
-        namespace_declarations(data, stream)
-    for graph in data.graphs():
+        namespace_declarations(data, stream)  # type: ignore[arg-type]
+
+    if isinstance(data, Dataset):
+        graphs = data.graphs()
+    else:
+        ds = Dataset()
+        for quad in data:
+            ctx = ds.get_context(quad.g)
+            ctx.add((quad.s, quad.p, quad.o))
+        graphs = ds.graphs()
+
+    for graph in graphs:
         yield from stream.graph(graph_id=graph.identifier, graph=graph)
+
     if frame := stream.flow.frame_from_dataset():
         yield frame
     if stream.stream_types.flat and (frame := stream.flow.to_stream_frame()):
@@ -297,9 +318,60 @@ def grouped_stream_to_file(
     Args:
         stream (Generator[Graph] | Generator[Dataset]): Generator of
             Graphs/Dataset to transform.
-        output_file (IO[bytes]): opened output file.
+        output_file (IO[bytes]): output buffered writer.
         **kwargs (Any): options to pass to stream.
 
     """
     for frame in grouped_stream_to_frames(stream, **kwargs):
         write_delimited(frame, output_file)
+
+
+def flat_stream_to_frames(
+    statements: Generator[Triple | Quad],
+    options: SerializerOptions | None = None,
+) -> Generator[jelly.RdfStreamFrame]:
+    """
+    Serialize a stream of raw triples or quads into Jelly frames.
+
+    Args:
+        statements (Generator[Triple | Quad]):
+          s/p/o triples or s/p/o/g quads to serialize.
+        options (SerializerOptions | None, optional):
+            if omitted, guessed based on the first tuple.
+
+    Yields:
+        Generator[jelly.RdfStreamFrame]: generated frames.
+
+    """
+    first = next(statements, None)
+    if first is None:
+        return
+
+    sink = Dataset() if len(first) == QUAD_ARITY else Graph()
+    if options is None:
+        options = guess_options(sink)
+    stream = guess_stream(options, sink)
+
+    combined: Generator[Triple | Quad] | Graph = (
+        item for item in chain([first], statements)
+    )
+
+    yield from stream_frames(stream, combined)
+
+
+def flat_stream_to_file(
+    statements: Generator[Triple | Quad],
+    output_file: IO[bytes],
+    options: SerializerOptions | None = None,
+) -> None:
+    """
+    Write Triple or Quad events to a binary file in Jelly flat format.
+
+    Args:
+        statements (Generator[Triple | Quad]): statements to serialize.
+        output_file (IO[bytes]): output buffered writer.
+        options (SerializerOptions | None, optional): stream options.
+
+    """
+    for frame in flat_stream_to_frames(statements, options):
+        write_delimited(frame, output_file)

pyjelly/options.py

@@ -15,6 +15,7 @@ from pyjelly.errors import (
 MIN_NAME_LOOKUP_SIZE: Final[int] = 8
 
 MAX_LOOKUP_SIZE: Final[int] = 4096
+MIN_VERSION: Final[int] = 1
 MAX_VERSION: Final[int] = 2
 
 DEFAULT_NAME_LOOKUP_SIZE: Final[int] = 4000
@@ -97,6 +98,14 @@ class StreamParameters:
     namespace_declarations: bool = False
     stream_name: str = ""
 
+    def __post_init__(self) -> None:
+        selected = MAX_VERSION if self.namespace_declarations else MIN_VERSION
+        if not (MIN_VERSION <= selected <= MAX_VERSION):
+            msg = f"""Error occured while settin up the Stream options.
+            Version must be between {MIN_VERSION} and {MAX_VERSION}."""
+            raise JellyConformanceError(msg)
+        object.__setattr__(self, "version", selected)
+
 
 TRIPLES_ONLY_LOGICAL_TYPES = {
     jelly.LOGICAL_STREAM_TYPE_GRAPHS,

pyjelly/parse/decode.py

@@ -66,6 +66,8 @@ def options_from_frame(
         ),
         params=StreamParameters(
             stream_name=options.stream_name,
+            generalized_statements=options.generalized_statements,
+            rdf_star=options.rdf_star,
             version=options.version,
             delimited=delimited,
         ),
@@ -134,6 +136,11 @@ class Adapter(metaclass=ABCMeta):
             stream_types=self.options.stream_types,
         )
 
+    def quoted_triple(self, terms: Iterable[Any]) -> Any:  # noqa: ARG002
+        _adapter_missing(
+            "decoding quoted triple", stream_types=self.options.stream_types
+        )
+
     def frame(self) -> Any:
         return None
 
@@ -383,6 +390,20 @@ class Decoder:
         terms = self.decode_statement(triple, ("subject", "predicate", "object"))
         return self.adapter.triple(terms)
 
+    def decode_quoted_triple(self, triple: jelly.RdfTriple) -> Any:
+        oneofs: Sequence[str] = ("subject", "predicate", "object")
+        terms = []
+        for oneof in oneofs:
+            field = triple.WhichOneof(oneof)
+            if field:
+                jelly_term = getattr(triple, field)
+                decoded_term = self.decode_term(jelly_term)
+            else:
+                msg = "repeated terms are not allowed in quoted triples"
+                raise ValueError(msg)
+            terms.append(decoded_term)
+        return self.adapter.quoted_triple(terms)
+
     def decode_quad(self, quad: jelly.RdfQuad) -> Any:
         terms = self.decode_statement(quad, ("subject", "predicate", "object", "graph"))
         return self.adapter.quad(terms)
@@ -405,4 +426,5 @@ class Decoder:
         str: decode_bnode,
         jelly.RdfLiteral: decode_literal,
         jelly.RdfDefaultGraph: decode_default_graph,
+        jelly.RdfTriple: decode_quoted_triple,
     }

pyjelly/serialize/encode.py

@@ -32,9 +32,8 @@ def split_iri(iri_string: str) -> tuple[str, str]:
 
 T = TypeVar("T")
 RowsAnd: TypeAlias = tuple[Sequence[jelly.RdfStreamRow], T]
-RowsAndTerm: TypeAlias = (
-    "RowsAnd[jelly.RdfIri | jelly.RdfLiteral | str | jelly.RdfDefaultGraph]"
-)
+RowsAndTerm: TypeAlias = "RowsAnd[jelly.RdfIri | jelly.RdfLiteral | str | \
+    jelly.RdfDefaultGraph | jelly.RdfTriple]"
 
 
 class TermEncoder:
@@ -43,6 +42,7 @@ class TermEncoder:
         jelly.RdfLiteral: "literal",
         str: "bnode",
         jelly.RdfDefaultGraph: "default_graph",
+        jelly.RdfTriple: "triple_term",
     }
 
     def __init__(
@@ -163,6 +163,33 @@ class TermEncoder:
             datatype=datatype_id,
         )
 
+    def encode_quoted_triple(self, terms: Iterable[object]) -> RowsAndTerm:
+        """
+        Encode a quoted triple.
+
+        Notes:
+            Although a triple, it is treated as a part of a statement.
+            Repeated terms are not used when encoding quoted triples.
+
+        Args:
+            terms (Iterable[object]): triple terms to encode.
+
+        Returns:
+            RowsAndTerm: additional stream rows with preceeding
+                information (prefixes, names, datatypes rows, if any)
+                and the encoded triple row.
+
+        """
+        statement: dict[str, Any] = {}
+        rows: list[jelly.RdfStreamRow] = []
+        for slot, term in zip(Slot, terms):
+            extra_rows, value = self.encode_any(term, slot)
+            oneof = self.TERM_ONEOF_NAMES[type(value)]
+            rows.extend(extra_rows)
+            field = f"{slot}_{oneof}"
+            statement[field] = value
+        return rows, jelly.RdfTriple(**statement)
+
     def encode_any(self, term: object, slot: Slot) -> RowsAndTerm:
         msg = f"unsupported term type: {type(term)}"
         raise NotImplementedError(msg)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyjelly
-Version: 0.4.0
+Version: 0.5.0
 Summary: Jelly-RDF implementation for Python
 Project-URL: Homepage, https://w3id.org/jelly/pyjelly
 Project-URL: Documentation, https://w3id.org/jelly/pyjelly
@@ -29,12 +29,13 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
 Requires-Dist: protobuf>=6.30.0
+Requires-Dist: pytest-cov>=6.2.1
 Requires-Dist: typing-extensions>=4.12.2
 Provides-Extra: rdflib
 Requires-Dist: rdflib>=7.1.4; extra == 'rdflib'
 Description-Content-Type: text/markdown
 
-[![Documentation](https://img.shields.io/website?url=https%3A%2F%2Fw3id.org%2Fjelly%2Fpyjelly&label=Documentation)](https://w3id.org/jelly/pyjelly) [![PyPI – Version](https://img.shields.io/pypi/v/pyjelly)](https://pypi.org/project/pyjelly/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyjelly)](https://pypi.org/project/pyjelly/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![CI status](https://github.com/Jelly-RDF/pyjelly/actions/workflows/ci.yml/badge.svg)](https://github.com/Jelly-RDF/pyjelly/actions/workflows/ci.yml) [![Discord](https://img.shields.io/discord/1333391881404420179?label=Discord%20chat)](https://discord.gg/A8sN5XwVa5)
+[![Documentation](https://img.shields.io/website?url=https%3A%2F%2Fw3id.org%2Fjelly%2Fpyjelly&label=Documentation)](https://w3id.org/jelly/pyjelly) [![PyPI – Version](https://img.shields.io/pypi/v/pyjelly)](https://pypi.org/project/pyjelly/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyjelly)](https://pypi.org/project/pyjelly/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![CI status](https://github.com/Jelly-RDF/pyjelly/actions/workflows/ci.yml/badge.svg)](https://github.com/Jelly-RDF/pyjelly/actions/workflows/ci.yml) [![Code coverage](https://codecov.io/gh/Jelly-RDF/pyjelly/branch/main/graph/badge.svg?token=2D8M2QH6U0)](https://codecov.io/gh/Jelly-RDF/pyjelly) [![Discord](https://img.shields.io/discord/1333391881404420179?label=Discord%20chat)](https://discord.gg/A8sN5XwVa5)
 
 # pyjelly
 

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

@@ -1,28 +1,32 @@
 pyjelly/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pyjelly/errors.py,sha256=R-xRB4a9S19J9dzAL4a5MCaBwb9ev_kvphGFkQJX6ZU,332
-pyjelly/options.py,sha256=jYVPNdaMTh76Oqtdk8kaJwG5gv8dUjlMkW6nXWohCn4,3862
+pyjelly/options.py,sha256=vjUjwifD1SFj_b3wvz8D50Tv2wbgGrVF0urG9Zpx3VQ,4307
 pyjelly/_proto/grpc.proto,sha256=3PfcZWqKhUSzP_T-xT-80raUYERr_dXWd8rITzXIqek,1188
 pyjelly/_proto/patch.proto,sha256=gASUm0xDG9J1advNoq_cCsJYxudTbQaiZQBq4oW3kw4,5291
 pyjelly/_proto/rdf.proto,sha256=EKxyG421B4m0Wx5-6jjojdga_hA3jpZfF6-T3lMc0hI,12763
 pyjelly/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyjelly/integrations/generic/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyjelly/integrations/generic/generic_sink.py,sha256=zJoz6hI46Z13u4aa4zSXlbXFkHO7wLVW-czlytK-IOI,4024
+pyjelly/integrations/generic/parse.py,sha256=BLavZP-CgstDfQtrMzhsn1OnGQQBe-DNmmxqCWvdAmc,9564
+pyjelly/integrations/generic/serialize.py,sha256=F3giZpPrMAuIL9LHm58e1u_9Y-wwMy9rPUmpxb3OVTY,10893
 pyjelly/integrations/rdflib/__init__.py,sha256=lpIz6iildMf5bDvj3aBqZJ7kgKFrTx_tsqSb6PkLis0,552
-pyjelly/integrations/rdflib/parse.py,sha256=_H4f5qUU0IvMPaq1Tnm2UF1aXX-DY1qPn_7GmoIa4V0,13717
-pyjelly/integrations/rdflib/serialize.py,sha256=etFY10HjmsjmuR6BjvWw32f2zBThW26mTGFn67jcOdc,9524
+pyjelly/integrations/rdflib/parse.py,sha256=73i4BAI72ZfZycNRlAPboRcpgPAS7XFG5Yesnfe7yME,13718
+pyjelly/integrations/rdflib/serialize.py,sha256=LwWeBZDoyQL4mC6wta2TnW_1ys3_kqxmAFkAoJMJnOw,11675
 pyjelly/jelly/__init__.py,sha256=9kacwn8Ew_1fcgj1abz6miEz-AtUdPT2ltFWaRIE5VE,126
 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=ERgCLzBvbkJWTlg3RT0p-h8J60KNqpQ4mj_-JHoD7kg,13299
+pyjelly/parse/decode.py,sha256=tVn2e6UmGqjFplIFFlOvZYMb50jCLvkRuaZky45CVNg,14220
 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/encode.py,sha256=Yr8StCm4u5oJ1ZDFFHnRVnJFtPlCyX7fCFBgmB5Drgw,10521
 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=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,,
+pyjelly-0.5.0.dist-info/METADATA,sha256=LZ9VubOV_XRCC-Bqk7RWmfbcYJETPfKL7-YnhrVQr5Y,4786
+pyjelly-0.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pyjelly-0.5.0.dist-info/entry_points.txt,sha256=kUG0p9zso7HpitdMaQaXEj_KSqgOGsL0Ky9ARbecN1g,339
+pyjelly-0.5.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pyjelly-0.5.0.dist-info/RECORD,,