pyjelly 0.5.2__tar.gz → 0.6.0__tar.gz

{pyjelly-0.5.2 → pyjelly-0.6.0}/.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.2 → pyjelly-0.6.0}/.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.2 → pyjelly-0.6.0}/PKG-INFO

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

{pyjelly-0.5.2 → pyjelly-0.6.0}/docs/contributing/index.md

@@ -93,12 +93,6 @@ uv run mkdocs serve
 ## Making releases
 
 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.
+2. 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`!**
+3. Push the tag to GitHub: `git push origin v1.2.3`.
+4. The release will be automatically built and published to PyPI.

{pyjelly-0.5.2 → pyjelly-0.6.0}/docs/env.py

@@ -37,7 +37,7 @@ def define_env(env):
 
     try:
         python_tag_raw = subprocess.check_output(
-            ["uv", "version", "--short"], encoding="utf-8"
+            ["git", "describe", "--tags"], encoding="utf-8"
         ).strip()
     except subprocess.CalledProcessError as e:
         print("Failed to call git: ", e.returncode, e.stderr)
@@ -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.6.0/docs/examples/generic/01_serialize.py

@@ -0,0 +1,26 @@
+from pyjelly.integrations.generic.generic_sink import *
+
+# Create a generic sink object
+generic_sink = GenericStatementSink()
+
+# 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.6.0/docs/examples/generic/02_parse.py

@@ -0,0 +1,15 @@
+from pyjelly.integrations.generic.generic_sink import *
+
+# Create a generic sink object
+generic_sink = GenericStatementSink()
+
+# 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.6.0/docs/examples/generic/03_streaming.py

@@ -0,0 +1,16 @@
+from pyjelly.integrations.generic.generic_sink import *
+
+
+# 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.6.0/docs/examples/generic/04_serialize_grouped.py

@@ -0,0 +1,23 @@
+from pyjelly.integrations.generic.generic_sink import *
+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 _ in range(10):
+        sink = GenericStatementSink()
+        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.6.0/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 *
+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.6.0/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.6.0/docs/examples/generic/07_parse_flat.py

@@ -0,0 +1,29 @@
+import gzip
+import urllib.request
+
+from pyjelly.integrations.generic.generic_sink import *
+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.6.0/docs/examples/generic/08_byte_buffer.py

@@ -0,0 +1,29 @@
+import io
+
+from pyjelly.integrations.generic.generic_sink import *
+
+g1 = GenericStatementSink()
+
+g1.add(
+    Triple(
+        IRI("http://example.com/subject"),
+        IRI("http://example.com/predicate"),
+        Literal("Hello", langtag="en"),
+    )
+)
+
+# Write the data into a byte buffer (bytes type)
+with io.BytesIO() as write_buffer:
+    g1.serialize(write_buffer)
+    data = write_buffer.getvalue()
+
+print(f"Serialized data size: {len(data)} bytes")
+
+# Parse the data back
+g2 = GenericStatementSink()
+with io.BytesIO(data) as read_buffer:
+    g2.parse(read_buffer)
+
+print("\nParsed triples:")
+for statement in g2:
+    print(statement)

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

@@ -0,0 +1,94 @@
+import urllib.request, gzip, tempfile, shutil, os
+
+import networkx as nx
+import matplotlib.pyplot as plt
+from rdflib import Graph, URIRef, BNode, Literal
+from rdflib.extras.external_graph_libs import rdflib_to_networkx_graph
+
+# 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.6.0/docs/examples/rdflib/08_namespaces.py

@@ -0,0 +1,21 @@
+from rdflib import Graph, Namespace, URIRef, Literal
+from pyjelly.integrations.rdflib.serialize import SerializerOptions, StreamParameters
+
+# Build a tiny graph and bind a prefix
+g = Graph()
+EX = Namespace("http://example.org/")
+g.namespace_manager.bind("ex", EX)
+g.add((EX.alice, URIRef("http://xmlns.com/foaf/0.1/name"), Literal("Alice")))
+
+print("IN  namespaces:", dict(g.namespaces()))
+
+# Enable namespace declarations in Jelly output
+options = SerializerOptions(params=StreamParameters(namespace_declarations=True))
+
+# Serialize with options
+g.serialize("sample_test.jelly", format="jelly", options=options)
+
+# Parse back and check namespaces
+g_new = Graph()
+g_new.parse("sample_test.jelly", format="jelly")
+print("OUT namespaces:", dict(g_new.namespaces()))

pyjelly-0.6.0/docs/generic-sink.md

@@ -0,0 +1,93 @@
+# 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.
+
+### Working with byte buffers and Kafka
+
+When working with Kafka or other message brokers, you may want to write Jelly data to a byte buffer instead of a file. You can do this by using the `BytesIO` class from the `io` module:
+
+{{ code_example('generic/08_byte_buffer.py')}}
+
+The `data` variable is of type `bytes`, and can be passed to Kafka with [`KafkaProducer.send(value=data)`](https://kafka-python.readthedocs.io/en/master/), or any other API that accepts byte buffers. Same trick may be used when working with the [RDFLib integration](getting-started.md).
+
+When working with Kafka, you should be aware of the broker's offset management and partitioning strategies. Data within one Jelly stream must be strictly ordered and no frames may be dropped. If you have less strict ordering guarantees, you should split up the stream into multiple Jelly streams, each with guaranteed consistency.
+
+### 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.2 → pyjelly-0.6.0}/docs/getting-started.md

@@ -27,6 +27,22 @@ To serialize a graph to the Jelly format see:
 
 This creates a [delimited Jelly stream]({{ proto_link("user-guide/#delimited-vs-non-delimited-jelly") }}) using default options.
 
+### Including namespace declarations (prefixes)
+
+By default, Jelly serializes only triples/quads. To also include namespace declarations (prefixes) in the output, enable the `namespace_declarations` option.
+Prefixes bound in RDFLib's namespace manager will then be written into the Jelly stream and restored on parsing.
+
+{{ code_example('rdflib/08_namespaces.py') }}
+
+!!! tip
+    
+    For an existing graph you can (re)bind a prefix just before saving:
+    
+    ```python
+    g.namespace_manager.bind("ex", EX, replace=True)
+    ```
+
+
 ### Parsing a graph
 
 To load RDF data from a `.jelly` file see:
@@ -81,4 +97,10 @@ You can generally omit the `format="jelly"` parameter if the file ends in `.jell
 
 !!! warning 
 
