rdf-construct 0.3.0__py3-none-any.whl

rdf_construct/cq/runner.py

@@ -0,0 +1,321 @@
+"""Test execution engine for competency question tests.
+
+Runs SPARQL queries against RDF graphs and checks results against expectations.
+"""
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+from rdflib import Graph
+
+from rdf_construct.cq.loader import CQTest, CQTestSuite, build_query_with_prefixes
+from rdf_construct.cq.expectations import CheckResult
+
+
+class CQStatus(Enum):
+    """Status of a test execution."""
+    PASS = "pass"
+    FAIL = "fail"
+    ERROR = "error"
+    SKIP = "skip"
+
+
+@dataclass
+class CQTestResult:
+    """Result of running a single competency question test.
+
+    Attributes:
+        test: The test that was run
+        status: Pass/fail/error/skip status
+        duration_ms: Execution time in milliseconds
+        result_count: Number of results returned (if applicable)
+        check_result: Detailed check result from expectation
+        error: Error message if status is ERROR
+    """
+    test: CQTest
+    status: CQStatus
+    duration_ms: float = 0.0
+    result_count: int | None = None
+    check_result: CheckResult | None = None
+    error: str | None = None
+
+    @property
+    def passed(self) -> bool:
+        """Return True if test passed."""
+        return self.status == CQStatus.PASS
+
+    @property
+    def message(self) -> str:
+        """Return a human-readable result message."""
+        if self.error:
+            return self.error
+        if self.check_result:
+            return self.check_result.message
+        if self.status == CQStatus.SKIP:
+            return self.test.skip_reason or "Skipped"
+        return ""
+
+
+@dataclass
+class CQTestResults:
+    """Results of running a full test suite.
+
+    Attributes:
+        suite: The test suite that was run
+        results: Individual test results
+        total_duration_ms: Total execution time in milliseconds
+        ontology_file: Path to the ontology file tested
+    """
+    suite: CQTestSuite
+    results: list[CQTestResult] = field(default_factory=list)
+    total_duration_ms: float = 0.0
+    ontology_file: Path | None = None
+
+    @property
+    def total_count(self) -> int:
+        """Total number of tests."""
+        return len(self.results)
+
+    @property
+    def passed_count(self) -> int:
+        """Number of passed tests."""
+        return sum(1 for r in self.results if r.status == CQStatus.PASS)
+
+    @property
+    def failed_count(self) -> int:
+        """Number of failed tests."""
+        return sum(1 for r in self.results if r.status == CQStatus.FAIL)
+
+    @property
+    def error_count(self) -> int:
+        """Number of tests with errors."""
+        return sum(1 for r in self.results if r.status == CQStatus.ERROR)
+
+    @property
+    def skipped_count(self) -> int:
+        """Number of skipped tests."""
+        return sum(1 for r in self.results if r.status == CQStatus.SKIP)
+
+    @property
+    def all_passed(self) -> bool:
+        """Return True if all tests passed (excluding skips)."""
+        return self.failed_count == 0 and self.error_count == 0
+
+    @property
+    def has_failures(self) -> bool:
+        """Return True if any tests failed."""
+        return self.failed_count > 0
+
+    @property
+    def has_errors(self) -> bool:
+        """Return True if any tests had errors."""
+        return self.error_count > 0
+
+
+class CQTestRunner:
+    """Runner for executing competency question tests.
+
+    Handles:
+    - Loading and combining graphs (ontology + sample data)
+    - Injecting prefixes into queries
+    - Executing SPARQL queries
+    - Checking results against expectations
+    - Timing and error handling
+
+    Args:
+        fail_fast: Stop on first failure if True
+        verbose: Output verbose logging if True
+    """
+
+    def __init__(self, fail_fast: bool = False, verbose: bool = False):
+        self.fail_fast = fail_fast
+        self.verbose = verbose
+
+    def run(self, ontology: Graph, suite: CQTestSuite,
+            ontology_file: Path | None = None) -> CQTestResults:
+        """Run all tests in a suite against an ontology.
+
+        Args:
+            ontology: RDF graph containing the ontology
+            suite: Test suite to execute
+            ontology_file: Optional path for reporting
+
+        Returns:
+            CQTestResults with all test results
+        """
+        start_time = time.perf_counter()
+
+        # Combine ontology with test data if present
+        if suite.data_graph:
+            graph = ontology + suite.data_graph
+        else:
+            graph = ontology
+
+        # Bind prefixes for query execution
+        for prefix, uri in suite.prefixes.items():
+            graph.bind(prefix, uri)
+
+        results = []
+        for test in suite.questions:
+            result = self._run_test(graph, test, suite.prefixes)
+            results.append(result)
+
+            if self.fail_fast and result.status in (CQStatus.FAIL, CQStatus.ERROR):
+                break
+
+        total_duration = (time.perf_counter() - start_time) * 1000
+
+        return CQTestResults(
+            suite=suite,
+            results=results,
+            total_duration_ms=total_duration,
+            ontology_file=ontology_file,
+        )
+
+    def _run_test(self, graph: Graph, test: CQTest,
+                  prefixes: dict[str, str]) -> CQTestResult:
+        """Run a single test.
+
+        Args:
+            graph: Combined ontology + data graph
+            test: Test to run
+            prefixes: Prefix definitions for query injection
+
+        Returns:
+            CQTestResult with status and details
+        """
+        # Handle skipped tests
+        if test.skip:
+            return CQTestResult(
+                test=test,
+                status=CQStatus.SKIP,
+            )
+
+        start_time = time.perf_counter()
+
+        try:
+            # Inject prefixes into query
+            full_query = build_query_with_prefixes(test.query, prefixes)
+
+            # Execute query
+            result = graph.query(full_query)
+
+            # Check if this is an ASK query (returns boolean) or SELECT (returns rows)
+            # rdflib Result objects have a 'type' attribute
+            is_ask_query = getattr(result, 'type', None) == 'ASK'
+
+            if is_ask_query:
+                # ASK query - result is boolean
+                result_count = None
+                check_input = result
+            else:
+                # SELECT query - need to materialise results for counting
+                # But we also need them for expectation checking
+                # So we convert to list first
+                results_list = list(result)
+                result_count = len(results_list)
+
+                # Create a fake result object that can be iterated
+                # This is a bit hacky but necessary since rdflib results
+                # are single-use iterators
+                class ResultWrapper:
+                    def __init__(self, rows):
+                        self.rows = rows
+                    def __iter__(self):
+                        return iter(self.rows)
+                    def __bool__(self):
+                        return len(self.rows) > 0
+                    def __len__(self):
+                        return len(self.rows)
+
+                check_input = ResultWrapper(results_list)
+
+            # Check expectation
+            check_result = test.expectation.check(check_input)
+
+            duration = (time.perf_counter() - start_time) * 1000
+
+            return CQTestResult(
+                test=test,
+                status=CQStatus.PASS if check_result.passed else CQStatus.FAIL,
+                duration_ms=duration,
+                result_count=result_count,
+                check_result=check_result,
+            )
+
+        except Exception as e:
+            duration = (time.perf_counter() - start_time) * 1000
+
+            return CQTestResult(
+                test=test,
+                status=CQStatus.ERROR,
+                duration_ms=duration,
+                error=f"{type(e).__name__}: {e}",
+            )
+
+
+def run_tests(ontology_path: Path, test_suite_path: Path,
+              additional_data: list[Path] | None = None,
+              include_tags: set[str] | None = None,
+              exclude_tags: set[str] | None = None,
+              fail_fast: bool = False,
+              verbose: bool = False) -> CQTestResults:
+    """Convenience function to run tests from file paths.
+
+    Args:
+        ontology_path: Path to ontology file
+        test_suite_path: Path to test suite YAML
+        additional_data: Additional data files to load
+        include_tags: Only run tests with these tags
+        exclude_tags: Exclude tests with these tags
+        fail_fast: Stop on first failure
+        verbose: Verbose output
+
+    Returns:
+        CQTestResults
+
+    Raises:
+        FileNotFoundError: If files don't exist
+        ValueError: If parsing fails
+    """
+    from .loader import load_test_suite
+
+    # Load ontology
+    ontology = Graph()
+    ontology.parse(str(ontology_path), format=_format_from_path(ontology_path))
+
+    # Load additional data
+    if additional_data:
+        for data_path in additional_data:
+            ontology.parse(str(data_path), format=_format_from_path(data_path))
+
+    # Load test suite
+    suite = load_test_suite(test_suite_path)
+
+    # Filter by tags
+    if include_tags or exclude_tags:
+        suite = suite.filter_by_tags(include_tags, exclude_tags)
+
+    # Run tests
+    runner = CQTestRunner(fail_fast=fail_fast, verbose=verbose)
+    return runner.run(ontology, suite, ontology_file=ontology_path)
+
+
+def _format_from_path(path: Path) -> str:
+    """Infer RDF format from file extension."""
+    suffix = path.suffix.lower()
+    format_map = {
+        ".ttl": "turtle",
+        ".turtle": "turtle",
+        ".rdf": "xml",
+        ".xml": "xml",
+        ".owl": "xml",
+        ".nt": "nt",
+        ".ntriples": "nt",
+        ".n3": "n3",
+        ".jsonld": "json-ld",
+        ".json": "json-ld",
+    }
+    return format_map.get(suffix, "turtle")

