pyjelly 0.1.0__tar.gz → 0.2.0__tar.gz

pyjelly-0.1.0/.github/workflows/quality.yml → pyjelly-0.2.0/.github/workflows/ci.yml

@@ -1,15 +1,15 @@
-name: quality-gate
+name: ci
 
 on:
   push:
-    branches:
-    -  main
+    branches: [main]
+    tags: ['v*']
   pull_request:
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
-    
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 env:
   FORCE_COLOR: 1
   PY_COLORS: 1
@@ -21,9 +21,9 @@ defaults:
     shell: bash
 
 jobs:
-  quality-gate:
+  check:
     if: ${{ github.actor != 'dependabot[bot]' && !cancelled() }}
-    name: ${{ matrix.runs-test-cases && '(test cases) ' || '' }}${{ matrix.version }} ${{matrix.platform}}
+    name: ${{ matrix.conformance-tests && '(conformance) ' || '' }}${{ matrix.version }} ${{matrix.platform}}
     runs-on: ${{ matrix.platform }}
 
     env:
@@ -33,14 +33,9 @@ jobs:
       fail-fast: false
       # https://blog.jaraco.com/efficient-use-of-ci-resources/
       matrix:
-        runs-test-cases:
-        - false
-        version:
-        - '3.9'
-        - '3.13'
-        platform:
-        - ubuntu-latest
-        - macos-latest
+        conformance-tests: [false]
+        version: ['3.9', '3.13']
+        platform: [ubuntu-latest, macos-latest]
         include:
         - version: '3.10'
           platform: ubuntu-latest
@@ -50,7 +45,7 @@ jobs:
           platform: ubuntu-latest
         - version: '3.13'
           platform: ubuntu-latest
-          runs-test-cases: true
+          conformance-tests: true
         - version: '3.14'
           platform: ubuntu-latest
         - version: pypy3.10
@@ -74,7 +69,7 @@ jobs:
     - name: Install latest Jelly CLI
       id: install-cli
       run: ./scripts/download-cli /opt/jelly-cli && echo '/opt' >> $GITHUB_PATH
-      if: ${{ !cancelled() && steps.install.conclusion == 'success' && matrix.runs-test-cases }}
+      if: ${{ !cancelled() && steps.install.conclusion == 'success' && matrix.conformance-tests }}
 
     - name: Run unit tests
       id: unit-tests

pyjelly-0.2.0/.github/workflows/news.yml

@@ -0,0 +1,29 @@
+name: news
+
+on:
+  pull_request:
+    types: [labeled, unlabeled, opened, reopened, synchronize]
+
+env:
+  UV_LOCKED: 1
+  UV_NO_SYNC: 1
+
+jobs:
+  check-news-entry:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        # `towncrier check` runs `git diff --name-only origin/main...`, which
+        # needs a non-shallow clone.
+        fetch-depth: 0
+    - uses: astral-sh/setup-uv@v6
+      with:
+        enable-cache: true
+    - name: Install dependencies
+      run: uv sync --group maintenance
+    - name: Check news entry
+      if: >
+        !contains(github.event.pull_request.labels.*.name, 'skip news')
+        && !contains(github.event.pull_request.user.login, '[bot]')
+      run: uv run towncrier check --compare-with origin/${{github.base_ref}}

