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

pyjelly/parse/decode.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from abc import ABCMeta, abstractmethod
 from collections.abc import Iterable, Sequence
+from enum import Enum, auto
 from typing import Any, ClassVar, NamedTuple
 from typing_extensions import Never
 
@@ -10,6 +11,21 @@ from pyjelly.options import LookupPreset, StreamParameters, StreamTypes
 from pyjelly.parse.lookup import LookupDecoder
 
 
+class ParsingMode(Enum):
+    """
+    Specifies how jelly frames should be treated.
+
+    Modes:
+    FLAT
+        Yield all frames as one Graph or Dataset.
+    GROUPED
+        Yield one Graph/Dataset per frame (grouped parsing).
+    """
+
+    FLAT = auto()
+    GROUPED = auto()
+
+
 class ParserOptions(NamedTuple):
     stream_types: StreamTypes
     lookup_preset: LookupPreset
@@ -21,6 +37,21 @@ def options_from_frame(
     *,
     delimited: bool,
 ) -> ParserOptions:
+    """
+    Fill stream options based on the options row.
+
+    Notes:
+        generalized_statements, rdf_star, and namespace declarations
+        are set to false by default
+
+    Args:
+        frame (jelly.RdfStreamFrame): first non-empty frame from the stream
+        delimited (bool): derived delimited flag
+
+    Returns:
+        ParserOptions: filled options with types/lookups/stream parameters information
+
+    """
     row = frame.rows[0]
     options = row.options
     return ParserOptions(
@@ -52,8 +83,11 @@ def _adapter_missing(feature: str, *, stream_types: StreamTypes) -> Never:
 
 
 class Adapter(metaclass=ABCMeta):
-    def __init__(self, options: ParserOptions) -> None:
+    def __init__(
+        self, options: ParserOptions, parsing_mode: ParsingMode = ParsingMode.FLAT
+    ) -> None:
         self.options = options
+        self.parsing_mode = parsing_mode
 
     # Obligatory abstract methods--all adapters must implement these
     @abstractmethod
@@ -106,6 +140,18 @@ class Adapter(metaclass=ABCMeta):
 
 class Decoder:
     def __init__(self, adapter: Adapter) -> None:
+        """
+        Initialize decoder.
+
+        Initializes decoder with a lookup tables with preset sizes,
+        integration-dependent adapter and empty repeated terms dictionary.
+
+        Args:
+            adapter (Adapter): integration-dependent adapter that specifies terms
+            conversion to specific objects, framing,
+            namespace declarations, and graphs/datasets forming.
+
+        """
         self.adapter = adapter
         self.names = LookupDecoder(lookup_size=self.options.lookup_preset.max_names)
         self.prefixes = LookupDecoder(
@@ -121,12 +167,42 @@ class Decoder:
         return self.adapter.options
 
     def decode_frame(self, frame: jelly.RdfStreamFrame) -> Any:
+        """
+        Decode a frame to custom object based on adapter implementation.
+
+        Args:
+            frame (jelly.RdfStreamFrame): jelly frame
+
+        Returns:
+            Any: custom obj based on adapter logic
+
+        """
         for row_owner in frame.rows:
             row = getattr(row_owner, row_owner.WhichOneof("row"))
             self.decode_row(row)
-        return self.adapter.frame()
+        if self.adapter.parsing_mode is ParsingMode.GROUPED:
+            return self.adapter.frame()
+        return None
 
     def decode_row(self, row: Any) -> Any | None:
+        """
+        Decode a row based on its type.
+
+        Notes: uses custom adapters to decode triples/quads, namespace declarations,
+               graph start/end.
+
+        Args:
+            row (Any): protobuf row message
+
+        Raises:
+            TypeError: raises error if this type of protobuf message does not have
+                       a respective handler
+
+        Returns:
+            Any | None: decoded row -
+                        result from calling decode_row (row type appropriate handler)
+
+        """
         try:
             decode_row = self.row_handlers[type(row)]
         except KeyError:
@@ -145,15 +221,51 @@ class Decoder:
         assert lookup_preset.max_names == options.max_name_table_size
 
     def ingest_prefix_entry(self, entry: jelly.RdfPrefixEntry) -> None:
+        """
+        Update prefix lookup table based on the table entry.
+
+        Args:
+            entry (jelly.RdfPrefixEntry): prefix message, containing id and value
+
+        """
         self.prefixes.assign_entry(index=entry.id, value=entry.value)
 
     def ingest_name_entry(self, entry: jelly.RdfNameEntry) -> None:
+        """
+        Update name lookup table based on the table entry.
+
+        Args:
+            entry (jelly.RdfNameEntry): name message, containing id and value
+
+        """
         self.names.assign_entry(index=entry.id, value=entry.value)
 
     def ingest_datatype_entry(self, entry: jelly.RdfDatatypeEntry) -> None:
+        """
+        Update datatype lookup table based on the table entry.
+
+        Args:
+            entry (jelly.RdfDatatypeEntry): name message, containing id and value
+
+        """
         self.datatypes.assign_entry(index=entry.id, value=entry.value)
 
     def decode_term(self, term: Any) -> Any:
+        """
+        Decode a term based on its type: IRI/literal/BN/default graph.
+
+        Notes: requires a custom adapter with implemented methods for terms decoding.
+
+        Args:
+            term (Any): IRI/literal/BN(string)/Default graph message
+
+        Raises:
+            TypeError: raises error if no handler for the term is found
+
+        Returns:
+            Any: decoded term (currently, rdflib objects, e.g., rdflib.term.URIRef)
+
+        """
         try:
             decode_term = self.term_handlers[type(term)]
         except KeyError:
@@ -162,6 +274,16 @@ class Decoder:
         return decode_term(self, term)
 
     def decode_iri(self, iri: jelly.RdfIri) -> Any:
+        """
+        Decode RdfIri message to IRI using a custom adapter.
+
+        Args:
+            iri (jelly.RdfIri): RdfIri message
+
+        Returns:
+            Any: IRI, based on adapter implementation, e.g., rdflib.term.URIRef
+
+        """
         name = self.names.decode_name_term_index(iri.name_id)
         prefix = self.prefixes.decode_prefix_term_index(iri.prefix_id)
         return self.adapter.iri(iri=prefix + name)
@@ -170,9 +292,32 @@ class Decoder:
         return self.adapter.default_graph()
 
     def decode_bnode(self, bnode: str) -> Any:
+        """
+        Decode string message to blank node (BN) using a custom adapter.
+
+        Args:
+            bnode (str): blank node id
+
+        Returns:
+            Any: blank node object from the custom adapter
+
+        """
         return self.adapter.bnode(bnode)
 
     def decode_literal(self, literal: jelly.RdfLiteral) -> Any:
+        """
+        Decode RdfLiteral to literal based on custom adapter implementation.
+
+        Notes: checks for langtag existence;
+               for datatype checks for non-zero table size and datatype field presence
+
+        Args:
+            literal (jelly.RdfLiteral): RdfLiteral message
+
+        Returns:
+            Any: literal returned by the custom adapter
+
+        """
         language = datatype = None
         if literal.langtag:
             language = literal.langtag
@@ -203,6 +348,22 @@ class Decoder:
         statement: jelly.RdfTriple | jelly.RdfQuad,
         oneofs: Sequence[str],
     ) -> Any:
+        """
+        Decode a triple/quad message.
+
+        Notes: also updates repeated terms dictionary
+
+        Args:
+            statement (jelly.RdfTriple | jelly.RdfQuad): triple/quad message
+            oneofs (Sequence[str]): terms s/p/o/g(if quads)
+
+        Raises:
+            ValueError: if a missing repeated term is encountered
+
+        Returns:
+            Any: a list of decoded terms
+
+        """
         terms = []
         for oneof in oneofs:
             field = statement.WhichOneof(oneof)

pyjelly/parse/ioutils.py

@@ -62,6 +62,22 @@ def frame_iterator(inp: IO[bytes]) -> Generator[jelly.RdfStreamFrame]:
 def get_options_and_frames(
     inp: IO[bytes],
 ) -> tuple[ParserOptions, Iterator[jelly.RdfStreamFrame]]:
+    """
+    Return stream options and frames from the buffered binary stream.
+
+    Args:
+        inp (IO[bytes]): jelly buffered binary stream
+
+    Raises:
+        JellyConformanceError: if no non-empty frames detected in the delimited stream
+        JellyConformanceError: if non-delimited,
+            error is raised if no rows are detected (empty frame)
+
+    Returns:
+        tuple[ParserOptions, Iterator[jelly.RdfStreamFrame]]: ParserOptions holds:
+            stream types, lookup presets and other stream options
+
+    """
     is_delimited = delimited_jelly_hint(bytes_read := inp.read(3))
     inp.seek(-len(bytes_read), os.SEEK_CUR)
 

pyjelly/serialize/encode.py

@@ -11,6 +11,16 @@ from pyjelly.serialize.lookup import LookupEncoder
 
 
 def split_iri(iri_string: str) -> tuple[str, str]:
+    """
+    Split iri into prefix and name.
+
+    Args:
+        iri_string (str): full iri string.
+
+    Returns:
+        tuple[str, str]: iri's prefix and name.
+
+    """
     name = iri_string
     prefix = ""
     for sep in "#", "/":
@@ -47,6 +57,16 @@ class TermEncoder:
         self.datatypes = LookupEncoder(lookup_size=lookup_preset.max_datatypes)
 
     def encode_iri(self, iri_string: str) -> RowsAnd[jelly.RdfIri]:
+        """
+        Encode iri.
+
+        Args:
+            iri_string (str): full iri in string format.
+
+        Returns:
+            RowsAnd[jelly.RdfIri]: extra rows and protobuf RdfIri message.
+
+        """
         prefix, name = split_iri(iri_string)
         if self.prefixes.lookup.max_size:
             prefix_entry_index = self.prefixes.encode_entry_index(prefix)
@@ -70,9 +90,27 @@ class TermEncoder:
         return term_rows, jelly.RdfIri(prefix_id=prefix_index, name_id=name_index)
 
     def encode_default_graph(self) -> RowsAnd[jelly.RdfDefaultGraph]:
+        """
+        Encode default graph.
+
+        Returns:
+            RowsAnd[jelly.RdfDefaultGraph]: empty extra rows and
+                default graph message.
+
+        """
         return (), jelly.RdfDefaultGraph()
 
     def encode_bnode(self, bnode: str) -> RowsAnd[str]:
+        """
+        Encode blank node (BN).
+
+        Args:
+            bnode (str): BN internal identifier in string format.
+
+        Returns:
+            RowsAnd[str]: empty extra rows and original BN string.
+
+        """
         return (), bnode
 
     def encode_literal(
@@ -82,6 +120,24 @@ class TermEncoder:
         language: str | None = None,
         datatype: str | None = None,
     ) -> RowsAnd[jelly.RdfLiteral]:
+        """
+        Encode literal.
+
+        Args:
+            lex (str): lexical form/literal value
+            language (str | None, optional): langtag. Defaults to None.
+            datatype (str | None, optional): data type if
+            it is a typed literal. Defaults to None.
+
+        Raises:
+            JellyConformanceError: if datatype specified while
+                datatable is not used.
+
+        Returns:
+            RowsAnd[jelly.RdfLiteral]: extra rows (i.e., datatype entries)
+                and RdfLiteral message.
+
+        """
         datatype_id = None
         term_rows: tuple[()] | tuple[jelly.RdfStreamRow] = ()
 
@@ -129,6 +185,19 @@ def encode_statement(
     term_encoder: TermEncoder,
     repeated_terms: dict[Slot, object],
 ) -> tuple[list[jelly.RdfStreamRow], dict[str, Any]]:
+    """
+    Encode a statement.
+
+    Args:
+        terms (Iterable[object]): original terms to encode
+        term_encoder (TermEncoder): encoder with lookup tables
+        repeated_terms (dict[Slot, object]): dictionary of repeated terms.
+
+    Returns:
+        tuple[list[jelly.RdfStreamRow], dict[str, Any]]:
+            extra rows to append and jelly terms.
+
+    """
     statement: dict[str, object] = {}
     rows: list[jelly.RdfStreamRow] = []
     for slot, term in zip(Slot, terms):
@@ -147,6 +216,18 @@ def encode_triple(
     term_encoder: TermEncoder,
     repeated_terms: dict[Slot, object],
 ) -> list[jelly.RdfStreamRow]:
+    """
+    Encode one triple.
+
+    Args:
+        terms (Iterable[object]): original terms to encode
+        term_encoder (TermEncoder): current encoder with lookup tables
+        repeated_terms (dict[Slot, object]): dictionary of repeated terms.
+
+    Returns:
+        list[jelly.RdfStreamRow]: list of rows to add to the current flow.
+
+    """
     rows, statement = encode_statement(terms, term_encoder, repeated_terms)
     row = jelly.RdfStreamRow(triple=jelly.RdfTriple(**statement))
     rows.append(row)
@@ -158,6 +239,18 @@ def encode_quad(
     term_encoder: TermEncoder,
     repeated_terms: dict[Slot, object],
 ) -> list[jelly.RdfStreamRow]:
+    """
+    Encode one quad.
+
+    Args:
+        terms (Iterable[object]): original terms to encode
+        term_encoder (TermEncoder): current encoder with lookup tables
+        repeated_terms (dict[Slot, object]): dictionary of repeated terms.
+
+    Returns:
+        list[jelly.RdfStreamRow]: list of messages to append to current flow.
+
+    """
     rows, statement = encode_statement(terms, term_encoder, repeated_terms)
     row = jelly.RdfStreamRow(quad=jelly.RdfQuad(**statement))
     rows.append(row)
@@ -169,6 +262,18 @@ def encode_namespace_declaration(
     value: str,
     term_encoder: TermEncoder,
 ) -> list[jelly.RdfStreamRow]:
+    """
+    Encode namespace declaration.
+
+    Args:
+        name (str): namespace prefix label
+        value (str): namespace iri
+        term_encoder (TermEncoder): current encoder
+
+    Returns:
+        list[jelly.RdfStreamRow]: list of messages to append to current flow.
+
+    """
     [*rows], iri = term_encoder.encode_iri(value)
     declaration = jelly.RdfNamespaceDeclaration(name=name, value=iri)
     row = jelly.RdfStreamRow(namespace=declaration)
@@ -181,6 +286,18 @@ def encode_options(
     stream_types: options.StreamTypes,
     params: options.StreamParameters,
 ) -> jelly.RdfStreamRow:
+    """
+    Encode stream options to ProtoBuf message.
+
+    Args:
+        lookup_preset (options.LookupPreset): lookup tables options
+        stream_types (options.StreamTypes): physical and logical types
+        params (options.StreamParameters): other params.
+
+    Returns:
+        jelly.RdfStreamRow: encoded stream options row
+
+    """
     return jelly.RdfStreamRow(
         options=jelly.RdfStreamOptions(
             stream_name=params.stream_name,

pyjelly/serialize/flows.py

@@ -41,6 +41,16 @@ class FrameFlow(UserList[jelly.RdfStreamRow]):
         return None
 
     def to_stream_frame(self) -> jelly.RdfStreamFrame | None:
+        """
+        Create stream frame from flow content.
+
+        Notes:
+            Clears flow content after creating the frame.
+
+        Returns:
+            jelly.RdfStreamFrame | None: stream frame
+
+        """
         if not self:
             return None
         frame = jelly.RdfStreamFrame(rows=self)
@@ -74,7 +84,7 @@ class ManualFrameFlow(FrameFlow):
 @dataclass
 class BoundedFrameFlow(FrameFlow):
     """
-    Produces frames automatically when a fixed number of rows is reached.
+    Produce frames automatically when a fixed number of rows is reached.
 
     Used for delimited encoding (default mode).
     """
@@ -93,6 +103,13 @@ class BoundedFrameFlow(FrameFlow):
 
     @override
     def frame_from_bounds(self) -> jelly.RdfStreamFrame | None:
+        """
+        Emit frame from flow if full.
+
+        Returns:
+            jelly.RdfStreamFrame | None: stream frame
+
+        """
         if len(self) >= self.frame_size:
             return self.to_stream_frame()
         return None
@@ -110,6 +127,14 @@ class GraphsFrameFlow(FrameFlow):
     logical_type = jelly.LOGICAL_STREAM_TYPE_GRAPHS
 
     def frame_from_graph(self) -> jelly.RdfStreamFrame | None:
+        """
+        Emit current flow content (one graph) as jelly frame.
+
+        Returns:
+            jelly.RdfStreamFrame | None: jelly frame or none if
+                flow is empty.
+
+        """
         return self.to_stream_frame()
 
 
@@ -117,9 +142,18 @@ class DatasetsFrameFlow(FrameFlow):
     logical_type = jelly.LOGICAL_STREAM_TYPE_DATASETS
 
     def frame_from_dataset(self) -> jelly.RdfStreamFrame | None:
+        """
+        Emit current flow content (dataset) as jelly frame.
+
+        Returns:
+            jelly.RdfStreamFrame | None: jelly frame or none if
+                flow is empty.
+
+        """
         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,
@@ -129,6 +163,19 @@ FLOW_DISPATCH: dict[jelly.LogicalStreamType, type[FrameFlow]] = {
 
 
 def flow_for_type(logical_type: jelly.LogicalStreamType) -> type[FrameFlow]:
+    """
+    Return flow based on logical type requested.
+
+    Args:
+        logical_type (jelly.LogicalStreamType): logical type requested.
+
+    Raises:
+        NotImplementedError: if logical type not supported.
+
+    Returns:
+        type[FrameFlow]: FrameFlow for respective logical type.
+
+    """
     try:
         return FLOW_DISPATCH[logical_type]
     except KeyError:

pyjelly/serialize/streams.py

@@ -60,6 +60,13 @@ class Stream:
         )
 
     def infer_flow(self) -> FrameFlow:
+        """
+        Return flow based on the stream options provided.
+
+        Returns:
+            FrameFlow: initialised FrameFlow object.
+
+        """
         flow: FrameFlow
         if self.options.params.delimited:
             if self.options.logical_type != jelly.LOGICAL_STREAM_TYPE_UNSPECIFIED:
@@ -79,11 +86,13 @@ class Stream:
         return flow
 
     def enroll(self) -> None:
+        """Initialize start of the stream."""
         if not self.enrolled:
             self.stream_options()
             self.enrolled = True
 
     def stream_options(self) -> None:
+        """Encode and append stream options row to the current flow."""
         self.flow.append(
             encode_options(
                 stream_types=self.stream_types,
@@ -93,6 +102,14 @@ class Stream:
         )
 
     def namespace_declaration(self, name: str, iri: str) -> None:
+        """
+        Add namespace declaration to jelly stream.
+
+        Args:
+            name (str): namespace prefix label
+            iri (str): namespace iri
+
+        """
         rows = encode_namespace_declaration(
             name=name,
             value=iri,
@@ -102,6 +119,20 @@ class Stream:
 
     @classmethod
     def for_rdflib(cls, options: SerializerOptions | None = None) -> Stream:
+        """
+        Initialize stream with RDFLib encoder.
+
+        Args:
+            options (SerializerOptions | None, optional): Stream options.
+                Defaults to None.
+
+        Raises:
+            TypeError: if Stream is passed, and not a Stream for specific physical type.
+
+        Returns:
+            Stream: initialized stream with RDFLib encoder.
+
+        """
         if cls is Stream:
             msg = "Stream is an abstract base class, use a subclass instead"
             raise TypeError(msg)
@@ -117,6 +148,19 @@ class Stream:
 
 
 def stream_for_type(physical_type: jelly.PhysicalStreamType) -> type[Stream]:
+    """
+    Give a Stream based on physical type specified.
+
+    Args:
+        physical_type (jelly.PhysicalStreamType): jelly stream physical type.
+
+    Raises:
+        NotImplementedError: if no stream for requested physical type is available.
+
+    Returns:
+        type[Stream]: jelly stream
+
+    """
     try:
         stream_cls = STREAM_DISPATCH[physical_type]
     except KeyError:
@@ -133,6 +177,21 @@ class TripleStream(Stream):
     default_delimited_flow_class: ClassVar = FlatTriplesFrameFlow
 
     def triple(self, terms: Iterable[object]) -> jelly.RdfStreamFrame | None:
+        """
+        Process one triple to Protobuf messages.
+
+        Note:
+            Adds new rows to the current flow and returns StreamFrame if
+            frame size conditions are met.
+
+        Args:
+            terms (Iterable[object]): RDF terms to encode.
+
+        Returns:
+            jelly.RdfStreamFrame | None: stream frame if
+                flow supports frames slicing and current flow is full
+
+        """
         new_rows = encode_triple(
             terms,
             term_encoder=self.encoder,
@@ -147,6 +206,17 @@ class QuadStream(Stream):
     default_delimited_flow_class: ClassVar = FlatQuadsFrameFlow
 
     def quad(self, terms: Iterable[object]) -> jelly.RdfStreamFrame | None:
+        """
+        Process one quad to Protobuf messages.
+
+        Args:
+            terms (Iterable[object]): terms to encode.
+
+        Returns:
+            jelly.RdfStreamFrame | None: stream frame if
+                flow supports frames slicing and current flow is full
+
+        """
         new_rows = encode_quad(
             terms,
             term_encoder=self.encoder,
@@ -165,6 +235,17 @@ class GraphStream(TripleStream):
         graph_id: object,
         graph: Iterable[Iterable[object]],
     ) -> Generator[jelly.RdfStreamFrame]:
+        """
+        Process one graph into a sequence of jelly frames.
+
+        Args:
+            graph_id (object): graph id (BN, Literal, iri, default)
+            graph (Iterable[Iterable[object]]): iterable of triples (graph's content)
+
+        Yields:
+            Generator[jelly.RdfStreamFrame]: jelly frames.
+
+        """
         [*graph_rows], graph_node = self.encoder.encode_any(graph_id, Slot.graph)
         kw_name = f"{Slot.graph}_{self.encoder.TERM_ONEOF_NAMES[type(graph_node)]}"
         kws: dict[Any, Any] = {kw_name: graph_node}
@@ -172,7 +253,7 @@ class GraphStream(TripleStream):
         graph_rows.append(start_row)
         self.flow.extend(graph_rows)
         for triple in graph:
-            if frame := self.triple(triple):
+            if frame := self.triple(triple):  # has frame slicing inside
                 yield frame
         end_row = jelly.RdfStreamRow(graph_end=jelly.RdfGraphEnd())
         self.flow.append(end_row)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyjelly
-Version: 0.2.3
+Version: 0.3.0
 Summary: Jelly-RDF implementation for Python
 Project-URL: Homepage, https://w3id.org/jelly/pyjelly
 Project-URL: Documentation, https://w3id.org/jelly/pyjelly