rdfdiff 0.1.0__tar.gz

rdfdiff-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: checks
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy semanticdiff
+      - run: uv run pytest -q

rdfdiff-0.1.0/.github/workflows/pypi-publish.yml

@@ -0,0 +1,36 @@
+name: publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/rdfdiff
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

rdfdiff-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/

rdfdiff-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 gbelbe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rdfdiff-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: rdfdiff
+Version: 0.1.0
+Summary: Read an RDF file's Git history as semantic change rather than text
+Project-URL: Homepage, https://github.com/gbelbe/semanticdiff
+Project-URL: Repository, https://github.com/gbelbe/semanticdiff
+Project-URL: Issues, https://github.com/gbelbe/semanticdiff/issues
+License: MIT License
+        
+        Copyright (c) 2024 gbelbe
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: diff,git,ontology,owl,rdf,semantic-web,skos
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control
+Requires-Python: >=3.12
+Requires-Dist: rdflib>=7.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=9.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# rdfdiff
+
+`rdfdiff` reads an RDF file's Git history as changes to its vocabulary,
+rather than as changed characters. It reports classes, properties, individuals,
+
+Equivalent RDF serializations produce no semantic change, so reformatting,
+prefix changes, reordered triples, and blank-node relabeling do not hide actual
+ontology evolution.
+
+## Install
+
+```sh
+uv tool install rdfdiff
+```
+
+Or run the current checkout:
+
+```sh
+uv run semanticdiff log --repo /path/to/ontology-repository
+```
+
+## Use
+
+Summarize every commit that changed an RDF file:
+
+```sh
+semanticdiff log v0.1..v0.2 --repo /path/to/ontology-repository --file ontology.ttl
+```
+
+Trace one entity through a revision range:
+
+```sh
+semanticdiff show ex:Product v0.1..HEAD --repo /path/to/ontology-repository --file ontology.ttl
+```
+
+When a repository has exactly one tracked RDF file, `--file` is optional. Use
+`--text` with `log` to append Git's raw hunks after the semantic report.
+
+## Library API
+
+```python
+from rdflib import Graph
+from semanticdiff import compare
+
+changes = compare(before_graph, after_graph)
+```
+
+`read_history(repo, revision_range, path)` pairs each commit touching `path`
+with its semantic change set. The public vocabulary is exported from the package
+root: `Change`, `ChangeKind`, `ChangeSet`, `CommitChanges`, and `EntityKind`.
+
+## Development
+
+```sh
+uv sync --extra dev
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy semanticdiff
+uv run pytest -q
+```
+
+The distribution is named `rdfdiff`; its Python import and command-line command
+remain `semanticdiff`. The project deliberately has no dependency on Ster. Ster
+can consume it as an optional integration, but the diff engine and command-line
+tool remain usable with any RDF repository.
+
+## Releases
+
+Releases are published to PyPI by the `pypi-publish.yml` GitHub Actions workflow
+when a `v*` tag is pushed. PyPI trusted publishing must be configured for the
+`gbelbe/semanticdiff` repository, the `pypi-publish.yml` workflow, and the
+  `pypi` environment before the first release tag is created. The pending PyPI
+  publisher must use the `rdfdiff` project name.

rdfdiff-0.1.0/README.md

@@ -0,0 +1,73 @@
+# rdfdiff
+
+`rdfdiff` reads an RDF file's Git history as changes to its vocabulary,
+rather than as changed characters. It reports classes, properties, individuals,
+
+Equivalent RDF serializations produce no semantic change, so reformatting,
+prefix changes, reordered triples, and blank-node relabeling do not hide actual
+ontology evolution.
+
+## Install
+
+```sh
+uv tool install rdfdiff
+```
+
+Or run the current checkout:
+
+```sh
+uv run semanticdiff log --repo /path/to/ontology-repository
+```
+
+## Use
+
+Summarize every commit that changed an RDF file:
+
+```sh
+semanticdiff log v0.1..v0.2 --repo /path/to/ontology-repository --file ontology.ttl
+```
+
+Trace one entity through a revision range:
+
+```sh
+semanticdiff show ex:Product v0.1..HEAD --repo /path/to/ontology-repository --file ontology.ttl
+```
+
+When a repository has exactly one tracked RDF file, `--file` is optional. Use
+`--text` with `log` to append Git's raw hunks after the semantic report.
+
+## Library API
+
+```python
+from rdflib import Graph
+from semanticdiff import compare
+
+changes = compare(before_graph, after_graph)
+```
+
+`read_history(repo, revision_range, path)` pairs each commit touching `path`
+with its semantic change set. The public vocabulary is exported from the package
+root: `Change`, `ChangeKind`, `ChangeSet`, `CommitChanges`, and `EntityKind`.
+
+## Development
+
+```sh
+uv sync --extra dev
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy semanticdiff
+uv run pytest -q
+```
+
+The distribution is named `rdfdiff`; its Python import and command-line command
+remain `semanticdiff`. The project deliberately has no dependency on Ster. Ster
+can consume it as an optional integration, but the diff engine and command-line
+tool remain usable with any RDF repository.
+
+## Releases
+
+Releases are published to PyPI by the `pypi-publish.yml` GitHub Actions workflow
+when a `v*` tag is pushed. PyPI trusted publishing must be configured for the
+`gbelbe/semanticdiff` repository, the `pypi-publish.yml` workflow, and the
+  `pypi` environment before the first release tag is created. The pending PyPI
+  publisher must use the `rdfdiff` project name.

