pyjelly 0.5.2__tar.gz → 0.5.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyjelly
-Version: 0.5.2
+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

{pyjelly-0.5.2 → 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.2 → 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.2 → 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
 

pyjelly-0.5.3/docs/networkx-integration.md

@@ -0,0 +1,101 @@
+# NetworkX
+
+NetworkX is a Python package that represents complex networks as graphs and allows for their manipulation.
+
+Install the following libraries:
+
+```bash
+pip install pyjelly[rdflib] networkx==3.2.1 matplotlib==3.9.4
+```
+
+Below there are few useful examples to follow.
+
+## Parse graph, show it
+
+Let's investigate relationships between worldwide political figures (support and opposition relations)!
+We are given a graph in `.jelly` containing information about political stances extracted from news articles.  
+Let's dive in and get some useful information!
+
+We can easily load it:  
+
+{{ code_example('networkx_integration/01_parse_calculate_visualize.py', 24, 27) }}
+
+Output from `print()`:
+
+```text
+Loaded graph with 90000 instances.
+```
+
+Convert it into a convenient NetworkX graph:
+
+{{ code_example('networkx_integration/01_parse_calculate_visualize.py', 55, 56) }}
+
+Is our graph fully connected? It's important to know (are all political relations tied together?), let's check here:
+
+{{ code_example('networkx_integration/01_parse_calculate_visualize.py', 58, 60) }}
+
+Output from `print()`:
+
+```text
+Connected components: 24
+```
+
+Which nodes are connected the most (have most connections?), let's see top 5 of them:
+
+{{ code_example('networkx_integration/01_parse_calculate_visualize.py', 62, 66) }}
+
+Output from `print()`:
+
+```text
+Top 5 nodes sorted by degree:
+Socrates: 241
+Cavaco: 189
+Passos Coelho: 187
+Costa: 179
+Antonio Costa: 168
+```
+
+What is the shortest path between two nodes? We can check:
+
+{{ code_example('networkx_integration/01_parse_calculate_visualize.py', 75, 79) }}
+
+Output from `print()`:
+
+```text
+Shortest path from Socrates to Obama: Socrates -> Marcelo Rebelo de Sousa -> Durao Barroso -> Obama
+```
+
+However, it's best to see the full picture (for our example we truncate to 10 nodes for clarity):
+
+{{ code_example('networkx_integration/01_parse_calculate_visualize.py', 81, 92) }}
+
+The graph presents as follows
+
+<div style="text-align:center;">
+  <img src="../assets/images/networkx_visualization_example.png" width="600" loading="lazy" alt="NetworkX visualization example" />
+</div>
+
+
+In summary:
+
+{{ snippet_admonition('examples/networkx_integration/01_parse_calculate_visualize.py', 0, 95, title="Entire example", expanded=False) }}
+
+We converted an RDFLib graph to NetworkX, calculated insightful metrics and visualized the graph.  
+
+For more info about the data source please see the [Politiquices dataset in RiverBench](https://riverbench.github.io/v/2.1.0/datasets/politiquices/) and its [original source (Portuguese)](http://www.politiquices.pt/).
+
+## Serialize NetworkX graph
+
+This example shows how to write a NetworkX graph to a Jelly file.:
+
+{{ code_example('networkx_integration/02_serialize.py') }}
+
+Which converts the NetworkX graph into an RDFLib `Graph` instance and serializes it.
+
+## Related sources
+
+To get more information, see the following:
+
+- [NetworkX examples](https://networkx.org/documentation/stable/auto_examples/index.html)
+- [NetworkX repository (github)](https://github.com/networkx/networkx)
+- [RDFLib external graph integration](https://rdflib.readthedocs.io/en/7.1.0/_modules/rdflib/extras/external_graph_libs.html)

{pyjelly-0.5.2 → pyjelly-0.5.3}/docs/overview.md

@@ -8,6 +8,7 @@ With Jelly, you can transmit both flat and structured streams of triples, quads,
 
 * Full support for reading and writing Jelly-encoded RDF data
 * Seamless integration with [RDFLib](https://rdflib.readthedocs.io/) (*"works just like Turtle"*)
+* Standalone generic API with no third-party dependencies [Generic API](generic-sink.md)
 * Support for all Jelly stream types
 * Tools for working with delimited and non-delimited Jelly streams
 * Fine-grained control over serialization options, compression, and framing
@@ -43,3 +44,8 @@ To learn how to use popular third-party libraries that connect with RDFLib, plea
 
 - **[RDFLib-Neo4j integration](rdflib-neo4j-integration.md)**
 - **[NetworkX integration](networkx-integration.md)**
+
+## Generic API
+
+pyjelly includes its own [generic API](generic-sink.md) for working with RDF data (no RDFLib or other external RDF libraries required).  
+It provides simple, built-in types for triples and quads, allowing you to create, read, and write data directly in the Jelly format.

{pyjelly-0.5.2 → pyjelly-0.5.3}/docs/rdflib-neo4j-integration.md

@@ -12,7 +12,7 @@ pip install pyjelly[rdflib] rdflib-neo4j
 
 To parse data from a `.jelly` file into the Neo4j database, use the following example (insert your own credentials to AuraDB):
 
-{{ code_example('neo4j_integration/01_rdflib_neo4j_parse_grouped.py') }}
+{{ snippet_admonition('examples/neo4j_integration/01_rdflib_neo4j_parse_grouped.py',0, 50, title="Parsing", expanded=True) }}
 
 which inserts your data into your AuraDB database.
 

{pyjelly-0.5.2 → pyjelly-0.5.3}/mkdocs.yml

@@ -101,9 +101,6 @@ theme:
   icon:
     repo: fontawesome/brands/github
 
-extra_css:
-  - stylesheets/extra.css
-
 extra:
   version:
     provider: mike
@@ -121,6 +118,7 @@ nav:
   - User guide:
       - Getting started (RDFLib): "getting-started.md"
       - Overview and supported features: "overview.md"
+      - Generic API (no RDFLib): "generic-sink.md"
       - Neo4j: "rdflib-neo4j-integration.md"
       - NetworkX: "networkx-integration.md"
   - API reference: "api.md"