pyjelly 0.7.1__cp311-cp311-macosx_11_0_x86_64.whl

pyjelly/integrations/generic/generic_sink.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Generator
+from typing import IO, NamedTuple, Union
+
+
+class _DefaultGraph:
+    def __repr__(self) -> str:
+        return ""
+
+
+DefaultGraph = _DefaultGraph()
+
+
+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})"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, BlankNode):
+            return self._identifier == other._identifier
+        return False
+
+    def __hash__(self) -> int:
+        return hash(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})"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, IRI):
+            return self._iri == other._iri
+        return False
+
+    def __hash__(self) -> int:
+        return hash(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})"
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Literal):
+            return (
+                self._lex == other._lex
+                and self._langtag == other._langtag
+                and self._datatype == other._datatype
+            )
+        return False
+
+    def __hash__(self) -> int:
+        return hash((self._lex, self._langtag, self._datatype))
+
+
+Node = Union[BlankNode, IRI, Literal, "Triple"]
+GraphName = Node | _DefaultGraph
+
+
+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: GraphName
+
+
+class Prefix(NamedTuple):
+    """Class for generic namespace declaration."""
+
+    prefix: str
+    iri: IRI
+
+
+class GenericStatementSink:
+    _store: deque[Triple | Quad]
+
+    def __init__(self, identifier: GraphName = DefaultGraph) -> 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 DefaultGraph.
+
+        """
+        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) -> GraphName:
+        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 bool(self._store) and len(self._store[0]) == TRIPLE_ARITY
+
+    def parse(self, input_file: IO[bytes]) -> None:
+        from pyjelly.integrations.generic.parse import (  # noqa: PLC0415
+            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 (  # noqa: PLC0415
+            grouped_stream_to_file,
+        )
+
+        grouped_stream_to_file((sink for sink in [self]), output_file)

pyjelly/integrations/generic/parse.py

@@ -0,0 +1,412 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Generator, Iterable, MutableMapping
+from contextvars import ContextVar
+from itertools import chain
+from typing import IO, Any
+from typing_extensions import override
+
+from mypy_extensions import mypyc_attr
+
+from pyjelly import jelly
+from pyjelly.errors import JellyConformanceError
+from pyjelly.integrations.generic.generic_sink import (
+    IRI,
+    BlankNode,
+    DefaultGraph,
+    GenericStatementSink,
+    GraphName,
+    Literal,
+    Prefix,
+    Quad,
+    Triple,
+)
+from pyjelly.parse.decode import Adapter, Decoder, ParserOptions
+from pyjelly.parse.ioutils import get_options_and_frames
+
+Statement = Triple | Quad
+
+
+@mypyc_attr(allow_interpreted_subclasses=True)
+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) -> GraphName:
+        return DefaultGraph
+
+    @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)
+
+
+@mypyc_attr(allow_interpreted_subclasses=True)
+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)
+
+
+@mypyc_attr(allow_interpreted_subclasses=True)
+class GenericQuadsBaseAdapter(GenericStatementSinkAdapter):
+    def __init__(self, options: ParserOptions) -> None:
+        super().__init__(options=options)
+
+
+@mypyc_attr(allow_interpreted_subclasses=True)
+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)
+
+
+@mypyc_attr(allow_interpreted_subclasses=True)
+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: GraphName | 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: GraphName) -> 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,
+    frame_metadata: ContextVar[MutableMapping[str, bytes]] | None = None,
+) -> Generator[Iterable[Triple | Prefix]]:
+    """
+    Parse flat triple stream.
+
+    Args:
+        frames (Iterable[jelly.RdfStreamFrame]): iterator over stream frames
+        options (ParserOptions): stream options
+        frame_metadata: (ContextVar[ScalarMap[str, bytes]]): context variable
+                used for extracting frame metadata
+
+    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:
+        if frame_metadata is not None:
+            frame_metadata.set(
+                frame.metadata
+            ) if frame.metadata else frame_metadata.set({})
+        yield decoder.iter_rows(frame)
+    return
+
+
+def parse_quads_stream(
+    frames: Iterable[jelly.RdfStreamFrame],
+    options: ParserOptions,
+    frame_metadata: ContextVar[MutableMapping[str, bytes]] | None = None,
+) -> Generator[Iterable[Quad | Prefix]]:
+    """
+    Parse flat quads stream.
+
+    Args:
+        frames (Iterable[jelly.RdfStreamFrame]): iterator over stream frames
+        options (ParserOptions): stream options
+        frame_metadata: (ContextVar[ScalarMap[str, bytes]]): context variable
+                used for extracting frame metadata
+
+    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:
+        if frame_metadata is not None:
+            frame_metadata.set(
+                frame.metadata
+            ) if frame.metadata else frame_metadata.set({})
+        yield decoder.iter_rows(frame)
+    return
+
+
+def parse_jelly_grouped(
+    inp: IO[bytes],
+    sink_factory: Callable[[], GenericStatementSink] = lambda: GenericStatementSink(),
+    *,
+    logical_type_strict: bool = False,
+    frame_metadata: ContextVar[MutableMapping[str, bytes]] | None = None,
+) -> 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.
+        logical_type_strict (bool): If True, validate the *logical* type
+            in stream options and require a grouped logical type.
+            Otherwise, only the physical type is used to route parsing.
+        frame_metadata: (ContextVar[ScalarMap[str, bytes]]): context variable
+                used for extracting frame metadata
+
+    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)
+
+    st = getattr(options, "stream_types", None)
+    if logical_type_strict and (
+        st is None
+        or st.logical_type == jelly.LOGICAL_STREAM_TYPE_UNSPECIFIED
+        or st.flat
+    ):
+        lt_name = (
+            "UNSPECIFIED"
+            if st is None
+            else jelly.LogicalStreamType.Name(st.logical_type)
+        )
+
+        msg = (
+            "strict logical type check requires options.stream_types"
+            if st is None
+            else f"expected GROUPED logical type, got {lt_name}"
+        )
+        raise JellyConformanceError(msg)
+
+    if options.stream_types.physical_type == jelly.PHYSICAL_STREAM_TYPE_TRIPLES:
+        for graph in parse_triples_stream(
+            frames=frames,
+            options=options,
+            **{"frame_metadata": frame_metadata} if frame_metadata is not None else {},
+        ):
+            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,
+            **{"frame_metadata": frame_metadata} if frame_metadata is not None else {},
+        ):
+            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, logical_type_strict=False
+    ):
+        if isinstance(item, Prefix):
+            sink.bind(item.prefix, item.iri)  # type: ignore[union-attr, unused-ignore]
+        else:
+            sink.add(item)
+    return sink
+
+
+def parse_jelly_flat(
+    inp: IO[bytes],
+    frames: Iterable[jelly.RdfStreamFrame] | None = None,
+    options: ParserOptions | None = None,
+    *,
+    logical_type_strict: bool = False,
+) -> Generator[Statement | Prefix]:  # type: ignore[valid-type, unused-ignore]
+    """
+    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.
+        logical_type_strict (bool): If True, validate the *logical* type
+            in stream options and require FLAT (TRIPLES/QUADS).
+            Otherwise, only the physical type is used to route parsing.
+
+    Raises:
+        NotImplementedError: if physical type is not supported
+
+    Yields:
+        Generator[Statement | Prefix]: Generator of stream events
+
+    """
+    if frames is None or options is None:
+        options, frames = get_options_and_frames(inp)
+
+    st = getattr(options, "stream_types", None)
+    if logical_type_strict and (st is None or not st.flat):
+        lt_name = (
+            "UNSPECIFIED"
+            if st is None
+            else jelly.LogicalStreamType.Name(st.logical_type)
+        )
+
+        msg = (
+            "strict logical type check requires options.stream_types"
+            if st is None
+            else f"expected FLAT logical type (TRIPLES/QUADS), got {lt_name}"
+        )
+        raise JellyConformanceError(msg)
+
+    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)