pyjelly-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,88 @@
+name: release
+
+permissions:
+  contents: write
+  pull-requests: write
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+
+defaults:
+  run:
+    shell: bash
+
+env:
+  UV_LOCKED: 1
+  UV_NO_SYNC: 1
+
+jobs:
+  release:
+    if: ${{ github.ref_type == 'tag' }}
+    name: Release to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    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: Validate tag
+        id: validate-tag
+        run: |
+          set -Eeuxo pipefail
+
+          project_version=v$(uv version --short)
+          tag=${GITHUB_REF#refs/tags/}
+
+          [[ "$tag" == "$project_version" ]] || {
+            echo "Tag $tag does not match project version $project_version"
+            exit 1
+          }
+
+      - name: Build package distributions
+        id: build
+        run: uv build --out-dir dist
+
+      - name: Publish package distributions
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  release-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+  
+      - name: Deploy site
+        run: |
+          set -Eeuxo pipefail
+          export TAG='${{ github.ref_name }}'
+          uv sync --group docs
+          git fetch origin gh-pages --depth=1
+
+          git config user.name github-actions[bot]
+          git config user.email github-actions[bot]@users.noreply.github.com
+
+          if [[ $TAG == v* ]]
+          then
+            V_MAJOR=`echo ${TAG#v} | awk -F '.' '{print $1}'`
+            V_MINOR=`echo ${TAG#v} | awk -F '.' '{print $2}'`
+            uv run mike deploy --push --alias-type=redirect --update-aliases "${V_MAJOR}.${V_MINOR}.x" stable "${TAG#v}"
+          else
+            uv run mike deploy --push --alias-type=redirect --title "Development version" --update-aliases dev latest
+          fi

pyjelly-0.2.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+## [v0.2.0](https://github.com/Jelly-RDF/pyjelly/tree/v0.2.0) (2025-06-03)
+
+### Added
+
+- Added changelog ([#103](https://github.com/Jelly-RDF/pyjelly/issues/103))
+- Stream types inference ([#120](https://github.com/Jelly-RDF/pyjelly/issues/120))
+
+### Changed
+
+- RDFLib exposed as an optional dependency installable with `pyjelly[rdflib]` ([#129](https://github.com/Jelly-RDF/pyjelly/issues/129))
+
+### Fixed
+
+- A bug where empty prefixes were not serialized ([#127](https://github.com/Jelly-RDF/pyjelly/issues/127))
+
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).<br/>
+This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+<!-- insertion marker -->

pyjelly-0.2.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: pyjelly
+Version: 0.2.0
+Summary: Jelly RDF implementation for Python
+Author-email: Bartosz Sławecki <bartosz@neverblink.eu>, Anastasiya Danilenka <anastasiya@neverblink.eu>
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: protobuf>=5.29.3
+Requires-Dist: typing-extensions>=4.12.2
+Provides-Extra: rdflib
+Requires-Dist: rdflib>=7.1.4; extra == 'rdflib'
+Description-Content-Type: text/markdown
+
+# pyjelly
+
+> [!Warning]
+> pyjelly is in early development! The API is unstable and breaking changes may occur in the coming weeks.
+
+**pyjelly** is a Python implementation of [Jelly](http://w3id.org/jelly), a high-performance binary serialization format and streaming protocol for RDF knowledge graphs. 
+
+**Documentation, usage guide and more: https://w3id.org/jelly/pyjelly**
+
+## Contributing and support
+
+This project is still in early development—you can stay tuned by [watching this repository](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications#subscription-options).
+
+You can also join the **[Jelly Discord chat](https://discord.gg/A8sN5XwVa5)** to ask questions about pyjelly and to be up-to-date with the development activities.
+
+### Commercial support
+
+**[NeverBlink](https://neverblink.eu)** provides commercial support services for Jelly, including implementing custom features, system integrations, implementations for new frameworks, benchmarking, and more.
+
+## Contributing
+
+If you'd like to contribute, check out our [contributing guidelines](CONTRIBUTING.md).
+
+## License
+
+The pyjelly library is licensed under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0).
+
+----
+
+The development of the Jelly protocol, its implementations, and supporting tooling was co-funded by the European Union. **[More details](https://w3id.org/jelly/dev/licensing/projects)**.

pyjelly-0.2.0/docs/changelog.md

@@ -0,0 +1 @@
+../CHANGELOG.md

{pyjelly-0.1.0 → pyjelly-0.2.0}/docs/getting-started.md

@@ -2,12 +2,12 @@
 
 This guide shows how to install pyjelly and prepare your environment for use with RDFLib.
 
-## Installation
+## Installation (with RDFLib)
 
 Install pyjelly from PyPI:
 
 ```
-pip install pyjelly
+pip install pyjelly[rdflib]
 ```
 
 pyjelly requires **Python 3.9** or newer and works on all major platforms (Linux, macOS, Windows).
@@ -29,16 +29,7 @@ from pyjelly import jelly
 
 g = Graph()
 g.parse("http://xmlns.com/foaf/spec/index.rdf")
-
-options = StreamOptions(
-    stream_types=StreamTypes(
-        physical_type=jelly.PHYSICAL_STREAM_TYPE_TRIPLES,
-        logical_type=jelly.LOGICAL_STREAM_TYPE_FLAT_TRIPLES,
-    )
-)
-stream = Stream.from_options(options)
-
-g.serialize(destination="foaf.jelly", format="jelly", stream=stream)
+g.serialize(destination="foaf.jelly", format="jelly")
 ```
 
 This creates a [delimited Jelly stream]({{ proto_link("user-guide/#delimited-vs-non-delimited-jelly") }}) using default options.

{pyjelly-0.1.0 → pyjelly-0.2.0}/mkdocs.yml

@@ -117,6 +117,7 @@ nav:
   - Home: "index.md"
   - Getting started: "getting-started.md"
   - Overview and supported features: "overview.md"
+  - Changelog: "changelog.md"
   - API reference: "api.md"
   - Contributing:
       - "contributing/index.md"

{pyjelly-0.1.0 → pyjelly-0.2.0}/pyjelly/integrations/rdflib/parse.py

@@ -12,8 +12,8 @@ from rdflib.store import Store
 
 from pyjelly import jelly
 from pyjelly.errors import JellyConformanceError
-from pyjelly.options import StreamOptions
-from pyjelly.parse.decode import Adapter, Decoder
+from pyjelly.options import StreamTypes
+from pyjelly.parse.decode import Adapter, Decoder, ParserOptions
 from pyjelly.parse.ioutils import get_options_and_frames
 
 
@@ -40,11 +40,9 @@ class RDFLibAdapter(Adapter):
         return rdflib.Literal(lex, lang=language, datatype=datatype)
 
 
-def _adapter_missing(feature: str, *, options: StreamOptions) -> Never:
-    physical_type_name = jelly.PhysicalStreamType.Name(
-        options.stream_types.physical_type
-    )
-    logical_type_name = jelly.LogicalStreamType.Name(options.stream_types.logical_type)
+def _adapter_missing(feature: str, *, stream_types: StreamTypes) -> Never:
+    physical_type_name = jelly.PhysicalStreamType.Name(stream_types.physical_type)
+    logical_type_name = jelly.LogicalStreamType.Name(stream_types.logical_type)
     msg = (
         f"adapter with {physical_type_name} and {logical_type_name} "
         f"does not implement {feature}"
@@ -55,9 +53,9 @@ def _adapter_missing(feature: str, *, options: StreamOptions) -> Never:
 class RDFLibTriplesAdapter(RDFLibAdapter):
     graph: Graph
 
-    def __init__(self, graph: Graph, options: StreamOptions) -> None:
+    def __init__(self, options: ParserOptions, store: Store | str = "default") -> None:
         super().__init__(options=options)
-        self.graph = graph
+        self.graph = Graph(store=store)
 
     @override
     def triple(self, terms: Iterable[Any]) -> Any:
@@ -77,26 +75,39 @@ class RDFLibTriplesAdapter(RDFLibAdapter):
             jelly.LOGICAL_STREAM_TYPE_FLAT_TRIPLES,
         ):
             return None
-        return _adapter_missing("interpreting frames", options=self.options)
+        return _adapter_missing(
+            "interpreting frames",
+            stream_types=self.options.stream_types,
+        )
 
 
 class RDFLibQuadsBaseAdapter(RDFLibAdapter):
-    def __init__(self, dataset: Dataset, options: StreamOptions) -> None:
+    def __init__(
+        self,
+        options: ParserOptions,
+        store: Store | str,
+    ) -> None:
         super().__init__(options=options)
-        self.dataset = dataset
+        self.store = store
+        self.dataset = self.new_dataset()
+
+    def new_dataset(self) -> Dataset:
+        return Dataset(store=self.store, default_union=True)
 
     @override
     def frame(self) -> Dataset | None:
         if self.options.stream_types.logical_type == jelly.LOGICAL_STREAM_TYPE_DATASETS:
             this_dataset = self.dataset
-            self.dataset = Dataset(store=self.dataset.store)
+            self.dataset = self.new_dataset()
             return this_dataset
         if self.options.stream_types.logical_type in (
             jelly.LOGICAL_STREAM_TYPE_UNSPECIFIED,
             jelly.LOGICAL_STREAM_TYPE_FLAT_QUADS,
         ):
             return None
-        return _adapter_missing("interpreting frames", options=self.options)
+        return _adapter_missing(
+            "interpreting frames", stream_types=self.options.stream_types
+        )
 
 
 class RDFLibQuadsAdapter(RDFLibQuadsBaseAdapter):
@@ -112,8 +123,12 @@ class RDFLibQuadsAdapter(RDFLibQuadsBaseAdapter):
 class RDFLibGraphsAdapter(RDFLibQuadsBaseAdapter):
     _graph: Graph | None = None
 
-    def __init__(self, dataset: Dataset, options: StreamOptions) -> None:
-        super().__init__(dataset=dataset, options=options)
+    def __init__(
+        self,
+        options: ParserOptions,
+        store: Store | str,
+    ) -> None:
+        super().__init__(options=options, store=store)
         self._graph = None
 
     @property
@@ -144,90 +159,134 @@ class RDFLibGraphsAdapter(RDFLibQuadsBaseAdapter):
         if self.options.stream_types.logical_type == jelly.LOGICAL_STREAM_TYPE_DATASETS:
             this_dataset = self.dataset
             self._graph = None
-            self.dataset = Dataset(store=self.dataset.store)
+            self.dataset = self.new_dataset()
             return this_dataset
         return super().frame()
 
 
-def parse_flat_stream(
+def parse_flat_triples_stream(
     frames: Iterable[jelly.RdfStreamFrame],
-    sink: Graph,
-    options: StreamOptions,
+    options: ParserOptions,
+    store: Store | str = "default",
+    identifier: str | None = None,
 ) -> Dataset | Graph:
-    assert options.stream_types.flat
-    ds = None
-
-    adapter: Adapter
-    if options.stream_types.physical_type == jelly.PHYSICAL_STREAM_TYPE_TRIPLES:
-        adapter = RDFLibTriplesAdapter(graph=sink, options=options)
-    else:
-        ds = Dataset(store=sink.store, default_union=True)
-        ds.default_context = sink
-
-        if options.stream_types.physical_type == jelly.PHYSICAL_STREAM_TYPE_QUADS:
-            adapter = RDFLibQuadsAdapter(dataset=ds, options=options)
-
-        else:  # jelly.PHYSICAL_STREAM_TYPE_GRAPHS
-            adapter = RDFLibGraphsAdapter(dataset=ds, options=options)
+    assert options.stream_types.logical_type == jelly.LOGICAL_STREAM_TYPE_FLAT_TRIPLES
+    adapter = RDFLibTriplesAdapter(options, store=store)
+    if identifier is not None:
+        adapter.graph = Graph(identifier=identifier, store=store)
     decoder = Decoder(adapter=adapter)
     for frame in frames:
         decoder.decode_frame(frame=frame)
-    return ds or sink
+    return adapter.graph
 
 
-def parse_grouped_graph_stream(
+def parse_flat_quads_stream(
     frames: Iterable[jelly.RdfStreamFrame],
-    sink: Graph,
-    options: StreamOptions,
+    options: ParserOptions,
+    store: Store | str = "default",
+    identifier: str | None = None,
 ) -> Dataset:
-    adapter = RDFLibTriplesAdapter(graph=sink, options=options)
-    ds = Dataset(store=sink.store, default_union=True)
-    ds.default_context = sink
+    assert options.stream_types.logical_type == jelly.LOGICAL_STREAM_TYPE_FLAT_QUADS
+    adapter_class: type[RDFLibQuadsBaseAdapter]
+    if options.stream_types.physical_type == jelly.PHYSICAL_STREAM_TYPE_QUADS:
+        adapter_class = RDFLibQuadsAdapter
+    else:  # jelly.PHYSICAL_STREAM_TYPE_GRAPHS
+        adapter_class = RDFLibGraphsAdapter
+    adapter = adapter_class(options=options, store=store)
+    adapter.dataset.default_context = Graph(identifier=identifier, store=store)
     decoder = Decoder(adapter=adapter)
     for frame in frames:
-        graph = decoder.decode_frame(frame=frame)
-        ds.add_graph(graph)
-    return ds
+        decoder.decode_frame(frame=frame)
+    return adapter.dataset
 
 
-def parse_grouped_dataset_stream(
+def parse_graph_stream(
     frames: Iterable[jelly.RdfStreamFrame],
-    options: StreamOptions,
+    options: ParserOptions,
     store: Store | str = "default",
-) -> Generator[Dataset]:
-    adapter = RDFLibGraphsAdapter(dataset=Dataset(store=store), options=options)
+) -> Generator[Graph]:
+    assert options.stream_types.logical_type == jelly.LOGICAL_STREAM_TYPE_GRAPHS
+    adapter = RDFLibTriplesAdapter(options, store=store)
     decoder = Decoder(adapter=adapter)
     for frame in frames:
         yield decoder.decode_frame(frame=frame)
 
 
-def graph_or_dataset_from_jelly(
+def graphs_from_jelly(
     inp: IO[bytes],
-    sink: Graph,
-) -> Dataset | Graph:
+    store: Store | str = "default",
+) -> Generator[Any] | Generator[Dataset] | Generator[Graph]:
     options, frames = get_options_and_frames(inp)
 
-    if options.stream_types.flat:
-        return parse_flat_stream(frames=frames, sink=sink, options=options)
+    if options.stream_types.logical_type == jelly.LOGICAL_STREAM_TYPE_FLAT_TRIPLES:
+        yield parse_flat_triples_stream(frames=frames, options=options, store=store)
+        return
 
-    if options.stream_types.physical_type == jelly.PHYSICAL_STREAM_TYPE_TRIPLES:
-        return parse_grouped_graph_stream(frames=frames, sink=sink, options=options)
+    if options.stream_types.logical_type == jelly.LOGICAL_STREAM_TYPE_FLAT_QUADS:
+        yield parse_flat_quads_stream(frames=frames, options=options, store=store)
+        return
 
-    msg = (
-        "the stream contains multiple datasets and cannot be parsed into "
-        "a single dataset"
-    )
+    if options.stream_types.logical_type == jelly.LOGICAL_STREAM_TYPE_GRAPHS:
+        yield from parse_graph_stream(frames=frames, options=options, store=store)
+        return
+
+    logical_type_name = jelly.LogicalStreamType.Name(options.stream_types.logical_type)
+    msg = f"the stream type {logical_type_name} is not supported "
+    raise NotImplementedError(msg)
+
+
+def graph_from_jelly(
+    inp: IO[bytes],
+    store: Store | str = "default",
+    identifier: str | None = None,
+) -> Any | Dataset | Graph:
+    options, frames = get_options_and_frames(inp)
+
+    if options.stream_types.logical_type == jelly.LOGICAL_STREAM_TYPE_DATASETS:
+        msg = (
+            "the stream contains multiple datasets and cannot be parsed into "
+            "a single dataset"
+        )
+        raise NotImplementedError(msg)
+
+    if options.stream_types.logical_type == jelly.LOGICAL_STREAM_TYPE_FLAT_TRIPLES:
+        return parse_flat_triples_stream(
+            frames=frames,
+            options=options,
+            store=store,
+            identifier=identifier,
+        )
+
+    if options.stream_types.logical_type == jelly.LOGICAL_STREAM_TYPE_FLAT_QUADS:
+        return parse_flat_quads_stream(
+            frames=frames,
+            options=options,
+            store=store,
+            identifier=identifier,
+        )
+
+    if options.stream_types.logical_type == jelly.LOGICAL_STREAM_TYPE_GRAPHS:
+        ds = Dataset(store=store, default_union=True)
+        ds.default_context = Graph(identifier=identifier, store=store)
+
+        for graph in parse_graph_stream(frames=frames, options=options, store=store):
+            ds.add_graph(graph)
+
+        return ds
+
+    logical_type_name = jelly.LogicalStreamType.Name(options.stream_types.logical_type)
+    msg = f"the stream type {logical_type_name} is not supported "
     raise NotImplementedError(msg)
 
 
 class RDFLibJellyParser(RDFLibParser):
-    def parse(
-        self,
-        source: InputSource,
-        sink: Graph,
-    ) -> None:
+    def parse(self, source: InputSource, sink: Graph) -> None:
         inp = source.getByteStream()  # type: ignore[no-untyped-call]
         if inp is None:
             msg = "expected source to be a stream of bytes"
             raise TypeError(msg)
-        graph_or_dataset_from_jelly(inp, sink=sink)
+        graph_from_jelly(
+            inp,
+            identifier=sink.identifier,
+            store=sink.store,
+        )