rdf_construct/diff/__init__.py

@@ -0,0 +1,59 @@
+"""Semantic diff for RDF ontologies.
+
+This module provides tools for comparing RDF graphs and identifying
+semantic differences, filtering out cosmetic changes like statement
+order, prefix bindings, and whitespace.
+
+Usage:
+    from rdf_construct.diff import compare_files, format_diff
+
+    diff = compare_files(Path("old.ttl"), Path("new.ttl"))
+    print(format_diff(diff, format_name="text"))
+
+CLI:
+    rdf-construct diff old.ttl new.ttl
+    rdf-construct diff old.ttl new.ttl --format markdown -o changelog.md
+"""
+
+from rdf_construct.diff.change_types import (
+    ChangeType,
+    EntityChange,
+    EntityType,
+    GraphDiff,
+    PredicateCategory,
+    TripleChange,
+)
+from rdf_construct.diff.comparator import compare_graphs, compare_files
+from rdf_construct.diff.filters import filter_diff, parse_filter_string
+from rdf_construct.diff.formatters import (
+    format_diff,
+    format_text,
+    format_markdown,
+    format_json,
+    get_formatter,
+    FORMATTERS,
+)
+
+
+__all__ = [
+    # Change types
+    "ChangeType",
+    "EntityChange",
+    "EntityType",
+    "GraphDiff",
+    "PredicateCategory",
+    "TripleChange",
+    # Comparison
+    "compare_graphs",
+    "compare_files",
+    # Filtering
+    "filter_diff",
+    "parse_filter_string",
+    # Formatting
+    "format_diff",
+    "format_text",
+    "format_markdown",
+    "format_json",
+    "get_formatter",
+    "FORMATTERS",
+]

