pyjelly 0.4.0__tar.gz → 0.5.0__tar.gz

{pyjelly-0.4.0 → pyjelly-0.5.0}/.github/workflows/ci.yml

@@ -67,15 +67,23 @@ jobs:
       id: install
       run: uv sync
 
-    - name: Install latest Jelly CLI
-      id: install-cli
-      run: ./scripts/download-cli /opt/jelly-cli && echo '/opt' >> $GITHUB_PATH
+    - name: Install jelly-cli
+      uses: jelly-rdf/setup-cli@v1
       if: ${{ !cancelled() && steps.install.conclusion == 'success' && matrix.conformance-tests }}
 
     - name: Run unit tests
-      id: unit-tests
-      run: uv run pytest -svv
-      if: ${{ !cancelled() && steps.install.conclusion == 'success' }}
+      run: uv run pytest -vv
+      if: ${{ !cancelled() && steps.install.conclusion == 'success' && !matrix.conformance-tests }}
+
+    - name: Run unit tests (with conformance tests and coverage)
+      run: uv run pytest -vv --cov --cov-branch --cov-report=xml
+      if: ${{ !cancelled() && steps.install.conclusion == 'success' && matrix.conformance-tests }}
+
+    - name: Upload coverage reports to Codecov
+      uses: codecov/codecov-action@v5
+      if: ${{ !cancelled() && steps.install.conclusion == 'success' && matrix.conformance-tests }}
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
 
     - name: Check formatting
       id: formatting

{pyjelly-0.4.0 → pyjelly-0.5.0}/PKG-INFO

@@ -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 → pyjelly-0.5.0}/README.md

