rdf-construct 0.2.0__py3-none-any.whl

rdf_construct/diff/formatters/json.py

@@ -0,0 +1,192 @@
+"""JSON formatter for diff output - designed for programmatic use and scripting."""
+
+import json
+from typing import Any
+
+from rdflib import Graph, URIRef, Literal, BNode
+from rdflib.term import Node
+
+from rdf_construct.diff.change_types import (
+    EntityChange,
+    EntityType,
+    GraphDiff,
+    TripleChange,
+)
+
+
+def format_json(diff: GraphDiff, graph: Graph | None = None, indent: int = 2) -> str:
+    """Format diff as JSON for programmatic use.
+
+    Args:
+        diff: The diff result to format.
+        graph: Optional graph for CURIE formatting.
+        indent: JSON indentation (default 2).
+
+    Returns:
+        JSON formatted diff.
+    """
+    result = _build_json_structure(diff, graph)
+    return json.dumps(result, indent=indent, ensure_ascii=False)
+
+
+def _build_json_structure(diff: GraphDiff, graph: Graph | None = None) -> dict[str, Any]:
+    """Build the JSON structure for a diff."""
+    return {
+        "comparison": {
+            "old": diff.old_path,
+            "new": diff.new_path,
+        },
+        "identical": diff.is_identical,
+        "added": _format_entity_group_json(diff.added, graph),
+        "removed": _format_entity_group_json(diff.removed, graph),
+        "modified": _format_modified_entities_json(diff.modified, graph),
+        "summary": diff.summary,
+        "warnings": _build_warnings(diff),
+    }
+
+
+def _format_entity_group_json(
+    entities: list[EntityChange], graph: Graph | None = None
+) -> dict[str, list[dict]]:
+    """Format a group of entities by type for JSON output."""
+    result: dict[str, list[dict]] = {
+        "classes": [],
+        "object_properties": [],
+        "datatype_properties": [],
+        "annotation_properties": [],
+        "individuals": [],
+        "other": [],
+    }
+
+    type_mapping = {
+        EntityType.CLASS: "classes",
+        EntityType.OBJECT_PROPERTY: "object_properties",
+        EntityType.DATATYPE_PROPERTY: "datatype_properties",
+        EntityType.ANNOTATION_PROPERTY: "annotation_properties",
+        EntityType.INDIVIDUAL: "individuals",
+        EntityType.ONTOLOGY: "other",
+        EntityType.OTHER: "other",
+    }
+
+    for entity in entities:
+        key = type_mapping.get(entity.entity_type, "other")
+        result[key].append(_format_entity_json(entity, graph))
+
+    # Remove empty categories
+    return {k: v for k, v in result.items() if v}
+
+
+def _format_entity_json(entity: EntityChange, graph: Graph | None = None) -> dict:
+    """Format a single entity for JSON output."""
+    result = {
+        "uri": str(entity.uri),
+        "label": entity.label,
+        "type": entity.entity_type.value,
+    }
+
+    if entity.superclasses:
+        result["superclasses"] = [str(sc) for sc in entity.superclasses]
+
+    return result
+
+
+def _format_modified_entities_json(
+    entities: list[EntityChange], graph: Graph | None = None
+) -> list[dict]:
+    """Format modified entities with detailed changes."""
+    result = []
+
+    for entity in entities:
+        entity_dict = {
+            "uri": str(entity.uri),
+            "label": entity.label,
+            "type": entity.entity_type.value,
+            "changes": [],
+        }
+
+        # Format added triples
+        for change in entity.added_triples:
+            entity_dict["changes"].append({
+                "action": "added",
+                "predicate": str(change.predicate),
+                "predicate_curie": _format_uri(change.predicate, graph),
+                "object": _format_object_json(change.object, graph),
+                "category": change.category.value,
+            })
+
+        # Format removed triples
+        for change in entity.removed_triples:
+            entity_dict["changes"].append({
+                "action": "removed",
+                "predicate": str(change.predicate),
+                "predicate_curie": _format_uri(change.predicate, graph),
+                "object": _format_object_json(change.object, graph),
+                "category": change.category.value,
+            })
+
+        result.append(entity_dict)
+
+    return result
+
+
+def _format_object_json(obj: Node, graph: Graph | None = None) -> dict:
+    """Format an RDF object for JSON output."""
+    if isinstance(obj, URIRef):
+        return {
+            "type": "uri",
+            "value": str(obj),
+            "curie": _format_uri(obj, graph),
+        }
+    elif isinstance(obj, BNode):
+        return {
+            "type": "bnode",
+            "value": str(obj),
+        }
+    elif isinstance(obj, Literal):
+        result = {
+            "type": "literal",
+            "value": str(obj),
+        }
+        if obj.language:
+            result["language"] = obj.language
+        if obj.datatype:
+            result["datatype"] = str(obj.datatype)
+        return result
+
+    return {"type": "unknown", "value": str(obj)}
+
+
+def _format_uri(uri: URIRef | BNode, graph: Graph | None = None) -> str:
+    """Format a URI as a CURIE if possible."""
+    if isinstance(uri, BNode):
+        return f"_:{uri}"
+
+    if graph is not None:
+        try:
+            curie = graph.namespace_manager.normalizeUri(uri)
+            if curie and not curie.startswith("<"):
+                return curie
+        except Exception:
+            pass
+
+    uri_str = str(uri)
+    if "#" in uri_str:
+        return uri_str.split("#")[-1]
+    elif "/" in uri_str:
+        parts = uri_str.split("/")
+        return parts[-1] if parts[-1] else parts[-2]
+
+    return uri_str
+
+
+def _build_warnings(diff: GraphDiff) -> list[str]:
+    """Build list of warning messages."""
+    warnings = []
+
+    if diff.blank_node_warning:
+        warnings.append(
+            "Blank node changes were detected but not fully analysed. "
+            "Consider skolemising blank nodes for detailed comparison."
+        )
+
+    return warnings

