rdf-construct 0.3.0__py3-none-any.whl

rdf_construct/core/profile.py

@@ -0,0 +1,157 @@
+"""Profile and configuration management for RDF ordering."""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .predicate_order import PredicateOrderConfig
+
+
+class OrderingProfile:
+    """Represents an ordering profile from a YAML configuration.
+
+    A profile defines how to organize and order RDF subjects, typically
+    with multiple sections (classes, properties, individuals) each having
+    their own selection and sorting rules.
+
+    Attributes:
+        name: Profile identifier
+        description: Human-readable description
+        sections: List of section configurations
+        predicate_order: Optional predicate ordering configuration
+    """
+
+    def __init__(self, name: str, config: dict[str, Any]):
+        """Initialize a profile from configuration.
+
+        Args:
+            name: Profile identifier
+            config: Profile configuration dictionary from YAML
+        """
+        self.name = name
+        self.description = config.get("description", "")
+        self.sections = config.get("sections", [])
+        self.predicate_order = PredicateOrderConfig.from_dict(
+            config.get("predicate_order")
+        )
+
+    def __repr__(self) -> str:
+        return f"OrderingProfile(name={self.name!r}, sections={len(self.sections)})"
+
+
+class OrderingConfig:
+    """Configuration for RDF ordering operations.
+
+    Loads and manages YAML-based ordering specifications with support
+    for multiple profiles, default settings, selectors, and shared
+    configuration via YAML anchors.
+
+    Attributes:
+        defaults: Default settings applied across profiles
+        selectors: Named selector definitions
+        prefix_order: Preferred order for namespace prefixes
+        profiles: Dictionary of available ordering profiles
+        predicate_order: Default predicate ordering (can be overridden per profile)
+    """
+
+    def __init__(self, yaml_path: Path | str):
+        """Load ordering configuration from a YAML file.
+
+        Args:
+            yaml_path: Path to YAML configuration file
+        """
+        yaml_path = Path(yaml_path)
+        self.config = yaml.safe_load(yaml_path.read_text(encoding="utf-8"))
+
+        self.defaults = self.config.get("defaults", {}) or {}
+        self.selectors = self.config.get("selectors", {}) or {}
+        self.prefix_order = self.config.get("prefix_order", []) or []
+
+        # Load default predicate ordering (can be overridden per profile)
+        self.predicate_order = PredicateOrderConfig.from_dict(
+            self.config.get("predicate_order")
+        )
+
+        # Load profiles
+        self.profiles = {}
+        for prof_name, prof_config in (self.config.get("profiles", {}) or {}).items():
+            self.profiles[prof_name] = OrderingProfile(prof_name, prof_config)
+
+    def get_profile(self, name: str) -> OrderingProfile:
+        """Get a profile by name.
+
+        Args:
+            name: Profile identifier
+
+        Returns:
+            OrderingProfile instance
+
+        Raises:
+            KeyError: If profile name not found
+        """
+        if name not in self.profiles:
+            raise KeyError(
+                f"Profile '{name}' not found. Available profiles: "
+                f"{', '.join(self.profiles.keys())}"
+            )
+        return self.profiles[name]
+
+    def get_predicate_order(self, profile_name: str) -> PredicateOrderConfig | None:
+        """Get the effective predicate ordering for a profile.
+
+        Profile-level predicate_order takes precedence over config-level.
+
+        Args:
+            profile_name: Profile identifier
+
+        Returns:
+            PredicateOrderConfig or None if no ordering configured
+        """
+        profile = self.get_profile(profile_name)
+
+        # Profile-level overrides config-level
+        if profile.predicate_order.classes.first or profile.predicate_order.classes.last:
+            return profile.predicate_order
+        if profile.predicate_order.properties.first or profile.predicate_order.properties.last:
+            return profile.predicate_order
+        if profile.predicate_order.individuals.first or profile.predicate_order.individuals.last:
+            return profile.predicate_order
+        if profile.predicate_order.default.first or profile.predicate_order.default.last:
+            return profile.predicate_order
+
+        # Fall back to config-level
+        if self.predicate_order.classes.first or self.predicate_order.classes.last:
+            return self.predicate_order
+        if self.predicate_order.properties.first or self.predicate_order.properties.last:
+            return self.predicate_order
+        if self.predicate_order.individuals.first or self.predicate_order.individuals.last:
+            return self.predicate_order
+        if self.predicate_order.default.first or self.predicate_order.default.last:
+            return self.predicate_order
+
+        return None
+
+    def list_profiles(self) -> list[str]:
+        """Get list of available profile names.
+
+        Returns:
+            List of profile identifier strings
+        """
+        return list(self.profiles.keys())
+
+    def __repr__(self) -> str:
+        return f"OrderingConfig(profiles={list(self.profiles.keys())})"
+
+
+def load_yaml(path: Path | str) -> dict[str, Any]:
+    """Load YAML file with UTF-8 encoding.
+
+    Args:
+        path: Path to YAML file
+
+    Returns:
+        Parsed YAML content as dictionary
+    """
+    path = Path(path)
+    return yaml.safe_load(path.read_text(encoding="utf-8"))

