pyjelly 0.5.1__tar.gz → 0.5.3__tar.gz

{pyjelly-0.5.1 → pyjelly-0.5.3}/.github/workflows/ci.yml

@@ -99,3 +99,34 @@ jobs:
       id: types
       run: uv run mypy .
       if: ${{ !cancelled() && steps.install.conclusion == 'success' }}
+
+  check-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: true
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install
+        id: install
+        run: uv sync --group docs
+
+      - name: Check docs build
+        run: uv run mkdocs build -s
+
+      - name: Check docs for dead links
+        run: |
+          uv run mkdocs serve &
+          sleep 10
+          uv run linkchecker \
+            --no-warning \
+            --check-extern \
+            --ignore "https://doi.org" \
+            http://localhost:8000
+          kill $!

{pyjelly-0.5.1 → pyjelly-0.5.3}/.github/workflows/release.yml

@@ -25,7 +25,8 @@ jobs:
     permissions:
       id-token: write
       contents: write
-
+    env:
+      UV_LOCKED: 0
     steps:
       - uses: actions/checkout@v4
         with:
@@ -36,7 +37,14 @@ jobs:
       - uses: astral-sh/setup-uv@v6
         with:
           enable-cache: true
-    
+        
+      - name: Bump project version to match tag
+        id: automatic-version
+        run: |
+          set -Eeuxo pipefail
+          version="${GITHUB_REF#refs/tags/v}"
+          uv version "$version"
+      
       - name: Validate tag
         id: validate-tag
         run: |