rdf_construct/diff/formatters/markdown.py

@@ -0,0 +1,210 @@
+"""Markdown formatter for diff output - designed for release notes and changelogs."""
+
+from rdflib import Graph, URIRef, Literal, BNode
+from rdflib.term import Node
+
+from rdf_construct.diff.change_types import (
+    EntityChange,
+    EntityType,
+    GraphDiff,
+    TripleChange,
+)
+
+
+# Section headings for entity types
+ENTITY_TYPE_HEADINGS = {
+    EntityType.CLASS: "Classes",
+    EntityType.OBJECT_PROPERTY: "Object Properties",
+    EntityType.DATATYPE_PROPERTY: "Datatype Properties",
+    EntityType.ANNOTATION_PROPERTY: "Annotation Properties",
+    EntityType.INDIVIDUAL: "Instances",
+    EntityType.ONTOLOGY: "Ontology Metadata",
+    EntityType.OTHER: "Other",
+}
+
+
+def format_markdown(diff: GraphDiff, graph: Graph | None = None) -> str:
+    """Format diff as Markdown for release notes.
+
+    Args:
+        diff: The diff result to format.
+        graph: Optional graph for CURIE formatting.
+
+    Returns:
+        Markdown formatted diff.
+    """
+    lines: list[str] = []
+
+    # Title
+    lines.append(f"# Ontology Changes: {diff.old_path} → {diff.new_path}")
+    lines.append("")
+
+    if diff.is_identical:
+        lines.append("No semantic differences found.")
+        return "\n".join(lines)
+
+    # Summary at top
+    summary = diff.summary
+    lines.append("## Summary")
+    lines.append("")
+    lines.append(
+        f"- **{summary['added']}** entities added"
+    )
+    lines.append(
+        f"- **{summary['removed']}** entities removed"
+    )
+    lines.append(
+        f"- **{summary['modified']}** entities modified"
+    )
+    lines.append("")
+
+    # Added entities
+    if diff.added:
+        lines.append("## Added")
+        lines.append("")
+        lines.extend(_format_entity_group(diff.added, graph))
+        lines.append("")
+
+    # Removed entities
+    if diff.removed:
+        lines.append("## Removed")
+        lines.append("")
+        lines.extend(_format_entity_group(diff.removed, graph))
+        lines.append("")
+
+    # Modified entities
+    if diff.modified:
+        lines.append("## Modified")
+        lines.append("")
+        for entity in diff.modified:
+            lines.extend(_format_modified_entity_md(entity, graph))
+        lines.append("")
+
+    # Blank node warning
+    if diff.blank_node_warning:
+        lines.append("---")
+        lines.append("")
+        lines.append(
+            "*Note: Blank node changes were detected but not fully analysed. "
+            "Consider skolemising blank nodes for detailed comparison.*"
+        )
+
+    return "\n".join(lines)
+
+
+def _format_entity_group(
+    entities: list[EntityChange], graph: Graph | None = None
+) -> list[str]:
+    """Format a group of entities by type."""
+    lines: list[str] = []
+
+    # Group by entity type
+    by_type: dict[EntityType, list[EntityChange]] = {}
+    for entity in entities:
+        if entity.entity_type not in by_type:
+            by_type[entity.entity_type] = []
+        by_type[entity.entity_type].append(entity)
+
+    # Output each type group
+    for entity_type in EntityType:
+        if entity_type not in by_type:
+            continue
+
+        heading = ENTITY_TYPE_HEADINGS.get(entity_type, "Other")
+        lines.append(f"### {heading}")
+        lines.append("")
+
+        for entity in by_type[entity_type]:
+            lines.append(_format_entity_bullet(entity, graph))
+
+        lines.append("")
+
+    return lines
+
+
+def _format_entity_bullet(entity: EntityChange, graph: Graph | None = None) -> str:
+    """Format a single entity as a markdown bullet."""
+    uri_str = _format_uri(entity.uri, graph)
+    label = entity.label or uri_str
+
+    # Build the bullet
+    bullet = f"- **{label}**"
+
+    # Add superclass info for classes
+    if entity.superclasses:
+        superclass_strs = [_format_uri(sc, graph) for sc in entity.superclasses]
+        bullet += f" — subclass of {', '.join(superclass_strs)}"
+
+    return bullet
+
+
+def _format_modified_entity_md(
+    entity: EntityChange, graph: Graph | None = None
+) -> list[str]:
+    """Format a modified entity with detailed changes."""
+    lines: list[str] = []
+
+    uri_str = _format_uri(entity.uri, graph)
+    label = entity.label or uri_str
+
+    lines.append(f"### {label}")
+    lines.append("")
+
+    # Additions
+    if entity.added_triples:
+        lines.append("**Added:**")
+        lines.append("")
+        for change in entity.added_triples:
+            pred_str = _format_uri(change.predicate, graph)
+            obj_str = _format_object(change.object, graph)
+            lines.append(f"- `{pred_str}` → {obj_str}")
+        lines.append("")
+
+    # Removals
+    if entity.removed_triples:
+        lines.append("**Removed:**")
+        lines.append("")
+        for change in entity.removed_triples:
+            pred_str = _format_uri(change.predicate, graph)
+            obj_str = _format_object(change.object, graph)
+            lines.append(f"- ~~`{pred_str}` → {obj_str}~~")
+        lines.append("")
+
+    return lines
+
+
+def _format_uri(uri: URIRef | BNode, graph: Graph | None = None) -> str:
+    """Format a URI as a CURIE if possible."""
+    if isinstance(uri, BNode):
+        return f"_:{uri}"
+
+    if graph is not None:
+        try:
+            curie = graph.namespace_manager.normalizeUri(uri)
+            if curie and not curie.startswith("<"):
+                return curie
+        except Exception:
+            pass
+
+    uri_str = str(uri)
+    if "#" in uri_str:
+        return uri_str.split("#")[-1]
+    elif "/" in uri_str:
+        parts = uri_str.split("/")
+        return parts[-1] if parts[-1] else parts[-2]
+
+    return uri_str
+
+
+def _format_object(obj: Node, graph: Graph | None = None) -> str:
+    """Format an RDF object (URI, BNode, or Literal)."""
+    if isinstance(obj, URIRef):
+        return f"`{_format_uri(obj, graph)}`"
+    elif isinstance(obj, BNode):
+        return f"`_:{obj}`"
+    elif isinstance(obj, Literal):
+        value = str(obj)
+        if obj.language:
+            return f'"{value}"@{obj.language}'
+        return f'"{value}"'
+    return str(obj)

