rdf-construct 0.2.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

rdf_construct/refactor/deprecator.py

@@ -0,0 +1,328 @@
+"""Deprecation workflow for ontology entities.
+
+This module handles marking ontology entities as deprecated:
+- Adds owl:deprecated true
+- Adds dcterms:isReplacedBy with replacement URI
+- Updates rdfs:comment with deprecation notice
+- Preserves all existing properties
+
+Deprecation marks entities but does NOT rename or migrate references.
+Use 'refactor rename' to actually migrate references after deprecation.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from rdflib import Graph, URIRef, Literal, Namespace
+from rdflib.namespace import RDF, RDFS, OWL, DCTERMS
+
+from rdf_construct.refactor.config import DeprecationSpec, DeprecationConfig
+
+
+# Dublin Core Terms namespace
+DCTERMS = Namespace("http://purl.org/dc/terms/")
+
+
+@dataclass
+class EntityDeprecationInfo:
+    """Information about a deprecated entity.
+
+    Attributes:
+        uri: URI of the deprecated entity.
+        found: Whether the entity was found in the graph.
+        current_labels: Current rdfs:label values.
+        current_comments: Current rdfs:comment values.
+        was_already_deprecated: Whether owl:deprecated was already present.
+        triples_added: Number of triples added.
+        reference_count: Number of references to this entity in the graph.
+        replaced_by: Replacement entity URI (if specified).
+        message: Deprecation message added.
+    """
+
+    uri: str
+    found: bool = True
+    current_labels: list[str] = field(default_factory=list)
+    current_comments: list[str] = field(default_factory=list)
+    was_already_deprecated: bool = False
+    triples_added: int = 0
+    reference_count: int = 0
+    replaced_by: str | None = None
+    message: str | None = None
+
+
+@dataclass
+class DeprecationStats:
+    """Statistics from a deprecation operation.
+
+    Attributes:
+        entities_deprecated: Number of entities marked deprecated.
+        entities_not_found: Number of entities not found in graph.
+        entities_already_deprecated: Entities that were already deprecated.
+        triples_added: Total triples added.
+    """
+
+    entities_deprecated: int = 0
+    entities_not_found: int = 0
+    entities_already_deprecated: int = 0
+    triples_added: int = 0
+
+
+@dataclass
+class DeprecationResult:
+    """Result of a deprecation operation.
+
+    Attributes:
+        deprecated_graph: The graph with deprecations added.
+        stats: Deprecation statistics.
+        success: Whether the operation succeeded.
+        error: Error message if success is False.
+        entity_info: Detailed info about each entity processed.
+        source_triples: Original triple count.
+        result_triples: Final triple count.
+    """
+
+    deprecated_graph: Graph | None = None
+    stats: DeprecationStats = field(default_factory=DeprecationStats)
+    success: bool = True
+    error: str | None = None
+    entity_info: list[EntityDeprecationInfo] = field(default_factory=list)
+    source_triples: int = 0
+    result_triples: int = 0
+
+
+class OntologyDeprecator:
+    """Marks ontology entities as deprecated.
+
+    Adds standard OWL deprecation annotations:
+    - owl:deprecated true
+    - dcterms:isReplacedBy (if replacement specified)
+    - Prepends "DEPRECATED: " to rdfs:comment
+
+    Example usage:
+        deprecator = OntologyDeprecator()
+        result = deprecator.deprecate(
+            graph,
+            entity="http://example.org/OldClass",
+            replaced_by="http://example.org/NewClass",
+            message="Use NewClass instead."
+        )
+    """
+
+    def deprecate(
+        self,
+        graph: Graph,
+        entity: str,
+        replaced_by: str | None = None,
+        message: str | None = None,
+        version: str | None = None,
+    ) -> DeprecationResult:
+        """Mark a single entity as deprecated.
+
+        Args:
+            graph: Source RDF graph (will be modified in-place).
+            entity: URI of entity to deprecate.
+            replaced_by: Optional URI of replacement entity.
+            message: Optional deprecation message.
+            version: Optional version when deprecated.
+
+        Returns:
+            DeprecationResult with updated graph.
+        """
+        result = DeprecationResult()
+        result.source_triples = len(graph)
+
+        entity_uri = URIRef(entity)
+        info = EntityDeprecationInfo(uri=entity)
+
+        # Check if entity exists in the graph
+        entity_exists = False
+        for s, p, o in graph:
+            if s == entity_uri:
+                entity_exists = True
+                break
+            if o == entity_uri:
+                info.reference_count += 1
+
+        if not entity_exists:
+            # Entity not found as subject - check if it's referenced
+            info.found = False
+            result.stats.entities_not_found += 1
+            result.entity_info.append(info)
+            result.deprecated_graph = graph
+            result.result_triples = len(graph)
+            return result
+
+        # Get current labels and comments
+        for label in graph.objects(entity_uri, RDFS.label):
+            if isinstance(label, Literal):
+                info.current_labels.append(str(label))
+
+        for comment in graph.objects(entity_uri, RDFS.comment):
+            if isinstance(comment, Literal):
+                info.current_comments.append(str(comment))
+
+        # Check if already deprecated
+        for obj in graph.objects(entity_uri, OWL.deprecated):
+            if str(obj).lower() == "true":
+                info.was_already_deprecated = True
+                result.stats.entities_already_deprecated += 1
+                break
+
+        # Add owl:deprecated true (if not already present)
+        if not info.was_already_deprecated:
+            graph.add((entity_uri, OWL.deprecated, Literal(True)))
+            info.triples_added += 1
+            result.stats.entities_deprecated += 1
+
+        # Add dcterms:isReplacedBy if replacement specified
+        if replaced_by:
+            replaced_by_uri = URIRef(replaced_by)
+            # Remove any existing isReplacedBy
+            graph.remove((entity_uri, DCTERMS.isReplacedBy, None))
+            graph.add((entity_uri, DCTERMS.isReplacedBy, replaced_by_uri))
+            info.triples_added += 1
+            info.replaced_by = replaced_by
+
+        # Add/update deprecation comment
+        if message:
+            # Build full deprecation message
+            deprecation_msg = f"DEPRECATED: {message}"
+            if version:
+                deprecation_msg = f"DEPRECATED (v{version}): {message}"
+            info.message = deprecation_msg
+
+            # Check if there's an existing comment to update
+            existing_deprecated_comment = None
+            for comment in list(graph.objects(entity_uri, RDFS.comment)):
+                if isinstance(comment, Literal) and str(comment).startswith("DEPRECATED"):
+                    existing_deprecated_comment = comment
+                    break
+
+            if existing_deprecated_comment:
+                # Remove old deprecation comment
+                graph.remove((entity_uri, RDFS.comment, existing_deprecated_comment))
+
+            # Add new deprecation comment
+            graph.add((entity_uri, RDFS.comment, Literal(deprecation_msg, lang="en")))
+            info.triples_added += 1
+
+        # Ensure dcterms namespace is bound
+        graph.bind("dcterms", DCTERMS, override=False)
+
+        result.stats.triples_added += info.triples_added
+        result.entity_info.append(info)
+        result.deprecated_graph = graph
+        result.result_triples = len(graph)
+        result.success = True
+
+        return result
+
+    def deprecate_bulk(
+        self,
+        graph: Graph,
+        specs: list[DeprecationSpec],
+    ) -> DeprecationResult:
+        """Mark multiple entities as deprecated.
+
+        Args:
+            graph: Source RDF graph (will be modified in-place).
+            specs: List of deprecation specifications.
+
+        Returns:
+            DeprecationResult with updated graph.
+        """
+        combined_result = DeprecationResult()
+        combined_result.source_triples = len(graph)
+
+        for spec in specs:
+            result = self.deprecate(
+                graph=graph,
+                entity=spec.entity,
+                replaced_by=spec.replaced_by,
+                message=spec.message,
+                version=spec.version,
+            )
+
+            # Combine stats
+            combined_result.stats.entities_deprecated += result.stats.entities_deprecated
+            combined_result.stats.entities_not_found += result.stats.entities_not_found
+            combined_result.stats.entities_already_deprecated += (
+                result.stats.entities_already_deprecated
+            )
+            combined_result.stats.triples_added += result.stats.triples_added
+
+            # Combine entity info
+            combined_result.entity_info.extend(result.entity_info)
+
+        combined_result.deprecated_graph = graph
+        combined_result.result_triples = len(graph)
+        combined_result.success = True
+
+        return combined_result
+
+
+def deprecate_file(
+    source_path: Path,
+    output_path: Path,
+    specs: list[DeprecationSpec],
+) -> DeprecationResult:
+    """Convenience function to deprecate entities in a file.
+
+    Args:
+        source_path: Path to source RDF file.
+        output_path: Path to write updated output.
+        specs: List of deprecation specifications.
+
+    Returns:
+        DeprecationResult with statistics.
+    """
+    # Load source graph
+    graph = Graph()
+    try:
+        graph.parse(source_path.as_posix())
+    except Exception as e:
+        result = DeprecationResult()
+        result.success = False
+        result.error = f"Failed to parse {source_path}: {e}"
+        return result
+
+    # Perform deprecation
+    deprecator = OntologyDeprecator()
+    result = deprecator.deprecate_bulk(graph, specs)
+
+    if not result.success:
+        return result
+
+    # Write output
+    if result.deprecated_graph:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        result.deprecated_graph.serialize(destination=output_path.as_posix(), format="turtle")
+
+    return result
+
+
+def generate_deprecation_message(
+    replaced_by: str | None,
+    message: str | None,
+    version: str | None,
+) -> str:
+    """Generate a standard deprecation message.
+
+    Args:
+        replaced_by: Replacement entity URI.
+        message: Custom message.
+        version: Version when deprecated.
+
+    Returns:
+        Formatted deprecation message.
+    """
+    if message:
+        return message
+
+    if replaced_by:
+        # Extract local name from URI
+        local_name = replaced_by.split("#")[-1].split("/")[-1]
+        return f"Use {local_name} instead."
+
+    return "This entity is deprecated and should not be used."

rdf_construct/refactor/formatters/__init__.py

@@ -0,0 +1,8 @@
+"""Formatters for refactor command output.
+
+This package provides formatters for dry-run previews and result output.
+"""
+
+from rdf_construct.refactor.formatters.text import TextFormatter
+
+__all__ = ["TextFormatter"]

rdf_construct/refactor/formatters/text.py

@@ -0,0 +1,311 @@
+"""Text formatter for refactor command output.
+
+Provides formatted output for dry-run previews and results.
+"""
+
+from typing import Any
+
+from rdf_construct.refactor.config import RenameConfig, RenameMapping, DeprecationSpec
+from rdf_construct.refactor.renamer import RenameResult, RenameStats
+from rdf_construct.refactor.deprecator import DeprecationResult, EntityDeprecationInfo
+
+
+class TextFormatter:
+    """Text formatter for refactor results and previews.
+
+    Attributes:
+        use_colour: Whether to use ANSI colour codes.
+    """
+
+    def __init__(self, use_colour: bool = True):
+        """Initialize formatter.
+
+        Args:
+            use_colour: Whether to use ANSI colour codes.
+        """
+        self.use_colour = use_colour
+
+    def _colour(self, text: str, colour: str) -> str:
+        """Apply ANSI colour code if enabled.
+
+        Args:
+            text: Text to colour.
+            colour: Colour name (green, red, yellow, cyan, bold).
+
+        Returns:
+            Coloured text (or original if colour disabled).
+        """
+        if not self.use_colour:
+            return text
+
+        codes = {
+            "green": "\033[32m",
+            "red": "\033[31m",
+            "yellow": "\033[33m",
+            "cyan": "\033[36m",
+            "bold": "\033[1m",
+            "dim": "\033[2m",
+            "reset": "\033[0m",
+        }
+        return f"{codes.get(colour, '')}{text}{codes['reset']}"
+
+    def format_rename_preview(
+        self,
+        mappings: list[RenameMapping],
+        source_file: str,
+        source_triples: int,
+        literal_mentions: dict[str, int] | None = None,
+    ) -> str:
+        """Format a dry-run preview for rename operation.
+
+        Args:
+            mappings: List of rename mappings to apply.
+            source_file: Name of source file.
+            source_triples: Number of triples in source.
+            literal_mentions: Count of mentions in literals (won't be changed).
+
+        Returns:
+            Formatted preview string.
+        """
+        lines = [
+            self._colour("Refactoring Preview: Rename", "bold"),
+            "=" * 27,
+            "",
+            f"Source: {source_file} ({source_triples:,} triples)",
+            "",
+        ]
+
+        # Group by source type
+        namespace_mappings = [m for m in mappings if m.source == "namespace"]
+        explicit_mappings = [m for m in mappings if m.source == "explicit"]
+
+        if namespace_mappings:
+            # Group by namespace
+            namespaces: dict[str, list[RenameMapping]] = {}
+            for m in namespace_mappings:
+                # Extract namespace prefix
+                from_str = str(m.from_uri)
+                to_str = str(m.to_uri)
+                # Find common prefix
+                ns_from = from_str.rsplit("#", 1)[0] + "#" if "#" in from_str else from_str.rsplit("/", 1)[0] + "/"
+                ns_to = to_str.rsplit("#", 1)[0] + "#" if "#" in to_str else to_str.rsplit("/", 1)[0] + "/"
+                key = f"{ns_from} → {ns_to}"
+                if key not in namespaces:
+                    namespaces[key] = []
+                namespaces[key].append(m)
+
+            lines.append(self._colour("Namespace renames:", "cyan"))
+            for ns_change, ns_mappings in namespaces.items():
+                lines.append(f"  {ns_change}")
+                lines.append(f"    - {len(ns_mappings)} entities affected")
+            lines.append("")
+
+        if explicit_mappings:
+            lines.append(self._colour("Entity renames:", "cyan"))
+            for m in explicit_mappings:
+                from_local = str(m.from_uri).split("#")[-1].split("/")[-1]
+                to_local = str(m.to_uri).split("#")[-1].split("/")[-1]
+                lines.append(f"  {from_local} → {to_local}")
+
+                # Check for literal mentions
+                if literal_mentions and str(m.from_uri) in literal_mentions:
+                    count = literal_mentions[str(m.from_uri)]
+                    lines.append(
+                        f"    └─ {count} literal mention(s) "
+                        f"{self._colour('(NOT changed)', 'yellow')}"
+                    )
+            lines.append("")
+
+        # Summary
+        lines.append(self._colour("Totals:", "bold"))
+        lines.append(f"  - {len(mappings)} entities to rename")
+        if namespace_mappings:
+            lines.append(f"  - {len(namespace_mappings)} from namespace rules")
+        if explicit_mappings:
+            lines.append(f"  - {len(explicit_mappings)} from explicit rules")
+        lines.append("")
+        lines.append(self._colour("Run without --dry-run to apply changes.", "dim"))
+
+        return "\n".join(lines)
+
+    def format_rename_result(self, result: RenameResult) -> str:
+        """Format the result of a rename operation.
+
+        Args:
+            result: Result from rename operation.
+
+        Returns:
+            Formatted result string.
+        """
+        if not result.success:
+            return self._colour(f"✗ Rename failed: {result.error}", "red")
+
+        lines = [
+            self._colour("Rename Complete", "green"),
+            "",
+            f"  Source triples: {result.source_triples:,}",
+            f"  Result triples: {result.result_triples:,}",
+            "",
+            self._colour("Changes:", "cyan"),
+            f"  - Subjects renamed: {result.stats.subjects_renamed:,}",
+            f"  - Predicates renamed: {result.stats.predicates_renamed:,}",
+            f"  - Objects renamed: {result.stats.objects_renamed:,}",
+            f"  - Total URI substitutions: {result.stats.total_renames:,}",
+        ]
+
+        if result.stats.namespace_entities > 0:
+            lines.append(f"  - Via namespace rules: {result.stats.namespace_entities:,}")
+        if result.stats.explicit_entities > 0:
+            lines.append(f"  - Via explicit rules: {result.stats.explicit_entities:,}")
+
+        if result.stats.literal_mentions:
+            lines.append("")
+            lines.append(
+                self._colour(
+                    f"  ⚠ {len(result.stats.literal_mentions)} entities mentioned in literals "
+                    "(not modified)",
+                    "yellow",
+                )
+            )
+
+        return "\n".join(lines)
+
+    def format_deprecation_preview(
+        self,
+        specs: list[DeprecationSpec],
+        entity_info: list[EntityDeprecationInfo] | None = None,
+        source_file: str = "",
+        source_triples: int = 0,
+    ) -> str:
+        """Format a dry-run preview for deprecation operation.
+
+        Args:
+            specs: List of deprecation specifications.
+            entity_info: Optional entity information from dry run.
+            source_file: Name of source file.
+            source_triples: Number of triples in source.
+
+        Returns:
+            Formatted preview string.
+        """
+        lines = [
+            self._colour("Refactoring Preview: Deprecate", "bold"),
+            "=" * 30,
+            "",
+            f"Source: {source_file} ({source_triples:,} triples)" if source_file else "",
+            "",
+            self._colour("Entities to deprecate:", "cyan"),
+            "",
+        ]
+
+        for i, spec in enumerate(specs):
+            # Extract local name
+            local_name = spec.entity.split("#")[-1].split("/")[-1]
+            lines.append(f"  {self._colour(local_name, 'bold')}")
+
+            # Show current state if available
+            if entity_info and i < len(entity_info):
+                info = entity_info[i]
+                if not info.found:
+                    lines.append(f"    {self._colour('⚠ Entity not found in graph', 'yellow')}")
+                else:
+                    if info.was_already_deprecated:
+                        lines.append(f"    {self._colour('Already deprecated', 'yellow')}")
+                    if info.current_labels:
+                        lines.append(f"    rdfs:label: \"{info.current_labels[0]}\"")
+                    if info.reference_count > 0:
+                        lines.append(
+                            f"    {self._colour(f'Referenced {info.reference_count} times', 'dim')}"
+                        )
+
+            # Show what will be added
+            lines.append("    Will add:")
+            lines.append(f"      owl:deprecated {self._colour('true', 'green')}")
+
+            if spec.replaced_by:
+                repl_local = spec.replaced_by.split("#")[-1].split("/")[-1]
+                lines.append(f"      dcterms:isReplacedBy {self._colour(repl_local, 'cyan')}")
+
+            if spec.message:
+                msg_preview = spec.message[:50] + "..." if len(spec.message) > 50 else spec.message
+                lines.append(f"      rdfs:comment \"DEPRECATED: {msg_preview}\"")
+
+            lines.append("")
+
+        # Summary
+        lines.append(self._colour("Summary:", "bold"))
+        lines.append(f"  - {len(specs)} entities will be marked deprecated")
+        with_replacement = len([s for s in specs if s.replaced_by])
+        lines.append(f"  - {with_replacement} with replacement")
+        lines.append(f"  - {len(specs) - with_replacement} without replacement")
+        lines.append("")
+        lines.append(
+            self._colour(
+                "Note: Deprecation marks entities but does not rename or migrate.",
+                "dim",
+            )
+        )
+        lines.append(
+            self._colour(
+                "      Use 'refactor rename' to actually migrate references.",
+                "dim",
+            )
+        )
+        lines.append("")
+        lines.append(self._colour("Run without --dry-run to apply changes.", "dim"))
+
+        return "\n".join(lines)
+
+    def format_deprecation_result(self, result: DeprecationResult) -> str:
+        """Format the result of a deprecation operation.
+
+        Args:
+            result: Result from deprecation operation.
+
+        Returns:
+            Formatted result string.
+        """
+        if not result.success:
+            return self._colour(f"✗ Deprecation failed: {result.error}", "red")
+
+        lines = [
+            self._colour("Deprecation Complete", "green"),
+            "",
+            f"  Source triples: {result.source_triples:,}",
+            f"  Result triples: {result.result_triples:,}",
+            "",
+            self._colour("Changes:", "cyan"),
+            f"  - Entities deprecated: {result.stats.entities_deprecated}",
+            f"  - Triples added: {result.stats.triples_added}",
+        ]
+
+        if result.stats.entities_not_found > 0:
+            lines.append(
+                self._colour(
+                    f"  ⚠ Entities not found: {result.stats.entities_not_found}",
+                    "yellow",
+                )
+            )
+
+        if result.stats.entities_already_deprecated > 0:
+            lines.append(
+                f"  - Already deprecated: {result.stats.entities_already_deprecated}"
+            )
+
+        # Show details of deprecated entities
+        if result.entity_info:
+            lines.append("")
+            lines.append("Details:")
+            for info in result.entity_info:
+                local_name = info.uri.split("#")[-1].split("/")[-1]
+                if not info.found:
+                    lines.append(f"  {self._colour('⚠', 'yellow')} {local_name} - not found")
+                elif info.was_already_deprecated and info.triples_added == 0:
+                    lines.append(f"  ○ {local_name} - already deprecated, no changes")
+                else:
+                    lines.append(f"  {self._colour('✓', 'green')} {local_name}")
+                    if info.replaced_by:
+                        repl_local = info.replaced_by.split("#")[-1].split("/")[-1]
+                        lines.append(f"      → replaced by {repl_local}")
+
+        return "\n".join(lines)