rdf-construct 0.3.0__py3-none-any.whl

rdf_construct/merge/migrator.py

@@ -0,0 +1,339 @@
+"""Data graph migration for ontology changes.
+
+This module handles migrating instance data when ontologies change:
+- Simple URI substitution (renames, namespace changes)
+- Complex CONSTRUCT-style transformations (property splits, type migrations)
+
+The migrator is reusable by merge, split, and refactor commands.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from rdflib import Graph, URIRef, Literal, BNode
+from rdflib.namespace import RDF
+
+from rdf_construct.merge.config import MigrationRule, DataMigrationConfig
+from rdf_construct.merge.rules import RuleEngine
+
+
+@dataclass
+class MigrationStats:
+    """Statistics from a migration operation.
+
+    Attributes:
+        subjects_updated: Number of subject URIs substituted
+        objects_updated: Number of object URIs substituted
+        triples_added: Number of triples added by transformations
+        triples_removed: Number of triples removed by transformations
+        rules_applied: Count of each rule applied
+    """
+
+    subjects_updated: int = 0
+    objects_updated: int = 0
+    triples_added: int = 0
+    triples_removed: int = 0
+    rules_applied: dict[str, int] = field(default_factory=dict)
+
+    @property
+    def total_changes(self) -> int:
+        """Total number of changes made."""
+        return (
+            self.subjects_updated
+            + self.objects_updated
+            + self.triples_added
+            + self.triples_removed
+        )
+
+
+@dataclass
+class MigrationResult:
+    """Result of a data migration operation.
+
+    Attributes:
+        migrated_graph: The migrated RDF graph
+        stats: Migration statistics
+        success: Whether migration completed without errors
+        error: Error message if success is False
+        source_triples: Original triple count
+        result_triples: Final triple count
+    """
+
+    migrated_graph: Graph | None = None
+    stats: MigrationStats = field(default_factory=MigrationStats)
+    success: bool = True
+    error: str | None = None
+    source_triples: int = 0
+    result_triples: int = 0
+
+
+class DataMigrator:
+    """Migrates instance data graphs when ontology structure changes.
+
+    Supports two types of migration:
+
+    1. **Simple URI substitution**: Replaces URIs throughout the graph.
+       Used for renames, namespace changes, and class/property moves.
+
+    2. **Complex transformations**: SPARQL CONSTRUCT-style rules that can:
+       - Split properties (fullName → givenName + familyName)
+       - Merge properties
+       - Change types (Company → Organisation)
+       - Transform values (Fahrenheit → Celsius)
+
+    Example usage:
+        migrator = DataMigrator()
+        uri_map = {
+            URIRef("http://old.org/Class"): URIRef("http://new.org/Class")
+        }
+        result = migrator.migrate(data_graph, uri_map=uri_map)
+    """
+
+    def __init__(self):
+        """Initialize the data migrator."""
+        self.rule_engine = RuleEngine()
+
+    def migrate(
+        self,
+        data: Graph,
+        uri_map: dict[URIRef, URIRef] | None = None,
+        rules: list[MigrationRule] | None = None,
+    ) -> MigrationResult:
+        """Migrate a data graph.
+
+        Args:
+            data: Source data graph to migrate
+            uri_map: Simple URI substitution map (old -> new)
+            rules: Complex migration rules to apply
+
+        Returns:
+            MigrationResult with migrated graph and statistics
+        """
+        result = MigrationResult()
+        result.source_triples = len(data)
+
+        # Create a new graph for the migrated data
+        migrated = Graph()
+
+        # Copy namespace bindings
+        for prefix, ns in data.namespace_manager.namespaces():
+            migrated.bind(prefix, ns)
+
+        # Phase 1: Apply simple URI substitutions
+        if uri_map:
+            for s, p, o in data:
+                new_s = self._substitute_uri(s, uri_map, result.stats, is_subject=True)
+                new_o = self._substitute_uri(o, uri_map, result.stats, is_subject=False)
+                migrated.add((new_s, p, new_o))
+        else:
+            # No substitutions, just copy
+            for triple in data:
+                migrated.add(triple)
+
+        # Phase 2: Apply complex transformation rules
+        if rules:
+            for rule in rules:
+                if rule.type == "rename":
+                    # Handle rename rules that weren't in uri_map
+                    if rule.from_uri and rule.to_uri:
+                        single_map = {
+                            URIRef(rule.from_uri): URIRef(rule.to_uri)
+                        }
+                        migrated = self._apply_uri_substitution(
+                            migrated, single_map, result.stats
+                        )
+                        result.stats.rules_applied[rule.description or "rename"] = (
+                            result.stats.rules_applied.get(rule.description or "rename", 0) + 1
+                        )
+
+                elif rule.type == "transform":
+                    changes = self.rule_engine.apply_rule(migrated, rule)
+                    result.stats.triples_added += changes.get("added", 0)
+                    result.stats.triples_removed += changes.get("removed", 0)
+                    result.stats.rules_applied[rule.description or "transform"] = (
+                        result.stats.rules_applied.get(rule.description or "transform", 0)
+                        + changes.get("instances", 0)
+                    )
+
+        result.migrated_graph = migrated
+        result.result_triples = len(migrated)
+        result.success = True
+
+        return result
+
+    def _substitute_uri(
+        self,
+        term: Any,
+        uri_map: dict[URIRef, URIRef],
+        stats: MigrationStats,
+        is_subject: bool,
+    ) -> Any:
+        """Substitute a URI if it's in the mapping.
+
+        Args:
+            term: RDF term to potentially substitute
+            uri_map: URI substitution map
+            stats: Statistics to update
+            is_subject: Whether this is a subject position
+
+        Returns:
+            Substituted term or original
+        """
+        if isinstance(term, URIRef) and term in uri_map:
+            if is_subject:
+                stats.subjects_updated += 1
+            else:
+                stats.objects_updated += 1
+            return uri_map[term]
+        return term
+
+    def _apply_uri_substitution(
+        self,
+        graph: Graph,
+        uri_map: dict[URIRef, URIRef],
+        stats: MigrationStats,
+    ) -> Graph:
+        """Apply URI substitution to an entire graph.
+
+        Args:
+            graph: Graph to transform
+            uri_map: URI substitution map
+            stats: Statistics to update
+
+        Returns:
+            New graph with substitutions applied
+        """
+        new_graph = Graph()
+
+        # Copy namespace bindings, updating if needed
+        for prefix, ns in graph.namespace_manager.namespaces():
+            new_graph.bind(prefix, ns)
+
+        for s, p, o in graph:
+            new_s = self._substitute_uri(s, uri_map, stats, is_subject=True)
+            new_o = self._substitute_uri(o, uri_map, stats, is_subject=False)
+            new_graph.add((new_s, p, new_o))
+
+        return new_graph
+
+    def build_uri_map_from_namespaces(
+        self,
+        graph: Graph,
+        namespace_remaps: dict[str, str],
+    ) -> dict[URIRef, URIRef]:
+        """Build a URI map from namespace remappings.
+
+        Scans the graph for all URIs and creates substitution entries
+        for those that fall within remapped namespaces.
+
+        Args:
+            graph: Graph to scan for URIs
+            namespace_remaps: Old namespace -> new namespace mapping
+
+        Returns:
+            URI substitution map
+        """
+        uri_map: dict[URIRef, URIRef] = {}
+
+        # Collect all URIs from the graph
+        all_uris: set[URIRef] = set()
+        for s, p, o in graph:
+            if isinstance(s, URIRef):
+                all_uris.add(s)
+            if isinstance(p, URIRef):
+                all_uris.add(p)
+            if isinstance(o, URIRef):
+                all_uris.add(o)
+
+        # Build substitution map
+        for uri in all_uris:
+            uri_str = str(uri)
+            for old_ns, new_ns in namespace_remaps.items():
+                if uri_str.startswith(old_ns):
+                    new_uri_str = uri_str.replace(old_ns, new_ns, 1)
+                    uri_map[uri] = URIRef(new_uri_str)
+                    break
+
+        return uri_map
+
+
+def migrate_data_files(
+    data_paths: list[Path],
+    uri_map: dict[URIRef, URIRef] | None = None,
+    rules: list[MigrationRule] | None = None,
+    output_path: Path | None = None,
+) -> MigrationResult:
+    """Convenience function to migrate multiple data files.
+
+    Args:
+        data_paths: Paths to data files to migrate
+        uri_map: URI substitution map
+        rules: Migration rules to apply
+        output_path: Path to write combined migrated output
+
+    Returns:
+        MigrationResult with combined statistics
+    """
+    migrator = DataMigrator()
+    combined_result = MigrationResult()
+    combined_graph = Graph()
+    combined_stats = MigrationStats()
+
+    for data_path in data_paths:
+        if not data_path.exists():
+            combined_result.success = False
+            combined_result.error = f"Data file not found: {data_path}"
+            return combined_result
+
+        # Load the data file
+        data = Graph()
+        try:
+            data.parse(data_path.as_posix())
+        except Exception as e:
+            combined_result.success = False
+            combined_result.error = f"Failed to parse {data_path}: {e}"
+            return combined_result
+
+        # Migrate this file
+        result = migrator.migrate(data, uri_map=uri_map, rules=rules)
+
+        if not result.success:
+            return result
+
+        # Combine results
+        combined_result.source_triples += result.source_triples
+        if result.migrated_graph:
+            for triple in result.migrated_graph:
+                combined_graph.add(triple)
+
+            # Copy namespace bindings
+            for prefix, ns in result.migrated_graph.namespace_manager.namespaces():
+                try:
+                    combined_graph.bind(prefix, ns, override=False)
+                except Exception:
+                    pass
+
+        # Combine stats
+        combined_stats.subjects_updated += result.stats.subjects_updated
+        combined_stats.objects_updated += result.stats.objects_updated
+        combined_stats.triples_added += result.stats.triples_added
+        combined_stats.triples_removed += result.stats.triples_removed
+        for rule_name, count in result.stats.rules_applied.items():
+            combined_stats.rules_applied[rule_name] = (
+                combined_stats.rules_applied.get(rule_name, 0) + count
+            )
+
+    combined_result.migrated_graph = combined_graph
+    combined_result.stats = combined_stats
+    combined_result.result_triples = len(combined_graph)
+    combined_result.success = True
+
+    # Write output if path provided
+    if output_path and combined_result.migrated_graph:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        combined_result.migrated_graph.serialize(
+            destination=output_path.as_posix(), format="turtle"
+        )
+
+    return combined_result

rdf_construct/merge/rules.py

@@ -0,0 +1,377 @@
+"""Migration rule parsing and execution.
+
+This module handles complex transformation rules using a SPARQL-like
+pattern matching approach:
+
+- Match patterns: Find triples matching a pattern
+- Construct patterns: Create new triples from matches
+- Delete patterns: Remove matched triples
+
+This enables structural transformations like:
+- Property splits (fullName → givenName + familyName)
+- Type migrations (Company → Organisation)
+- Value transformations
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from rdflib import Graph, URIRef, Literal, BNode, Namespace
+from rdflib.namespace import RDF, RDFS, XSD
+from rdflib.term import Node
+
+from rdf_construct.merge.config import MigrationRule
+
+
+@dataclass
+class Binding:
+    """A variable binding from pattern matching.
+
+    Attributes:
+        variable: Variable name (without ?)
+        value: Bound RDF value
+    """
+
+    variable: str
+    value: Node
+
+
+@dataclass
+class Match:
+    """A single match result from pattern matching.
+
+    Attributes:
+        bindings: Dictionary of variable -> value bindings
+        matched_triples: Triples that were matched
+    """
+
+    bindings: dict[str, Node] = field(default_factory=dict)
+    matched_triples: list[tuple] = field(default_factory=list)
+
+
+class PatternParser:
+    """Parses simple SPARQL-like triple patterns.
+
+    Supports patterns like:
+    - "?s ex:fullName ?name"
+    - "?s a ex:Company"
+
+    Variables start with ?
+    URIs can be full or prefixed (requires namespace context)
+    """
+
+    # Pattern for variables like ?s, ?name
+    VARIABLE_PATTERN = re.compile(r"\?(\w+)")
+
+    def __init__(self, namespaces: dict[str, Namespace] | None = None):
+        """Initialize the parser.
+
+        Args:
+            namespaces: Prefix -> Namespace mapping for expanding CURIEs
+        """
+        self.namespaces = namespaces or {}
+
+    def parse_pattern(self, pattern: str) -> tuple[Any, Any, Any]:
+        """Parse a triple pattern into (subject, predicate, object).
+
+        Args:
+            pattern: Triple pattern string like "?s ex:hasName ?name"
+
+        Returns:
+            Tuple of (subject, predicate, object) where variables are
+            represented as strings starting with ?
+        """
+        # Handle special "a" for rdf:type
+        pattern = pattern.replace(" a ", f" {RDF.type} ")
+
+        parts = pattern.strip().split(None, 2)
+        if len(parts) != 3:
+            raise ValueError(f"Invalid pattern (expected 3 parts): {pattern}")
+
+        return (
+            self._parse_term(parts[0]),
+            self._parse_term(parts[1]),
+            self._parse_term(parts[2]),
+        )
+
+    def _parse_term(self, term: str) -> Any:
+        """Parse a single term from a pattern.
+
+        Args:
+            term: Term string (variable, URI, or literal)
+
+        Returns:
+            Parsed term: string for variables, URIRef for URIs, etc.
+        """
+        term = term.strip()
+
+        # Variable
+        if term.startswith("?"):
+            return term  # Keep as string marker
+
+        # Full URI in angle brackets
+        if term.startswith("<") and term.endswith(">"):
+            return URIRef(term[1:-1])
+
+        # Already a URIRef (from pattern replacement like RDF.type)
+        if isinstance(term, URIRef):
+            return term
+        if term.startswith("http://") or term.startswith("https://"):
+            return URIRef(term)
+
+        # Prefixed name
+        if ":" in term:
+            prefix, local = term.split(":", 1)
+            if prefix in self.namespaces:
+                return URIRef(str(self.namespaces[prefix]) + local)
+            # If prefix not found, return as-is (may be handled later)
+            return URIRef(term)
+
+        # Literal (quoted string)
+        if term.startswith('"') and term.endswith('"'):
+            return Literal(term[1:-1])
+
+        # Default: treat as local name (would need base URI)
+        return term
+
+
+class RuleEngine:
+    """Executes transformation rules on RDF graphs.
+
+    Supports:
+    - Pattern matching with variable bindings
+    - Triple construction from bindings
+    - Simple value transformations (STRBEFORE, STRAFTER)
+    """
+
+    def __init__(self):
+        """Initialize the rule engine."""
+        self.parser = PatternParser()
+
+    def set_namespaces(self, graph: Graph) -> None:
+        """Update parser namespaces from a graph.
+
+        Args:
+            graph: Graph to extract namespaces from
+        """
+        self.parser.namespaces = {
+            prefix: Namespace(str(ns))
+            for prefix, ns in graph.namespace_manager.namespaces()
+        }
+
+    def apply_rule(self, graph: Graph, rule: MigrationRule) -> dict[str, int]:
+        """Apply a transformation rule to a graph.
+
+        Modifies the graph in place.
+
+        Args:
+            graph: Graph to transform
+            rule: Transformation rule to apply
+
+        Returns:
+            Statistics: {"added": n, "removed": n, "instances": n}
+        """
+        self.set_namespaces(graph)
+
+        if rule.type != "transform" or not rule.match:
+            return {"added": 0, "removed": 0, "instances": 0}
+
+        stats = {"added": 0, "removed": 0, "instances": 0}
+
+        # Find all matches
+        matches = self._find_matches(graph, rule.match)
+
+        for match in matches:
+            stats["instances"] += 1
+
+            # Construct new triples
+            if rule.construct:
+                for construct_spec in rule.construct:
+                    new_triples = self._construct_triples(
+                        match, construct_spec, graph
+                    )
+                    for triple in new_triples:
+                        graph.add(triple)
+                        stats["added"] += 1
+
+            # Delete matched triples if configured
+            if rule.delete_matched:
+                for triple in match.matched_triples:
+                    graph.remove(triple)
+                    stats["removed"] += 1
+
+        return stats
+
+    def _find_matches(self, graph: Graph, pattern_str: str) -> list[Match]:
+        """Find all matches for a pattern in the graph.
+
+        Args:
+            graph: Graph to search
+            pattern_str: Pattern string to match
+
+        Returns:
+            List of Match objects with bindings
+        """
+        try:
+            pattern = self.parser.parse_pattern(pattern_str)
+        except ValueError:
+            return []
+
+        matches: list[Match] = []
+
+        # Build query pattern for graph iteration
+        query_s = None if isinstance(pattern[0], str) else pattern[0]
+        query_p = None if isinstance(pattern[1], str) else pattern[1]
+        query_o = None if isinstance(pattern[2], str) else pattern[2]
+
+        for s, p, o in graph.triples((query_s, query_p, query_o)):
+            bindings: dict[str, Node] = {}
+
+            # Check and bind each position
+            if isinstance(pattern[0], str):  # Variable
+                bindings[pattern[0][1:]] = s  # Remove ? prefix
+            elif pattern[0] != s:
+                continue
+
+            if isinstance(pattern[1], str):
+                bindings[pattern[1][1:]] = p
+            elif pattern[1] != p:
+                continue
+
+            if isinstance(pattern[2], str):
+                bindings[pattern[2][1:]] = o
+            elif pattern[2] != o:
+                continue
+
+            matches.append(
+                Match(bindings=bindings, matched_triples=[(s, p, o)])
+            )
+
+        return matches
+
+    def _construct_triples(
+        self,
+        match: Match,
+        construct_spec: dict[str, str],
+        graph: Graph,
+    ) -> list[tuple]:
+        """Construct new triples from a match and specification.
+
+        Args:
+            match: Match with variable bindings
+            construct_spec: Construction specification with pattern and optional bind
+            graph: Graph for namespace resolution
+
+        Returns:
+            List of new triples to add
+        """
+        pattern_str = construct_spec.get("pattern", "")
+        bind_expr = construct_spec.get("bind")
+
+        try:
+            pattern = self.parser.parse_pattern(pattern_str)
+        except ValueError:
+            return []
+
+        # Substitute variables in pattern
+        result_s = self._substitute_variable(pattern[0], match.bindings)
+        result_p = self._substitute_variable(pattern[1], match.bindings)
+
+        if bind_expr:
+            # Evaluate bind expression
+            result_o = self._evaluate_bind(bind_expr, match.bindings)
+        else:
+            result_o = self._substitute_variable(pattern[2], match.bindings)
+
+        if result_s is None or result_p is None or result_o is None:
+            return []
+
+        return [(result_s, result_p, result_o)]
+
+    def _substitute_variable(
+        self, term: Any, bindings: dict[str, Node]
+    ) -> Node | None:
+        """Substitute a variable with its bound value.
+
+        Args:
+            term: Term to substitute (may be a variable string)
+            bindings: Variable bindings
+
+        Returns:
+            Substituted value or None if variable not bound
+        """
+        if isinstance(term, str) and term.startswith("?"):
+            var_name = term[1:]
+            return bindings.get(var_name)
+        return term
+
+    def _evaluate_bind(
+        self, expression: str, bindings: dict[str, Node]
+    ) -> Node | None:
+        """Evaluate a simple bind expression.
+
+        Supports:
+        - STRBEFORE(?var, 'delimiter') - substring before delimiter
+        - STRAFTER(?var, 'delimiter') - substring after delimiter
+        - Simple arithmetic with +, -, *, /
+
+        Args:
+            expression: Bind expression string
+            bindings: Variable bindings
+
+        Returns:
+            Evaluated value or None
+        """
+        # Handle STRBEFORE
+        strbefore_match = re.match(
+            r"STRBEFORE\(\?(\w+),\s*['\"](.+)['\"]\)\s*AS\s*\?(\w+)",
+            expression,
+            re.IGNORECASE,
+        )
+        if strbefore_match:
+            var_name = strbefore_match.group(1)
+            delimiter = strbefore_match.group(2)
+            if var_name in bindings:
+                value = str(bindings[var_name])
+                idx = value.find(delimiter)
+                if idx >= 0:
+                    return Literal(value[:idx])
+            return None
+
+        # Handle STRAFTER
+        strafter_match = re.match(
+            r"STRAFTER\(\?(\w+),\s*['\"](.+)['\"]\)\s*AS\s*\?(\w+)",
+            expression,
+            re.IGNORECASE,
+        )
+        if strafter_match:
+            var_name = strafter_match.group(1)
+            delimiter = strafter_match.group(2)
+            if var_name in bindings:
+                value = str(bindings[var_name])
+                idx = value.find(delimiter)
+                if idx >= 0:
+                    return Literal(value[idx + len(delimiter) :])
+            return None
+
+        # Handle simple arithmetic: ((?var - n) * m / d) AS ?result
+        arith_match = re.match(
+            r"\(\(\?(\w+)\s*-\s*(\d+)\)\s*\*\s*(\d+)/(\d+)\)\s*AS\s*\?(\w+)",
+            expression,
+        )
+        if arith_match:
+            var_name = arith_match.group(1)
+            sub = float(arith_match.group(2))
+            mult = float(arith_match.group(3))
+            div = float(arith_match.group(4))
+            if var_name in bindings:
+                try:
+                    value = float(str(bindings[var_name]))
+                    result = ((value - sub) * mult) / div
+                    return Literal(result, datatype=XSD.decimal)
+                except (ValueError, ZeroDivisionError):
+                    return None
+            return None
+
+        return None