rdf_construct/core/selector.py

@@ -0,0 +1,64 @@
+"""Subject selection logic for RDF graphs."""
+
+from rdflib import Graph, RDF, RDFS
+from rdflib.namespace import OWL
+
+
+def select_subjects(
+        graph: Graph, selector_key: str, selectors: dict[str, str]
+) -> set:
+    """Select subjects from a graph based on selector criteria.
+
+    Supports several selector shorthands:
+    - classes: owl:Class and rdfs:Class entities
+    - obj_props: owl:ObjectProperty entities
+    - data_props: owl:DatatypeProperty entities
+    - ann_props: owl:AnnotationProperty entities
+    - individuals: All subjects that aren't classes or properties
+
+    Args:
+        graph: RDF graph to select from
+        selector_key: Key identifying the selection type
+        selectors: Dictionary of selector definitions
+
+    Returns:
+        Set of URIRefs matching the selection criteria
+    """
+    sel = selectors.get(selector_key, "").strip()
+    subjects: set = set()
+
+    # Classes - check both owl:Class and rdfs:Class
+    if sel in ("owl:Class", "rdf:type owl:Class") or selector_key == "classes":
+        subjects = {s for s in graph.subjects(RDF.type, OWL.Class)}
+        subjects |= {s for s in graph.subjects(RDF.type, RDFS.Class)}
+
+    # Object properties
+    elif sel in ("owl:ObjectProperty",) or selector_key == "obj_props":
+        subjects = {s for s in graph.subjects(RDF.type, OWL.ObjectProperty)}
+
+    # Datatype properties
+    elif sel in ("owl:DatatypeProperty",) or selector_key == "data_props":
+        subjects = {s for s in graph.subjects(RDF.type, OWL.DatatypeProperty)}
+
+    # Annotation properties
+    elif sel in ("owl:AnnotationProperty",) or selector_key == "ann_props":
+        subjects = {s for s in graph.subjects(RDF.type, OWL.AnnotationProperty)}
+
+    # Individuals - everything that's not a class or property
+    elif selector_key == "individuals" or sel.startswith("FILTER"):
+        classes = {s for s in graph.subjects(RDF.type, OWL.Class)}
+        classes |= {s for s in graph.subjects(RDF.type, RDFS.Class)}
+
+        properties = set()
+        for prop_type in (
+                RDF.Property,
+                OWL.ObjectProperty,
+                OWL.DatatypeProperty,
+                OWL.AnnotationProperty,
+        ):
+            properties |= {s for s in graph.subjects(RDF.type, prop_type)}
+
+        all_subjects = {s for (s, _, _) in graph}
+        subjects = all_subjects - classes - properties
+
+    return subjects

rdf_construct/core/serialiser.py