rdfdiff-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rdfdiff"
+version = "0.1.0"
+description = "Read an RDF file's Git history as semantic change rather than text"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { file = "LICENSE" }
+keywords = ["rdf", "ontology", "semantic-web", "git", "diff", "skos", "owl"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Version Control",
+]
+dependencies = [
+    "rdflib>=7.0",
+    "typer>=0.12",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[project.scripts]
+semanticdiff = "semanticdiff.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/gbelbe/semanticdiff"
+Repository = "https://github.com/gbelbe/semanticdiff"
+Issues = "https://github.com/gbelbe/semanticdiff/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["semanticdiff"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--tb=short --strict-markers --strict-config"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "UP", "B", "C4", "SIM"]
+ignore = [
+    # Keep str + Enum for the established serialized public API.
+    "UP042",
+]
+
+[tool.mypy]
+python_version = "3.12"
+ignore_missing_imports = true
+pretty = true

rdfdiff-0.1.0/semanticdiff/__init__.py

@@ -0,0 +1,26 @@
+"""semanticdiff — read a git history of an RDF file as semantic change.
+
+A git diff reports characters. This package reports the vocabulary: which
+classes, properties and concepts were added, modified, renamed, deprecated or
+removed in each commit, so the raw text only has to be opened when the summary
+is not enough.
+
+It deliberately depends on nothing from `ster` — an import contract enforces
+that — so it can be extracted into its own distribution unchanged.
+"""
+
+from __future__ import annotations
+
+from semanticdiff.changeset import compare
+from semanticdiff.history import CommitChanges, read_history
+from semanticdiff.vocabulary import Change, ChangeKind, ChangeSet, EntityKind
+
+__all__ = [
+    "Change",
+    "ChangeKind",
+    "ChangeSet",
+    "CommitChanges",
+    "EntityKind",
+    "compare",
+    "read_history",
+]

rdfdiff-0.1.0/semanticdiff/changeset.py