{pyjelly-0.5.1 → pyjelly-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyjelly
-Version: 0.5.1
+Version: 0.5.3
 Summary: Jelly-RDF implementation for Python
 Project-URL: Homepage, https://w3id.org/jelly/pyjelly
 Project-URL: Documentation, https://w3id.org/jelly/pyjelly
@@ -29,7 +29,6 @@ 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'

{pyjelly-0.5.1 → pyjelly-0.5.3}/codecov.yml

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

{pyjelly-0.5.1 → pyjelly-0.5.3}/docs/contributing/index.md

@@ -94,11 +94,8 @@ uv run mkdocs serve
 
 1. Make sure you are on the `main` branch and that it is up-to-date: `git checkout main && git pull`.
 2. Checkout a new branch.
-3. Update the version in `pyproject.toml` with either:
-    - `uv version X.Y.Z`
-    - `uv version --bump major|minor|patch`
-4. Commit the changes, push the branch, and open a pull request.
-5. Once the pull request is merged, go back to the `main` branch: `git checkout main && git pull`.
-6. Create a new tag for the release. For example, for version 1.2.3: `git tag v1.2.3`. **The tag must start with `v`!**
-7. Push the tag to GitHub: `git push origin v1.2.3`.
-8. The release will be automatically built and published to PyPI.
+3. Commit the changes, push the branch, and open a pull request.
+4. Once the pull request is merged, go back to the `main` branch: `git checkout main && git pull`.
+5. Create a new tag for the release. For example, for version 1.2.3: `git tag v1.2.3`. **The tag must start with `v`!**
+6. Push the tag to GitHub: `git push origin v1.2.3`.
+7. The release will be automatically built and published to PyPI.

{pyjelly-0.5.1 → pyjelly-0.5.3}/docs/env.py

@@ -107,14 +107,20 @@ def define_env(env):
         return f"https://w3id.org/jelly/{version}/{page}"
 
     @env.macro
-    def code_example(file_name):
-        with open(f"examples/{file_name}", "r") as f:
-            code = f.read()
-        return f"""
-```python
-{code}
-```
-"""
+    def code_example(file_name, start=None, end=None):
+        try:
+            lines = open(f"examples/{file_name}").read().splitlines(keepends=True)
+        except:
+            return "```python\n\n```"
+        start_index = 0 if not start or start < 1 else start - 1
+        end_index = len(lines) if not end or end < 1 else end
+        if start_index < 0:
+            start_index = 0
+        if end_index > len(lines):
+            end_index = len(lines)
+        if start_index >= end_index:
+            return "```python\n\n```"
+        return "```python\n" + "".join(lines[start_index:end_index]) + "```"
 
     @env.macro
     def code_example_box(file_name):
@@ -132,6 +138,39 @@ def define_env(env):
     ```
 """
 
+    @env.macro
+    def snippet_raw_lines(path, start, end):
+        with open(path, "r") as f:
+            lines = f.readlines()
+        if start < 1:
+            start = 1
+        if end > len(lines):
+            end = len(lines)
+        if start > end:
+            return (
+                f"Error: invalid range {start}-{end} for file with {len(lines)} lines."
+            )
+        snippet = "".join(lines[start - 1 : end])
+        return snippet
+
+    @env.macro
+    def snippet_admonition(
+        path, start, end, title="Snippet", expanded=True, kind="note"
+    ):
+        marker = "???+" if expanded else "???"
+        snippet = snippet_raw_lines(path, start, end)
+
+        if snippet.startswith("Error:"):
+            inner = f"""```text
+{snippet}
+```"""
+        else:
+            inner = f"```python\n{snippet}```"
+        indented = "\n".join(
+            ("    " + line) if line.strip() != "" else "" for line in inner.splitlines()
+        )
+        return f'{marker} {kind} "{title}"\n{indented}'
+
     def transform_nav_item(item):
         if list(item.values())[0] == "https://w3id.org/jelly/":
             return {list(item.keys())[0]: proto_link("")}

pyjelly-0.5.3/docs/examples/generic/01_serialize.py

@@ -0,0 +1,32 @@
+from pyjelly.integrations.generic.generic_sink import (
+    IRI,
+    BlankNode,
+    GenericStatementSink,
+    Literal,
+    Triple,
+)
+
+# Create a generic sink object, identifier is optional
+generic_sink = GenericStatementSink(identifier="my_graph")
+
+# Let's add triples one by one
+generic_sink.add(
+    Triple(
+        IRI("http://example.com/subject"),
+        IRI("http://example.com/predicate"),
+        Literal("Hello", langtag="en"),
+    )
+)
+generic_sink.add(
+    Triple(
+        BlankNode("B1"),
+        IRI("http://example.com/hasName"),
+        Literal("Bob"),
+    )
+)
+
+# Write into a Jelly file
+with open("output.jelly", "wb") as out_file:
+    generic_sink.serialize(out_file)
+
+print("All done.")

pyjelly-0.5.3/docs/examples/generic/02_parse.py

@@ -0,0 +1,15 @@
+from pyjelly.integrations.generic.generic_sink import GenericStatementSink, Triple
+
+# Create a generic sink object, identifier is optional
+generic_sink = GenericStatementSink(identifier="my_graph")
+
+# Load triples from the Jelly file
+with open("output.jelly", "rb") as in_file:
+    generic_sink.parse(in_file)
+
+# Let's inspect them statement by statement
+for statement in generic_sink:
+    if isinstance(statement, Triple):
+        print(statement)
+
+print("All done.")

pyjelly-0.5.3/docs/examples/generic/03_streaming.py

@@ -0,0 +1,16 @@
+from pyjelly.integrations.generic.generic_sink import GenericStatementSink
+
+
+# Helper generator that streams statements from a Jelly file path
+def stream_triples(jelly_path):
+    generic_sink = GenericStatementSink()
+    with open(jelly_path, "rb") as f:
+        generic_sink.parse(f)
+    yield from (stmt for stmt in generic_sink)
+
+
+# Example usage, just printing:
+for triple in stream_triples("output.jelly"):
+    print(triple)
+
+print("All done.")

pyjelly-0.5.3/docs/examples/generic/04_serialize_grouped.py

@@ -0,0 +1,27 @@
+from pyjelly.integrations.generic.generic_sink import (
+    GenericStatementSink,
+    IRI,
+    Triple,
+)
+from pyjelly.integrations.generic.serialize import grouped_stream_to_file
+import random
+
+
+# Helper function to generate a generator of graphs
+def generate_sample_sinks():
+    content = (
+        IRI("http://example.com/sensor"),
+        IRI("http://example.com/humidity"),
+        IRI(f"http://example.com/{random.random()}"),
+    )
+    for i in range(10):
+        sink = GenericStatementSink(identifier=f"graph_{i}")
+        sink.add(Triple(*content))
+        yield sink
+
+
+output_file = "output.jelly"
+print(f"Streaming graphs into {output_file}…")
+with open(output_file, "wb") as out_f:
+    grouped_stream_to_file(generate_sample_sinks(), out_f)
+print("All done.")

pyjelly-0.5.3/docs/examples/generic/05_serialize_flat.py

@@ -0,0 +1,22 @@
+from pyjelly.integrations.generic.serialize import flat_stream_to_file
+from pyjelly.integrations.generic.generic_sink import Triple, IRI
+import random
+
+
+# Example generator that yields raw triples
+def generate_sample_triples():
+    content = (
+        IRI("http://example.com/sensor"),
+        IRI("http://example.com/humidity"),
+        IRI(f"http://example.com/{random.random()}"),
+    )
+    for _ in range(10):
+        yield Triple(*content)
+
+
+output_file = "flat_output.jelly"
+print(f"Streaming triples into {output_file}…")
+sample_triples = generate_sample_triples()
+with open(output_file, "wb") as out_f:
+    flat_stream_to_file(sample_triples, out_f)
+print("All done.")

pyjelly-0.5.3/docs/examples/generic/06_parse_grouped.py

@@ -0,0 +1,22 @@
+import gzip
+import urllib.request
+
+from pyjelly.integrations.generic.parse import parse_jelly_grouped
+
+# Dataset: Katrina weather measurements (10k graphs)
+# Documentation: https://w3id.org/riverbench/datasets/lod-katrina/dev
+url = "https://w3id.org/riverbench/datasets/lod-katrina/dev/files/jelly_10K.jelly.gz"
+
+# Load, uncompress .gz file, and pass to Jelly parser, all in a streaming manner
+with (
+    urllib.request.urlopen(url) as response,
+    gzip.open(response) as jelly_stream,
+):
+    # Parse into sinks (one per graph)
+    graphs = parse_jelly_grouped(jelly_stream)
+
+    # First 50
+    for i, graph in enumerate(graphs):
+        print(f"Graph {i} in the stream has {len(graph)} triples")
+        if i >= 50:
+            break

pyjelly-0.5.3/docs/examples/generic/07_parse_flat.py

@@ -0,0 +1,32 @@
+import gzip
+import urllib.request
+
+from pyjelly.integrations.generic.generic_sink import (
+    IRI,
+    Triple,
+)
+from pyjelly.integrations.generic.parse import parse_jelly_flat
+
+# Dataset: OpenStreetMap data for Denmark (first 10k objects)
+# Documentation: https://w3id.org/riverbench/datasets/osm2rdf-denmark/dev
+url = (
+    "https://w3id.org/riverbench/datasets/osm2rdf-denmark/dev/files/jelly_10K.jelly.gz"
+)
+
+# We are looking for city names in the dataset
+predicate_to_look_for = IRI("https://www.openstreetmap.org/wiki/Key:addr:city")
+city_names = set()
+
+with (
+    urllib.request.urlopen(url) as response,
+    gzip.open(response) as jelly_stream,
+):
+    for event in parse_jelly_flat(jelly_stream):
+        if isinstance(event, Triple):
+            if str(event.p) == str(predicate_to_look_for):
+                city_names.add(str(event.o))
+
+print(f"Found {len(city_names)} unique city names in the dataset.")
+print("Sample city names:")
+for city in list(city_names)[:10]:
+    print(f"- {city}")

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

@@ -0,0 +1,94 @@
+import urllib.request, gzip, tempfile, shutil, os
+from rdflib import Graph
+from rdflib.extras.external_graph_libs import rdflib_to_networkx_graph
+import networkx as nx
+import matplotlib.pyplot as plt
+from rdflib import Graph, URIRef, BNode, Literal
+
+# Filter predicates for people
+TARGET_PREDICATES = {
+    URIRef("http://www.politiquices.pt/ent2_str"),
+    URIRef("http://www.politiquices.pt/ent1_str"),
+}
+
+# URL to the dataset
+url = "https://w3id.org/riverbench/datasets/politiquices/1.0.3/files/jelly_10K.jelly.gz"
+
+# Load example jelly file
+with urllib.request.urlopen(url) as r:
+    fd, example_file = tempfile.mkstemp(suffix=".jelly")
+    os.close(fd)
+    with gzip.GzipFile(fileobj=r) as g, open(example_file, "wb") as out:
+        shutil.copyfileobj(g, out)
+
+# Parse RDF from the Jelly format
+rdf_g = Graph()
+rdf_g.parse(example_file, format="jelly")
+print(f"Loaded graph with {len(rdf_g)} instances.")
+
+# First step for filtering the graph
+rdf_g_filtered = Graph()
+for s, p, o in rdf_g.triples((None, None, None)):
+    if p in TARGET_PREDICATES:
+        rdf_g_filtered.add((s, p, o))
+
+# Just filtering the graph for clarity of visualization, can be omitted
+related = URIRef("http://www.politiquices.pt/related")
+for b in list(rdf_g_filtered.subjects()):
+    if isinstance(b, BNode):
+        ent1 = ent2 = None
+        for p, o in rdf_g_filtered.predicate_objects(b):
+            if p == URIRef("http://www.politiquices.pt/ent1_str") and isinstance(
+                o, Literal
+            ):
+                ent1 = o
+            elif p == URIRef("http://www.politiquices.pt/ent2_str") and isinstance(
+                o, Literal
+            ):
+                ent2 = o
+        if ent1 and ent2:
+            rdf_g_filtered.add((ent1, related, ent2))
+            rdf_g_filtered.add((ent2, related, ent1))
+        for triple in list(rdf_g_filtered.triples((b, None, None))):
+            rdf_g_filtered.remove(triple)
+
+# Convert to a NetworkX graph
+nx_g = rdflib_to_networkx_graph(rdf_g_filtered)
+
+# Example calculation, get the number of connected components in a graph
+num_components = nx.number_connected_components(nx_g)
+print(f"Connected components: {num_components}")
+
+# Example calculation, get top 5 objects with highest degrees, simple in NetworkX
+top5 = sorted(nx_g.degree, key=lambda x: x[1], reverse=True)[:5]
+print("Top 5 nodes sorted by degree:")
+for node, deg in top5:
+    print(f"{node}: {deg}")
+
+# Helper function
+norm = (
+    lambda n: str(n.value).strip().lower()
+    if isinstance(n, Literal)
+    else str(n).strip().lower()
+)
+
+# Example calculation, shortest path between two nodes (provided at least two nodes)
+source = next(n for n in nx_g if norm(n) == "socrates")
+target = next(n for n in nx_g if norm(n) == "obama")
+path = nx.shortest_path(nx_g, source=source, target=target)
+print(f"Shortest path from {source} to {target}: {' -> '.join(path)}")
+
+# Take first 10 nodes
+nodes = list(nx_g)[:10]
+subg = nx_g.subgraph(nodes)
+
+# Draw and display the graph
+pos_sub = nx.spring_layout(subg, k=5, iterations=200, scale=3, seed=24)
+plt.figure(figsize=(10, 10))
+
+# Introduce your own settings for display
+nx.draw_networkx(subg, pos_sub, font_size=14, node_size=220, linewidths=0.7)
+plt.axis("off")
+plt.show()
+
+print("All done.")

pyjelly-0.5.3/docs/generic-sink.md

@@ -0,0 +1,83 @@
+# Generic API
+
+This guide explains how to use pyjelly’s **generic API** to write and read RDF statements into the Jelly format without any external library.
+
+## Installation
+
+Install pyjelly from PyPI:
+
+```bash
+pip install pyjelly
+```
+
+### Requirements
+
+- Python 3.9 or newer  
+- Linux, macOS, or Windows
+
+## Usage without external libraries
+
+Unlike the example in [getting started](getting-started.md), the Generic API does not use the RDFLib or any other third-party libraries, but it works in much the same way.
+
+## Serializing statements to a Jelly file
+
+To make a set of triples/quads and write them to a Jelly file, use:
+
+{{ code_example('generic/01_serialize.py') }}
+
+This example uses pyjelly’s simple custom triple/quad type, which is easy to create and work with.
+
+## Parsing statements from a Jelly file
+
+To load triples/quads into your python object from a `.jelly` file, see:
+
+{{ code_example('generic/02_parse.py') }}
+
+Which retrieves data from your `.jelly` file.
+
+### Parsing a stream of graphs
+
+Similarly, to process a Jelly stream as a stream of graphs through generic API, see:
+
+{{ code_example('generic/06_parse_grouped.py') }}
+
+Where we use a [dataset of weather measurements](https://w3id.org/riverbench/datasets/lod-katrina/dev) and count the number of triples in each graph.
+
+### Parsing a stream of statements
+
+You can also process a Jelly stream as a flat stream with only generic API:
+
+We look through a fragment of Denmark's OpenStreetMap to find all city names:
+
+{{ code_example('generic/07_parse_flat.py') }}
+
+We get a generator of stream events, which allows us to process the file statement-by-statement, however with no external libraries used.
+
+## Streaming data
+
+If you need to process a certain quantity of statements both efficiently and iteratively, you can provide a simple generator:
+
+{{ code_example('generic/03_streaming.py') }}
+
+With this method you avoid storing all statements in memory, which greatly improves performance.
+
+### Serializing a stream of graphs
+
+If you have a generator object containing graphs, you can use a generic approach for serialization:
+
+{{ code_example('generic/04_serialize_grouped.py')}}
+
+Grouped data is streamed in its original form, no need for additional RDF libraries like RDFLib. 
+
+### Serializing a stream of statements
+
+Serializing a generator object of statements to `.jelly` file through generic API:
+
+{{ code_example('generic/05_serialize_flat.py')}}
+
+Data is transmitted and kept ordered and simple. 
+
+### See also
+
+If you are familiar with RDFLib, you can use pyjelly together with RDFLib in a similar way. [See the dedicated guide](getting-started.md).
+

{pyjelly-0.5.1 → pyjelly-0.5.3}/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Getting started
 
-This guide walks you through installing pyjelly, setting up your environment for RDFLib, and using the library's core features.
+This guide walks you through installing and working with pyjelly and RDFLib.
 
 ## Installation (with RDFLib)
 
@@ -17,7 +17,7 @@ pip install pyjelly[rdflib]
 
 ## Usage with RDFLib
 
-Once you install pyjelly, it automatically integrates with RDFLib. You can immediately serialize and parse `.jelly` files using the standard RDFLib API.
+Once you install pyjelly, it integrates automatically with RDFLib through standard RDFLib API.
 
 ### Serializing a graph
 
@@ -39,47 +39,38 @@ RDFLib will reconstruct the graph from the Jelly file.
 
 You can process a Jelly stream as a stream of graphs. A Jelly file consists of "frames" (batches of statements) – we can load each frame as a separate RDFLib graph.
 
-In this example, we use a [dataset of weather measurements](https://w3id.org/riverbench/datasets/lod-katrina/dev), which is an RDF graph stream. We count the number of triples in each graph:
+In this example, we use a [dataset of weather measurements](https://w3id.org/riverbench/datasets/lod-katrina/dev). We count the number of triples in each graph:
 
 {{ code_example('rdflib/04_parse_grouped.py') }}
 
-Because `parse_jelly_grouped` returns a generator, each iteration receives **one** graph, keeping memory usage bounded to the current frame. So, large datasets and live streams can be processed efficiently.
+Each iteration receives only **one** graph, allowing for processing large datasets efficiently, without exhausting memory.
 
 ### Parsing a stream of triples
 
 You can also process a Jelly stream as a flat stream of triples.
 
-In this more complex example, we look through a fragment of Denmark's OpenStreetMap to find all city names:
+We look through a fragment of Denmark's OpenStreetMap to find all city names:
 
 {{ code_example('rdflib/05_parse_flat.py') }}
 
-`parse_jelly_flat` returns a generator of stream events (i.e., statements parsed). This allows you to efficiently process the file triple-by-triple and build custom aggregations from the stream.
+`parse_jelly_flat` returns a generator of stream events (i.e., statements parsed). This case allows you to efficiently process the file triple-by-triple and build custom aggregations from the stream.
 
 ### 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: 
+If you have a generator object containing graphs, you can easily serialize it into the Jelly format: 
 
 {{ code_example('rdflib/06_serialize_grouped.py')}}
 
-This method allows for transmitting logically grouped data, preserving their original division.
+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: 
+If you have a generator object containing statements, you can easily serialize it into the Jelly format: 
 
 {{ 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 its the simplicity and order.
-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.
+The flat method transmits the data as a continuous sequence of statements, keeping it simple and ordered.
 For more precise control over frame serialization you can use [lower-level API](api.md)
 
 ### File extension support

{pyjelly-0.5.1 → pyjelly-0.5.3}/docs/index.md

@@ -14,6 +14,7 @@
 
 - **[Getting started](getting-started.md)**
 - **[Overview and supported features](overview.md)**
+- **[Generic interface (usage without RDFLib)](generic-sink.md)**
 - **[API reference](api.md)**
 - **[Contributing](contributing/index.md)** – how to report issues, contribute code, and request features