@@ -0,0 +1,232 @@
+"""Custom RDF serialisers that preserve semantic ordering.
+
+RDFlib's built-in serialisers always sort subjects alphabetically,
+which defeats semantic ordering. These custom serialisers respect
+the exact subject order provided.
+"""
+
+from pathlib import Path
+
+from rdflib import Graph, URIRef, Literal, RDF
+from rdflib.namespace import RDFS, OWL, XSD
+
+try:
+    from .predicate_order import (
+        PredicateOrderConfig,
+        PredicateOrderSpec,
+        classify_subject,
+        order_predicates,
+    )
+except ImportError:
+    from predicate_order import (
+        PredicateOrderConfig,
+        PredicateOrderSpec,
+        classify_subject,
+        order_predicates,
+    )
+
+
+def format_term(graph: Graph, term, use_prefixes: bool = True) -> str:
+    """Format an RDF term as a Turtle string.
+
+    Args:
+        graph: RDF graph containing namespace bindings
+        term: RDF term to format (URIRef, Literal, or other)
+        use_prefixes: Whether to use prefix notation for URIs
+
+    Returns:
+        Turtle-formatted string representation of the term
+    """
+    if isinstance(term, URIRef):
+        if use_prefixes:
+            try:
+                qname = graph.namespace_manager.normalizeUri(term)
+                return qname
+            except Exception:
+                return f"<{term}>"
+        return f"<{term}>"
+
+    elif isinstance(term, Literal):
+        value = str(term)
+        # Escape special characters
+        value = (
+            value.replace("\\", "\\\\")
+            .replace('"', '\\"')
+            .replace("\n", "\\n")
+            .replace("\r", "\\r")
+        )
+
+        if term.datatype:
+            dt = format_term(graph, term.datatype, use_prefixes=True)
+            return f'"{value}"^^{dt}'
+        elif term.language:
+            return f'"{value}"@{term.language}'
+        else:
+            return f'"{value}"'
+
+    else:
+        return str(term)
+
+
+def serialise_turtle(
+    graph: Graph,
+    subjects_ordered: list,
+    output_path: Path | str,
+    predicate_order: PredicateOrderConfig | None = None,
+) -> None:
+    """Serialise RDF graph to Turtle format with preserved subject ordering.
+
+    This custom serialiser respects the exact order of subjects provided,
+    unlike rdflib's built-in serialisers which always sort alphabetically.
+
+    Formatting features:
+    - Prefixes sorted alphabetically at top
+    - Subjects in specified order
+    - rdf:type predicate listed first for each subject
+    - Predicates ordered according to predicate_order config (or alphabetically)
+    - Objects sorted alphabetically within each predicate
+    - Proper indentation and punctuation
+
+    Args:
+        graph: RDF graph to serialise
+        subjects_ordered: List of subjects in desired output order
+        output_path: Path to write Turtle file to
+        predicate_order: Optional predicate ordering configuration
+    """
+    lines = []
+
+    # Write prefixes
+    prefixes = sorted(graph.namespace_manager.namespaces(), key=lambda x: x[0])
+    for prefix, namespace in prefixes:
+        if prefix:  # Skip the default namespace
+            lines.append(f"PREFIX {prefix}: <{namespace}>")
+    lines.append("")  # Blank line after prefixes
+
+    # Write subjects in order
+    for subject in subjects_ordered:
+        preds = list(graph.predicate_objects(subject))
+        if not preds:
+            continue
+
+        # Write subject
+        subj_str = format_term(graph, subject)
+        lines.append(f"{subj_str}")
+
+        # Group predicates
+        pred_dict: dict[URIRef, list] = {}
+        for p, o in preds:
+            if p not in pred_dict:
+                pred_dict[p] = []
+            pred_dict[p].append(o)
+
+        # Order predicates
+        sorted_preds = _order_subject_predicates(
+            graph, subject, pred_dict, predicate_order
+        )
+
+        # Write predicate-object pairs
+        for i, (pred, objects) in enumerate(sorted_preds):
+            # Use 'a' shorthand for rdf:type
+            pred_str = "a" if pred == RDF.type else format_term(graph, pred)
+            objects_sorted = sorted(objects, key=lambda x: format_term(graph, x))
+
+            if len(objects_sorted) == 1:
+                obj_str = format_term(graph, objects_sorted[0])
+                if i == len(sorted_preds) - 1:
+                    lines.append(f"    {pred_str} {obj_str} .")
+                else:
+                    lines.append(f"    {pred_str} {obj_str} ;")
+            else:
+                # Multiple objects for same predicate
+                lines.append(f"    {pred_str}")
+                for j, obj in enumerate(objects_sorted):
+                    obj_str = format_term(graph, obj)
+                    if j == len(objects_sorted) - 1:
+                        if i == len(sorted_preds) - 1:
+                            lines.append(f"        {obj_str} .")
+                        else:
+                            lines.append(f"        {obj_str} ;")
+                    else:
+                        lines.append(f"        {obj_str} ,")
+
+        lines.append("")  # Blank line after each subject
+
+    # Write to file
+    output_path = Path(output_path)
+    output_path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def _order_subject_predicates(
+    graph: Graph,
+    subject: URIRef,
+    pred_dict: dict[URIRef, list],
+    predicate_order: PredicateOrderConfig | None,
+) -> list[tuple[URIRef, list]]:
+    """Order predicates for a subject according to configuration.
+
+    Args:
+        graph: RDF graph
+        subject: The subject being serialised
+        pred_dict: Dictionary of predicate -> objects
+        predicate_order: Predicate ordering configuration
+
+    Returns:
+        List of (predicate, objects) tuples in desired order
+    """
+    sorted_preds = []
+
+    # rdf:type always first
+    if RDF.type in pred_dict:
+        sorted_preds.append((RDF.type, pred_dict[RDF.type]))
+
+    # Get remaining predicates (excluding rdf:type)
+    remaining = [p for p in pred_dict.keys() if p != RDF.type]
+
+    if predicate_order:
+        # Use configured ordering
+        subject_type = classify_subject(graph, subject)
+        spec = predicate_order.get_spec_for_type(subject_type)
+
+        ordered = order_predicates(
+            graph,
+            remaining,
+            spec,
+            lambda x: format_term(graph, x),
+        )
+    else:
+        # Default: alphabetical ordering
+        ordered = sorted(remaining, key=lambda x: format_term(graph, x))
+
+    # Add ordered predicates
+    for pred in ordered:
+        sorted_preds.append((pred, pred_dict[pred]))
+
+    return sorted_preds
+
+
+def build_section_graph(base: Graph, subjects_ordered: list) -> Graph:
+    """Build a new graph containing only the specified subjects and their triples.
+
+    Creates a filtered view of the base graph that includes all triples
+    where the subject is in the provided list. Preserves all namespace
+    bindings from the base graph.
+
+    Args:
+        base: Source RDF graph to filter
+        subjects_ordered: List of subjects to include
+
+    Returns:
+        New graph containing only triples for the specified subjects
+    """
+    sg = Graph()
+
+    # Copy namespace bindings
+    for pfx, uri in base.namespace_manager.namespaces():
+        sg.namespace_manager.bind(pfx, uri, override=True, replace=True)
+
+    # Copy triples for each subject
+    for s in subjects_ordered:
+        for p, o in base.predicate_objects(s):
+            sg.add((s, p, o))
+
+    return sg