rdf_construct/diff/formatters/text.py

@@ -0,0 +1,195 @@
+"""Text formatter for diff output - designed for terminal display."""
+
+from typing import Protocol
+
+from rdflib import Graph, URIRef, Literal, BNode
+from rdflib.term import Node
+
+from rdf_construct.diff.change_types import (
+    EntityChange,
+    EntityType,
+    GraphDiff,
+    PredicateCategory,
+    TripleChange,
+)
+
+
+class DiffFormatter(Protocol):
+    """Protocol for diff formatters."""
+
+    def format(self, diff: GraphDiff, graph: Graph | None = None) -> str:
+        """Format a diff result as a string.
+
+        Args:
+            diff: The diff result to format.
+            graph: Optional graph for CURIE formatting.
+
+        Returns:
+            Formatted string representation.
+        """
+        ...
+
+
+# Human-readable names for entity types
+ENTITY_TYPE_NAMES = {
+    EntityType.CLASS: "Class",
+    EntityType.OBJECT_PROPERTY: "ObjectProperty",
+    EntityType.DATATYPE_PROPERTY: "DataProperty",
+    EntityType.ANNOTATION_PROPERTY: "AnnotationProperty",
+    EntityType.INDIVIDUAL: "Instance",
+    EntityType.ONTOLOGY: "Ontology",
+    EntityType.OTHER: "Entity",
+}
+
+
+def format_text(diff: GraphDiff, graph: Graph | None = None) -> str:
+    """Format diff as plain text for terminal output.
+
+    Args:
+        diff: The diff result to format.
+        graph: Optional graph for CURIE formatting.
+
+    Returns:
+        Plain text diff representation.
+    """
+    lines: list[str] = []
+
+    # Header
+    lines.append(f"Comparing {diff.old_path} → {diff.new_path}")
+    lines.append("")
+
+    if diff.is_identical:
+        lines.append("No semantic differences found.")
+        return "\n".join(lines)
+
+    # Added entities
+    if diff.added:
+        lines.append(f"ADDED ({len(diff.added)} entities):")
+        for entity in diff.added:
+            lines.append(_format_added_entity(entity, graph))
+        lines.append("")
+
+    # Removed entities
+    if diff.removed:
+        lines.append(f"REMOVED ({len(diff.removed)} entities):")
+        for entity in diff.removed:
+            lines.append(_format_removed_entity(entity, graph))
+        lines.append("")
+
+    # Modified entities
+    if diff.modified:
+        lines.append(f"MODIFIED ({len(diff.modified)} entities):")
+        for entity in diff.modified:
+            lines.extend(_format_modified_entity(entity, graph))
+        lines.append("")
+
+    # Summary
+    summary = diff.summary
+    lines.append(
+        f"Summary: {summary['added']} added, "
+        f"{summary['removed']} removed, "
+        f"{summary['modified']} modified"
+    )
+
+    # Blank node warning
+    if diff.blank_node_warning:
+        lines.append("")
+        lines.append(
+            "Note: Blank node changes detected but not fully analysed. "
+            "Consider skolemising blank nodes for detailed comparison."
+        )
+
+    return "\n".join(lines)
+
+
+def _format_uri(uri: URIRef | BNode, graph: Graph | None = None) -> str:
+    """Format a URI as a CURIE if possible, or full URI otherwise."""
+    if isinstance(uri, BNode):
+        return f"_:{uri}"
+
+    if graph is not None:
+        try:
+            curie = graph.namespace_manager.normalizeUri(uri)
+            if curie and not curie.startswith("<"):
+                return curie
+        except Exception:
+            pass
+
+    # Fallback: extract local name
+    uri_str = str(uri)
+    if "#" in uri_str:
+        return uri_str.split("#")[-1]
+    elif "/" in uri_str:
+        parts = uri_str.split("/")
+        return parts[-1] if parts[-1] else parts[-2]
+
+    return uri_str
+
+
+def _format_object(obj: Node, graph: Graph | None = None) -> str:
+    """Format an RDF object (URI, BNode, or Literal)."""
+    if isinstance(obj, URIRef):
+        return _format_uri(obj, graph)
+    elif isinstance(obj, BNode):
+        return f"_:{obj}"
+    elif isinstance(obj, Literal):
+        value = str(obj)
+        if obj.language:
+            return f'"{value}"@{obj.language}'
+        elif obj.datatype:
+            dtype = _format_uri(obj.datatype, graph)
+            # Skip xsd:string as it's the default
+            if "string" in dtype.lower():
+                return f'"{value}"'
+            return f'"{value}"^^{dtype}'
+        return f'"{value}"'
+    return str(obj)
+
+
+def _format_added_entity(entity: EntityChange, graph: Graph | None = None) -> str:
+    """Format a single added entity."""
+    type_name = ENTITY_TYPE_NAMES.get(entity.entity_type, "Entity")
+    uri_str = _format_uri(entity.uri, graph)
+
+    # Build description
+    desc = f"  + {type_name} {uri_str}"
+
+    # Add superclass info for classes
+    if entity.superclasses:
+        superclass_strs = [_format_uri(sc, graph) for sc in entity.superclasses]
+        desc += f" (subclass of {', '.join(superclass_strs)})"
+
+    return desc
+
+
+def _format_removed_entity(entity: EntityChange, graph: Graph | None = None) -> str:
+    """Format a single removed entity."""
+    type_name = ENTITY_TYPE_NAMES.get(entity.entity_type, "Entity")
+    uri_str = _format_uri(entity.uri, graph)
+
+    return f"  - {type_name} {uri_str}"
+
+
+def _format_modified_entity(
+    entity: EntityChange, graph: Graph | None = None
+) -> list[str]:
+    """Format a modified entity with its changes."""
+    lines: list[str] = []
+
+    type_name = ENTITY_TYPE_NAMES.get(entity.entity_type, "Entity")
+    uri_str = _format_uri(entity.uri, graph)
+
+    lines.append(f"  ~ {type_name} {uri_str}")
+
+    # Group and format changes
+    for change in entity.added_triples:
+        pred_str = _format_uri(change.predicate, graph)
+        obj_str = _format_object(change.object, graph)
+        lines.append(f"    + {pred_str} {obj_str}")
+
+    for change in entity.removed_triples:
+        pred_str = _format_uri(change.predicate, graph)
+        obj_str = _format_object(change.object, graph)
+        lines.append(f"    - {pred_str} {obj_str}")
+
+    return lines