@@ -0,0 +1,243 @@
+"""The semantic core: two graphs in, a set of change operations out.
+
+Pure — no git, no files, no I/O — so the whole vocabulary of change is testable
+from turtle strings. The engine is rdflib's `graph_diff` over the isomorphic
+(blank-node-canonical) form of each graph, which is what makes a re-serialised
+file report as unchanged.
+"""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from dataclasses import dataclass
+
+from rdflib import BNode, Graph, Literal, URIRef
+from rdflib.compare import graph_diff, to_isomorphic
+from rdflib.namespace import OWL, RDF, RDFS, SKOS
+from rdflib.term import Node
+
+from semanticdiff.rename import detect_renames
+from semanticdiff.vocabulary import Change, ChangeKind, ChangeSet, EntityKind
+
+# Predicates whose *object* is also touched by the triple. Adding
+# `ex:Vehicle rdfs:subClassOf ex:Product` changes ex:Product too, although
+# ex:Product is never a subject of the added triples; without this table the
+# sentence "class X gained 2 properties" cannot be produced at all. Kept to
+# four entries on purpose — every addition here is a new source of noise.
+_OBJECT_ATTRIBUTION: dict[URIRef, tuple[str, str]] = {
+    RDFS.subClassOf: ("subclass", "subclasses"),
+    SKOS.broader: ("narrower concept", "narrower concepts"),
+    RDFS.domain: ("property", "properties"),
+    RDFS.range: ("property range", "property ranges"),
+}
+
+# Predicates reported as a value transition on the subject: "domain A → B".
+_TRANSITIONS: dict[URIRef, str] = {RDFS.domain: "domain", RDFS.range: "range"}
+
+_TYPE_KINDS: dict[URIRef, EntityKind] = {
+    OWL.Class: EntityKind.CLASS,
+    RDFS.Class: EntityKind.CLASS,
+    OWL.ObjectProperty: EntityKind.PROPERTY,
+    OWL.DatatypeProperty: EntityKind.PROPERTY,
+    OWL.AnnotationProperty: EntityKind.PROPERTY,
+    RDF.Property: EntityKind.PROPERTY,
+    SKOS.Concept: EntityKind.CONCEPT,
+    OWL.Ontology: EntityKind.ONTOLOGY,
+    OWL.NamedIndividual: EntityKind.INDIVIDUAL,
+}
+
+_LABEL_PREDICATES = (SKOS.prefLabel, RDFS.label)
+
+_DEPRECATED = Literal(True)
+
+
+@dataclass(frozen=True)
+class _Delta:
+    """The two delta graphs, plus their incoming edges indexed by object.
+
+    The index exists because the alternative is quadratic. Attributing
+    "+2 properties" to a class means counting the triples pointing *at* it, and
+    scanning the delta once per entity costs entities x delta: on a commit
+    touching 1 827 entities that was 15s of a 16s diff. Indexed once, it is a
+    single pass and a dict lookup each.
+    """
+
+    only_base: Graph
+    only_later: Graph
+    lost: dict[Node, Counter[Node]]
+    gained: dict[Node, Counter[Node]]
+
+
+def compare(base: Graph, later: Graph) -> ChangeSet:
+    """The change operations taking `base` to `later`."""
+    _, only_base, only_later = graph_diff(to_isomorphic(base), to_isomorphic(later))
+    delta = _Delta(
+        only_base=only_base,
+        only_later=only_later,
+        lost=_incoming_index(only_base),
+        gained=_incoming_index(only_later),
+    )
+    touched = _touched(only_base) | _touched(only_later) | _changed_owners(base, later)
+    changes = (_describe(uri, base, later, delta) for uri in sorted(touched))
+    return detect_renames(ChangeSet(tuple(c for c in changes if c is not None)))
+
+
+def _incoming_index(delta: Graph) -> dict[Node, Counter[Node]]:
+    """`{object: {predicate: count}}` for the predicates that credit their object."""
+    index: dict[Node, Counter[Node]] = defaultdict(Counter)
+    for _, predicate, obj in delta:
+        if predicate in _OBJECT_ATTRIBUTION:
+            index[obj][predicate] += 1
+    return index
+
+
+def _touched(delta: Graph) -> set[URIRef]:
+    """Every named entity implicated by the triples in `delta`."""
+    touched: set[URIRef] = set()
+    for subject, predicate, obj in delta:
+        if isinstance(subject, URIRef):
+            touched.add(subject)
+        if predicate in _OBJECT_ATTRIBUTION and isinstance(obj, URIRef):
+            touched.add(obj)
+    return touched
+
+
+def _changed_owners(base: Graph, later: Graph) -> set[URIRef]:
+    """Named entities whose blank-node description changed.
+
+    A change inside a blank node — a restriction's cardinality, a member of an
+    anonymous union, an item in an RDF list — has a blank node as its subject, so
+    subject attribution alone discards it, and the triple joining the owner to the
+    blank node does not itself change. The edit would then be reported nowhere at
+    all, which a reader cannot tell apart from "nothing changed".
+
+    The blank nodes in the diff cannot be traced back: graph_diff canonicalises
+    them, so their identity no longer matches either source graph. Instead each
+    entity that owns a blank node has its description (itself plus everything
+    reachable through blank nodes) compared between the two revisions.
+
+    Only entities that actually own a blank node are examined, so an ontology
+    without any — the common case — pays nothing for this.
+    """
+    owners = {
+        subject
+        for graph in (base, later)
+        for subject, _, obj in graph
+        if isinstance(subject, URIRef) and isinstance(obj, BNode)
+    }
+    return {uri for uri in owners if not _same_description(base, later, uri)}
+
+
+def _same_description(base: Graph, later: Graph, uri: URIRef) -> bool:
+    """Whether the entity's blank-node closure is the same graph on both sides."""
+    return to_isomorphic(base.cbd(uri)) == to_isomorphic(later.cbd(uri))
+
+
+def _describe(uri: URIRef, base: Graph, later: Graph, delta: _Delta) -> Change | None:
+    """One change for `uri`, or None when it is only ever referenced, never defined."""
+    in_base = (uri, None, None) in base
+    in_later = (uri, None, None) in later
+    if not in_base and not in_later:
+        return None
+    source = later if in_later else base
+    label, lang = _label(source, uri)
+    return Change(
+        kind=_kind(uri, base, later, in_base=in_base, in_later=in_later),
+        entity=_entity_kind(source, uri),
+        uri=str(uri),
+        curie=_curie(source, uri),
+        label=label,
+        label_lang=lang,
+        detail=_detail(uri, base, later, delta),
+        of_class=_of_class(source, uri),
+    )
+
+
+def _kind(uri: URIRef, base: Graph, later: Graph, *, in_base: bool, in_later: bool) -> ChangeKind:
+    if not in_base:
+        return ChangeKind.ADDED
+    if not in_later:
+        return ChangeKind.REMOVED
+    if (uri, OWL.deprecated, _DEPRECATED) in later and (
+        uri,
+        OWL.deprecated,
+        _DEPRECATED,
+    ) not in base:
+        return ChangeKind.DEPRECATED
+    return ChangeKind.MODIFIED
+
+
+def _entity_kind(graph: Graph, uri: URIRef) -> EntityKind:
+    for type_uri in graph.objects(uri, RDF.type):
+        if isinstance(type_uri, URIRef) and (kind := _TYPE_KINDS.get(type_uri)) is not None:
+            return kind
+    if (uri, RDF.type, None) in graph:
+        return EntityKind.INDIVIDUAL
+    return EntityKind.OTHER
+
+
+def _of_class(graph: Graph, uri: URIRef) -> str | None:
+    """The class an individual instantiates, as the name a reader should see.
+
+    Sorted so a multi-typed individual always reports the same one, and skipping
+    owl:NamedIndividual, which says nothing about what the thing is.
+    """
+    types = sorted(
+        str(t)
+        for t in graph.objects(uri, RDF.type)
+        if isinstance(t, URIRef) and t != OWL.NamedIndividual and t not in _TYPE_KINDS
+    )
+    if not types:
+        return None
+    cls = URIRef(types[0])
+    label, _ = _label(graph, cls)
+    return label or _curie(graph, cls)
+
+
+def _label(graph: Graph, uri: URIRef) -> tuple[str | None, str | None]:
+    """The entity's preferred label, skos:prefLabel winning over rdfs:label."""
+    for predicate in _LABEL_PREDICATES:
+        literals = sorted(
+            (o for o in graph.objects(uri, predicate) if isinstance(o, Literal)),
+            key=lambda lit: (lit.language or "", str(lit)),
+        )
+        if literals:
+            return str(literals[0]), literals[0].language
+    return None, None
+
+
+def _curie(graph: Graph, uri: Node) -> str:
+    """The prefixed form, or the full URI when no prefix is bound."""
+    try:
+        prefix, _, name = graph.namespace_manager.compute_qname(str(uri), generate=False)
+    except (KeyError, ValueError):
+        return str(uri)
+    return f"{prefix}:{name}" if prefix else str(uri)
+
+
+def _detail(uri: URIRef, base: Graph, later: Graph, delta: _Delta) -> tuple[str, ...]:
+    return (*_transitions(uri, base, later, delta), *_attributions(uri, delta))
+
+
+def _transitions(uri: URIRef, base: Graph, later: Graph, delta: _Delta) -> tuple[str, ...]:
+    """Single-valued predicates that moved, read as 'domain ex:Place → ex:Site'."""
+    parts = []
+    for predicate, name in _TRANSITIONS.items():
+        before = list(delta.only_base.objects(uri, predicate))
+        after = list(delta.only_later.objects(uri, predicate))
+        if len(before) == 1 and len(after) == 1:
+            parts.append(f"{name} {_curie(base, before[0])} → {_curie(later, after[0])}")
+    return tuple(parts)
+
+
+def _attributions(uri: URIRef, delta: _Delta) -> tuple[str, ...]:
+    """What the entity gained or lost through triples pointing at it."""
+    gained = delta.gained.get(uri, Counter())
+    lost = delta.lost.get(uri, Counter())
+    parts = []
+    for predicate, (singular, plural) in _OBJECT_ATTRIBUTION.items():
+        for sign, counted in (("+", gained), ("-", lost)):
+            total = counted[predicate]
+            if total:
+                parts.append(f"{sign}{total} {singular if total == 1 else plural}")
+    return tuple(parts)