rdf_construct/core/utils.py

@@ -0,0 +1,89 @@
+"""Utilities for handling prefixes, CURIEs, and namespace operations."""
+
+from typing import Optional
+
+from rdflib import Graph, Namespace, URIRef
+
+
+def extract_prefix_map(graph: Graph) -> dict[str, str]:
+    """Extract all namespace prefixes from a graph.
+
+    Args:
+        graph: RDF graph to extract prefixes from
+
+    Returns:
+        Dictionary mapping prefix strings to namespace URIs
+    """
+    return {pfx: str(uri) for pfx, uri in graph.namespace_manager.namespaces()}
+
+
+def expand_curie(graph: Graph, curie_or_iri: str) -> Optional[URIRef]:
+    """Expand a CURIE to a full URIRef using the graph's namespace bindings.
+
+    Handles multiple input formats:
+    - CURIE format: 'ies:Element' -> http://example.org/ies#Element
+    - Angle brackets: '<http://...>' -> http://...
+    - Full IRI: 'http://...' -> http://...
+
+    Args:
+        graph: RDF graph containing namespace bindings
+        curie_or_iri: CURIE, bracketed IRI, or full IRI string
+
+    Returns:
+        Expanded URIRef or None if expansion fails
+    """
+    s = curie_or_iri.strip()
+    if not s:
+        return None
+
+    # Handle angle-bracketed IRIs
+    if s.startswith("<") and s.endswith(">"):
+        return URIRef(s[1:-1])
+
+    # Handle full IRIs
+    if "://" in s:
+        return URIRef(s)
+
+    # Handle CURIEs
+    if ":" in s:
+        pfx, local = s.split(":", 1)
+        for p, uri in graph.namespace_manager.namespaces():
+            if p == pfx:
+                return URIRef(str(uri) + local)
+
+    return None
+
+
+def rebind_prefixes(
+        graph: Graph, ordered_prefixes: list[str], prefix_map: dict[str, str]
+) -> None:
+    """Rebind prefixes in a graph according to a specified order.
+
+    This ensures deterministic prefix ordering in serialized output.
+
+    Args:
+        graph: RDF graph to rebind prefixes in
+        ordered_prefixes: List of prefix strings in desired order
+        prefix_map: Dictionary mapping prefixes to namespace URIs
+    """
+    nm = graph.namespace_manager
+    for pfx in ordered_prefixes:
+        uri = prefix_map.get(pfx)
+        if uri:
+            nm.bind(pfx, URIRef(uri), override=True, replace=True)
+
+
+def qname_sort_key(graph: Graph, term) -> str:
+    """Generate a sortable string key for an RDF term using its QName.
+
+    Args:
+        graph: RDF graph containing namespace bindings
+        term: RDF term to generate key for
+
+    Returns:
+        Normalized URI string suitable for alphabetical sorting
+    """
+    try:
+        return graph.namespace_manager.normalizeUri(term)
+    except Exception:
+        return str(term)