rdf_construct/docs/__init__.py

@@ -0,0 +1,60 @@
+"""Documentation generation module for rdf-construct.
+
+This module provides functionality for generating comprehensive, navigable
+documentation from RDF ontologies in HTML, Markdown, or JSON formats.
+
+Example usage:
+    from rdf_construct.docs import generate_docs
+
+    result = generate_docs(
+        source=Path("ontology.ttl"),
+        output_dir=Path("docs/"),
+        output_format="html",
+    )
+    print(f"Generated {result.total_pages} pages")
+
+For more control, use the DocsGenerator class directly:
+    from rdf_construct.docs import DocsGenerator, DocsConfig
+
+    config = DocsConfig(
+        output_dir=Path("docs/"),
+        format="html",
+        include_instances=True,
+        include_search=True,
+    )
+    generator = DocsGenerator(config)
+    result = generator.generate_from_file(Path("ontology.ttl"))
+"""
+
+from rdf_construct.docs.config import DocsConfig, load_docs_config
+from rdf_construct.docs.extractors import (
+    ClassInfo,
+    ExtractedEntities,
+    InstanceInfo,
+    OntologyInfo,
+    PropertyInfo,
+    extract_all,
+)
+from rdf_construct.docs.generator import DocsGenerator, GenerationResult, generate_docs
+from rdf_construct.docs.search import SearchEntry, generate_search_index
+
+__all__ = [
+    # Main interface
+    "generate_docs",
+    "DocsGenerator",
+    "GenerationResult",
+    # Configuration
+    "DocsConfig",
+    "load_docs_config",
+    # Data classes
+    "ClassInfo",
+    "PropertyInfo",
+    "InstanceInfo",
+    "OntologyInfo",
+    "ExtractedEntities",
+    # Extraction
+    "extract_all",
+    # Search
+    "SearchEntry",
+    "generate_search_index",
+]