rdf_construct/diff/change_types.py

@@ -0,0 +1,214 @@
+"""Data classes for representing semantic changes between RDF graphs.
+
+This module defines the type hierarchy for diff results:
+- EntityChange: Changes to a single entity (added/removed/modified)
+- TripleChange: Individual triple-level changes
+- GraphDiff: Complete diff result containing all changes
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any
+
+from rdflib import URIRef, BNode, Literal
+from rdflib.term import Node
+
+
+class ChangeType(Enum):
+    """Classification of change types for filtering and display."""
+
+    ADDED = auto()
+    REMOVED = auto()
+    MODIFIED = auto()
+
+
+class EntityType(Enum):
+    """Classification of RDF entity types."""
+
+    CLASS = "class"
+    OBJECT_PROPERTY = "object_property"
+    DATATYPE_PROPERTY = "datatype_property"
+    ANNOTATION_PROPERTY = "annotation_property"
+    INDIVIDUAL = "individual"
+    ONTOLOGY = "ontology"
+    OTHER = "other"
+
+
+class PredicateCategory(Enum):
+    """Semantic categories for predicates (for human-readable output)."""
+
+    TYPE = "type"
+    HIERARCHY = "hierarchy"
+    DOMAIN_RANGE = "domain_range"
+    LABEL = "label"
+    DOCUMENTATION = "documentation"
+    OWL_AXIOM = "owl_axiom"
+    OTHER = "other"
+
+
+@dataclass
+class TripleChange:
+    """Represents a single triple that was added or removed.
+
+    Attributes:
+        predicate: The predicate of the changed triple.
+        object: The object of the changed triple.
+        is_addition: True if added, False if removed.
+        category: Semantic category of the predicate.
+    """
+
+    predicate: URIRef
+    object: Node
+    is_addition: bool
+    category: PredicateCategory = PredicateCategory.OTHER
+
+    def __post_init__(self):
+        """Categorise the predicate if not already done."""
+        if self.category == PredicateCategory.OTHER:
+            self.category = categorise_predicate(self.predicate)
+
+
+@dataclass
+class EntityChange:
+    """Represents all changes to a single entity.
+
+    Attributes:
+        uri: The URI of the changed entity.
+        entity_type: The type of entity (class, property, individual, etc.).
+        change_type: Whether entity was added, removed, or modified.
+        label: Human-readable label if available.
+        added_triples: List of triples added to this entity.
+        removed_triples: List of triples removed from this entity.
+        superclasses: Superclasses (for classes) or None.
+    """
+
+    uri: URIRef | BNode
+    entity_type: EntityType
+    change_type: ChangeType
+    label: str | None = None
+    added_triples: list[TripleChange] = field(default_factory=list)
+    removed_triples: list[TripleChange] = field(default_factory=list)
+    superclasses: list[URIRef] | None = None
+
+    @property
+    def is_blank_node(self) -> bool:
+        """Check if this entity is a blank node."""
+        return isinstance(self.uri, BNode)
+
+    @property
+    def all_changes(self) -> list[TripleChange]:
+        """Get all triple changes (both additions and removals)."""
+        return self.added_triples + self.removed_triples
+
+
+@dataclass
+class GraphDiff:
+    """Complete result of comparing two RDF graphs.
+
+    Attributes:
+        old_path: Path/name of the old graph.
+        new_path: Path/name of the new graph.
+        added: Entities that exist only in the new graph.
+        removed: Entities that exist only in the old graph.
+        modified: Entities that exist in both but have changes.
+        blank_node_warning: True if blank nodes were encountered.
+    """
+
+    old_path: str
+    new_path: str
+    added: list[EntityChange] = field(default_factory=list)
+    removed: list[EntityChange] = field(default_factory=list)
+    modified: list[EntityChange] = field(default_factory=list)
+    blank_node_warning: bool = False
+
+    @property
+    def is_identical(self) -> bool:
+        """Check if graphs are semantically identical."""
+        return not self.added and not self.removed and not self.modified
+
+    @property
+    def summary(self) -> dict[str, int]:
+        """Get summary counts."""
+        return {
+            "added": len(self.added),
+            "removed": len(self.removed),
+            "modified": len(self.modified),
+        }
+
+    def entities_by_type(
+        self, change_type: ChangeType
+    ) -> dict[EntityType, list[EntityChange]]:
+        """Group entities by their type for a given change type.
+
+        Args:
+            change_type: ADDED, REMOVED, or MODIFIED
+
+        Returns:
+            Dictionary mapping EntityType to list of EntityChange
+        """
+        if change_type == ChangeType.ADDED:
+            entities = self.added
+        elif change_type == ChangeType.REMOVED:
+            entities = self.removed
+        else:
+            entities = self.modified
+
+        result: dict[EntityType, list[EntityChange]] = {}
+        for entity in entities:
+            if entity.entity_type not in result:
+                result[entity.entity_type] = []
+            result[entity.entity_type].append(entity)
+
+        return result
+
+
+def categorise_predicate(predicate: URIRef) -> PredicateCategory:
+    """Categorise a predicate for human-readable output.
+
+    Args:
+        predicate: The predicate URI to categorise
+
+    Returns:
+        The semantic category of the predicate
+    """
+    pred_str = str(predicate)
+
+    # Type predicates
+    if pred_str.endswith("type") or "rdf-syntax-ns#type" in pred_str:
+        return PredicateCategory.TYPE
+
+    # Hierarchy predicates
+    if any(
+        x in pred_str
+        for x in ["subClassOf", "subPropertyOf", "equivalentClass", "equivalentProperty"]
+    ):
+        return PredicateCategory.HIERARCHY
+
+    # Domain/range
+    if any(x in pred_str for x in ["domain", "range"]):
+        return PredicateCategory.DOMAIN_RANGE
+
+    # Labels
+    if "label" in pred_str.lower() or "prefLabel" in pred_str:
+        return PredicateCategory.LABEL
+
+    # Documentation
+    if any(x in pred_str.lower() for x in ["comment", "description", "definition", "note"]):
+        return PredicateCategory.DOCUMENTATION
+
+    # OWL axioms
+    if "owl" in pred_str.lower() and any(
+        x in pred_str
+        for x in [
+            "disjoint",
+            "inverse",
+            "functional",
+            "cardinality",
+            "restriction",
+            "union",
+            "intersection",
+        ]
+    ):
+        return PredicateCategory.OWL_AXIOM
+
+    return PredicateCategory.OTHER