rdf_construct/cq/__init__.py

@@ -0,0 +1,77 @@
+"""Competency Question (CQ) testing module.
+
+Validates whether an ontology can answer competency questions expressed
+as SPARQL queries with expected results.
+
+Example usage:
+
+    from rdf_construct.cq import run_tests
+
+    results = run_tests(
+        ontology_path=Path("ontology.ttl"),
+        test_suite_path=Path("cq-tests.yml"),
+    )
+
+    print(f"Passed: {results.passed_count}/{results.total_count}")
+
+Or with more control:
+
+    from rdf_construct.cq import load_test_suite, CQTestRunner
+    from rdflib import Graph
+
+    ontology = Graph()
+    ontology.parse("ontology.ttl", format="turtle")
+
+    suite = load_test_suite(Path("cq-tests.yml"))
+    suite = suite.filter_by_tags(include_tags={"core"})
+
+    runner = CQTestRunner(fail_fast=True)
+    results = runner.run(ontology, suite)
+"""
+
+from rdf_construct.cq.loader import CQTest, CQTestSuite, load_test_suite
+from rdf_construct.cq.runner import (
+    CQTestRunner,
+    CQTestResult,
+    CQTestResults,
+    CQStatus,
+    run_tests,
+)
+from rdf_construct.cq.expectations import (
+    Expectation,
+    BooleanExpectation,
+    HasResultsExpectation,
+    NoResultsExpectation,
+    CountExpectation,
+    ValuesExpectation,
+    ContainsExpectation,
+    parse_expectation,
+)
+from rdf_construct.cq.formatters import format_results, format_text, format_json, format_junit
+
+__all__ = [
+    # Loader
+    "CQTest",
+    "CQTestSuite",
+    "load_test_suite",
+    # Runner
+    "CQTestRunner",
+    "CQTestResult",
+    "CQTestResults",
+    "CQStatus",
+    "run_tests",
+    # Expectations
+    "Expectation",
+    "BooleanExpectation",
+    "HasResultsExpectation",
+    "NoResultsExpectation",
+    "CountExpectation",
+    "ValuesExpectation",
+    "ContainsExpectation",
+    "parse_expectation",
+    # Formatters
+    "format_results",
+    "format_text",
+    "format_json",
+    "format_junit",
+]