-    Unfortunately, the way this is implemented in RDFLib is a bit wonky, so it will only work if you explicitly import `pyjelly.integrations.rdflib`, or you used `format="jelly"` in the `serialize()` or `parse()` call before.
+    Unfortunately, the way this is implemented in RDFLib is a bit wonky, so it will only work if you explicitly import `pyjelly.integrations.rdflib`, or you used `format="jelly"` in the `serialize()` or `parse()` call before.
+
+## See also
+
+- [Working with byte buffers and Kafka](generic-sink.md#working-with-byte-buffers-and-kafka)
+- [Usage without RDFLib](generic-sink.md)
+- [API reference](api.md)

{pyjelly-0.5.2 → pyjelly-0.6.0}/docs/index.md

@@ -14,9 +14,23 @@
 
 - **[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
 
+## Compatibility
+
+pyjelly is compatible with Python 3.9 and newer. Python 3.9–3.13 are tested in CI and are guaranteed to work.
+
+The following table shows the compatibility of the pyjelly implementation with other libraries:
+
+| pyjelly                                                                                                                                             | Python     | RDFLib         |
+|-----------------------------------------------------------------------------------------------------------------------------------------------------|------------|----------------|
+| [0.1.0](https://w3id.org/jelly/pyjelly/0.1.0) – **[{{ python_package_version() }}](https://w3id.org/jelly/pyjelly/{{ python_package_version() }})** | 3.9 – 3.13 | 7.x (>= 7.1.4) |
+
+
+See the **[release notes on GitHub](https://github.com/Jelly-RDF/pyjelly/releases)** for more details.
+
 ## Commercial and community support
 
 **[NeverBlink](https://neverblink.eu)** provides commercial support services for Jelly, including implementing custom features, system integrations, implementations for new frameworks, benchmarking, and more.