@@ -1,4 +1,4 @@
-[![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.5.0/codecov.yml

@@ -0,0 +1,4 @@
+ignore:
+  - "docs"
+  - "tests"
+  - "examples"

pyjelly-0.5.0/docs/examples/neo4j_integration/01_rdflib_neo4j_parse_grouped.py

@@ -0,0 +1,49 @@
+import urllib.request
+from neo4j import GraphDatabase
+from rdflib import Graph
+from rdflib_neo4j import Neo4jStoreConfig, Neo4jStore, HANDLE_VOCAB_URI_STRATEGY
+
+# Example file from the Riverbench
+example_file, _ = urllib.request.urlretrieve("https://w3id.org/riverbench/v/dev.jelly")
+
+# Please introduce your credentials
+aura_db_uri = "aura_db_uri"
+aura_db_username = "neo4j"
+aura_db_pwd = "aura_db_pwd"
+
+# Prepare the authentication data to the Aura database
+auth_data = {
+    "uri": aura_db_uri,
+    "database": "neo4j",
+    "user": aura_db_username,
+    "pwd": aura_db_pwd,
+}
+
+# Prepare the configuration for neo4j store object
+config = Neo4jStoreConfig(
+    auth_data=auth_data,
+    handle_vocab_uri_strategy=HANDLE_VOCAB_URI_STRATEGY.IGNORE,
+    batching=True,
+)
+
+# Make a graph with Neo4jStore object
+neo4j_sink = Graph(store=Neo4jStore(config=config))
+
+# Parse the file into the AuraDB
+neo4j_sink.parse(example_file, format="jelly")
+
+# Close the stream
+neo4j_sink.close(True)
+
+# Cypher query to check loaded data
+with GraphDatabase.driver(
+    aura_db_uri, auth=(aura_db_username, aura_db_pwd)
+).session() as session:
+    count = session.run("MATCH ()-[r]->() RETURN count(r) AS c").single()["c"]
+    print(f"Loaded {count} triples")
+    for r in session.run(
+        "MATCH (s)-[r]->(o) RETURN s.uri AS s, type(r) AS p, coalesce(o.uri,o.name) AS o LIMIT 5"
+    ):
+        print(r["s"], f"-[{r['p']}]->", r["o"])
+
+print("All done.")

pyjelly-0.5.0/docs/examples/networkx_integration/01_parse_calculate_visualize.py

@@ -0,0 +1,44 @@
+import urllib.request
+from rdflib import Graph
+from rdflib.extras.external_graph_libs import rdflib_to_networkx_graph
+import networkx as nx
+import matplotlib.pyplot as plt
+
+# Example Jelly file
+example_file, _ = urllib.request.urlretrieve("https://w3id.org/riverbench/v/dev.jelly")
+
+# Parse RDF from the Jelly format
+rdf_g = Graph()
+rdf_g.parse(example_file, format="jelly")
+
+# Convert to a NetworkX graph from RDFLib
+nx_g = rdflib_to_networkx_graph(rdf_g)
+
+# Example calculation, get the number of connected components in a graph
+num_components = nx.number_connected_components(nx_g)
+
+# Example calculation, get top 5 objects with highest degrees, something simple in NetworkX
+top5 = sorted(nx_g.degree, key=lambda x: x[1], reverse=True)[:5]
+
+# Example calculation, shortest path between two nodes
+# Provide two example nodes in a graph
+source, target = list(nx_g.nodes)[0], list(nx_g.nodes)[-1]
+path = nx.shortest_path(nx_g, source=source, target=target)
+
+# Draw and display the graph
+pos = nx.spring_layout(nx_g)
+plt.figure(figsize=(10, 10))
+
+# Introduce your own settings for display
+nx.draw_networkx(
+    nx_g, pos, with_labels=True, font_size=4, node_size=300, linewidths=0.6
+)
+plt.axis("off")
+plt.show()
+
+print(f"Connected components: {num_components}")
+print("Top 5 nodes sorted by degree:")
+for node, deg in top5:
+    print(f"{node}: {deg}")
+print(f"Shortest path from {source} to {target}: {' -> '.join(path)}")
+print("All done.")

pyjelly-0.5.0/docs/examples/networkx_integration/02_serialize.py

@@ -0,0 +1,28 @@
+import networkx as nx
+from rdflib import Graph, URIRef, Namespace
+from rdflib.namespace import RDF
+
+# An example NetworkX graph
+nx_g = nx.Graph()
+nx_g.add_node("http://example.org/A")
+nx_g.add_node("http://example.org/B")
+nx_g.add_edge("http://example.org/A", "http://example.org/B")
+
+# We define RDFLib graph for further conversion
+rdf_g = Graph()
+
+# Example namespace
+ex = Namespace("http://example.org/ns#")
+
+# Add triples through node information in NetworkX graph
+for node_uri, data in nx_g.nodes(data=True):
+    subj = URIRef(node_uri)
+    rdf_g.add((subj, RDF.type, ex.Node))
+
+# Add triples through edge information in NetworkX graph
+for u, v, attr in nx_g.edges(data=True):
+    rdf_g.add((URIRef(u), ex.connectedTo, URIRef(v)))
+
+# Serialize graph into a .jelly file
+rdf_g.serialize(destination="networkx_graph.jelly", format="jelly")
+print("All done.")

{pyjelly-0.4.0 → pyjelly-0.5.0}/docs/examples/rdflib/04_parse_grouped.py

@@ -15,3 +15,6 @@ with (
     graphs = parse_jelly_grouped(jelly_stream)
     for i, graph in enumerate(graphs):
         print(f"Graph {i} in the stream has {len(graph)} triples")
+        # Limit to 50 graphs for demonstration -- the rest will not be parsed
+        if i >= 50:
+            break

pyjelly-0.5.0/docs/examples/rdflib/07_serialize_flat.py

@@ -0,0 +1,19 @@
+from pyjelly.integrations.rdflib.serialize import flat_stream_to_file
+from rdflib import Literal, Namespace
+import random
+
+
+# example generator with triples statements
+def generate_sample_triples():
+    ex = Namespace("http://example.org/")
+    for _ in range(10):
+        yield (ex.sensor, ex.temperature, Literal(random.random()))
+
+
+output_file_name = "flat_output.jelly"
+
+print(f"Streaming triples into {output_file_name}…")
+sample_triples = generate_sample_triples()
+with open(output_file_name, "wb") as out_file:
+    flat_stream_to_file(sample_triples, out_file)
+print("All done.")

pyjelly-0.5.0/docs/external-integration.md

@@ -0,0 +1,69 @@
+# Pyjelly integration with external libraries
+
+This section describes how to integrate useful third‑party libraries that utilize RDFLib.  
+In order to proceed with the content of the document, one should be acquainted with the [getting-started.md](getting-started.md) file.
+
+## Neo4j - rdflib
+
+The Neo4j RDFLib library is a Python plugin that lets you use RDFLib’s API to parse RDF triples directly in a Neo4j graph database.  
+Because Neo4j integrates well with the baseline RDFLib objects, which is also true for pyjelly, both libraries can be easily combined.  
+
+In further steps we will exemplify the integration, however first, (in our pyjelly environment) we should install rdflib-neo4j:  
+```
+pip install rdflib-neo4j
+```
+
+For more information, one should visit the following references found on the rdflib-neo4j original sources, which formed the base of
+the following document:  
+    - [github.com/neo4j-labs/rdflib-neo4j](https://github.com/neo4j-labs/rdflib-neo4j)  
+    - [neo4j.com/labs/rdflib-neo4j/](https://neo4j.com/labs/rdflib-neo4j/)  
+
+### Configure Your AuraDB Connection
+
+Before running the example code, make sure to provide your own credentials to the AuraDB instance listed below:
+```
+AURA_DB_URI
+AURA_DB_USERNAME
+AURA_DB_PWD
+```
+
+### Parsing data into neo4j from a jelly file
+
+To parse data into the neo4j database from `.jelly` file use the following example:
+
+{{ code_example('neo4j_integration/01_rdflib_neo4j_parse_grouped.py') }}
+
+which parses the data from `.jelly` file into the user's AuraDB database.
+
+## NetworkX
+
+NetworkX is a Python package for the creation, manipulation, and analysis of the structure, dynamics, and functions of networks represented as graphs.
+Due to its seamless integration with RDFlib and PyJelly via its conversion utilities, these libraries can be easily combined for graph analysis and transformation tasks.
+
+To successfully go through the use cases, one should primarily install the following libraries:
+```
+pip install networkx==3.2.1 matplotlib==3.9.4
+```
+
+To get more information about the NetworkX itself, see the package's documentation and other useful utilities:  
+    - [networkx.org/documentation/stable/auto_examples](https://networkx.org/documentation/stable/auto_examples/index.html)  
+    - [rdflib.readthedocs.io/en/7.1.0/_modules/rdflib/extras/external_graph_libs.html](https://rdflib.readthedocs.io/en/7.1.0/_modules/rdflib/extras/external_graph_libs.html)  
+    - [github.com/networkx/networkx](https://github.com/networkx/networkx)  
+
+In the following sub-sections, we will describe a few useful and baseline use cases for performing integration between the modules.
+
+### Parse graph into NetworkX object, visualize it, calculate useful graph-based characteristics
+
+To load data into a NetworkX object, starting from a `.jelly` file, and (optionally) calculate some practical graph characteristics, one can look into the example:
+
+{{ code_example('networkx_integration/01_parse_calculate_visualize.py') }}
+
+which loads the data from RDFLib graph into equivalent NetworkX graph, performs computation of useful graph theory metrics and visualizes the graph.
+
+### Transform and serialize NetworkX graph
+
+To transform a NetworkX graph into RDFLib graph and perform its serialization into the `.jelly` format, look into the example:
+
+{{ code_example('networkx_integration/02_serialize.py') }}
+
+Which converts an example-defined NetworkX graph into RDFLib graph and performs its serialization.

{pyjelly-0.4.0 → pyjelly-0.5.0}/docs/getting-started.md

@@ -62,6 +62,24 @@ If you have a generator object containing graphs, you can easily serialize it in
 This method allows for transmitting logically grouped data, preserving their original division.
 For more precise control over frame serialization you can use [lower-level API](api.md)
 
+### Serializing a stream of statements
+
+If you have a generator object containing statements, you can easily serialize it into the Jelly format, like in the following example: 
+
+{{ code_example('rdflib/07_serialize_flat.py')}}
+
+The flat method transmits the data as a continuous sequence of individual statements (i.e., triples or quads), keeping the simplicity and order of the data.
+For more precise control over frame serialization you can use [lower-level API](api.md)
+
+### Serializing a stream of graphs
+
+If you have a generator object containing graphs, you can easily serialize it into the Jelly format, like in the following example: 
+
+{{ code_example('rdflib/06_serialize_grouped.py')}}
+
+This method allows for transmitting logically grouped data, preserving their original division.
+For more precise control over frame serialization you can use [lower-level API](api.md)
+
 ### File extension support
 
 You can generally omit the `format="jelly"` parameter if the file ends in `.jelly` – RDFLib will auto-detect the format:

{pyjelly-0.4.0 → pyjelly-0.5.0}/docs/index.md

@@ -1,6 +1,6 @@
 # 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)
+[![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** is a Python implementation of [Jelly]({{ proto_link("") }}), a high-performance binary serialization format and streaming protocol for RDF knowledge graphs. It works great with [rdflib](getting-started.md).
 
@@ -14,6 +14,7 @@
 
 - **[Getting started](getting-started.md)**
 - **[Overview and supported features](overview.md)**
+- **[Integration with Python RDF Tools](external-integration.md)**
 - **[API reference](api.md)**
 - **[Contributing](contributing/index.md)** – how to report issues, contribute code, and request features
 

{pyjelly-0.4.0 → pyjelly-0.5.0}/mkdocs.yml

@@ -120,6 +120,7 @@ nav:
   - Home: "index.md"
   - Getting started: "getting-started.md"
   - Overview and supported features: "overview.md"
+  - Integration with Python RDF Tools: "external-integration.md"
   - API reference: "api.md"
   - Contributing:
       - "contributing/index.md"

pyjelly-0.5.0/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)