rdf-construct 0.2.0__py3-none-any.whl

rdf_construct/core/__init__.py

@@ -0,0 +1,33 @@
+"""Core RDF ordering and serialization functionality."""
+
+from .ordering import sort_subjects, topo_sort_subset, sort_with_roots
+from .profile import OrderingConfig, OrderingProfile, load_yaml
+from .selector import select_subjects
+from .serialiser import serialise_turtle, build_section_graph
+from .utils import (
+    expand_curie,
+    extract_prefix_map,
+    qname_sort_key,
+    rebind_prefixes,
+)
+
+__all__ = [
+    # Ordering
+    "sort_subjects",
+    "topo_sort_subset",
+    "sort_with_roots",
+    # Profile
+    "OrderingConfig",
+    "OrderingProfile",
+    "load_yaml",
+    # Selector
+    "select_subjects",
+    # Serialiser
+    "serialise_turtle",
+    "build_section_graph",
+    # Utils
+    "expand_curie",
+    "extract_prefix_map",
+    "qname_sort_key",
+    "rebind_prefixes",
+]

rdf_construct/core/config.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Configuration and YAML handling for rdf-construct.
+
+This module handles loading ordering profiles from YAML files and managing
+RDF namespace prefixes and CURIE expansion.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import yaml
+from rdflib import Graph, Namespace, URIRef
+
+
+@dataclass
+class SectionConfig:
+    """Configuration for a single section in an ordering profile."""
+
+    name: str
+    select: str
+    sort: str = "qname_alpha"
+    roots: Optional[List[str]] = None
+    cluster: Optional[str] = None
+    within_level: Optional[str] = None
+    group_by: Optional[str] = None
+    group_order: Optional[str] = None
+    explicit_group_sequence: Optional[List[str]] = None
+    within_group_tie: Optional[str] = None
+    anchors: Optional[List[str]] = None
+    after_anchors: Optional[str] = None
+
+
+@dataclass
+class ProfileConfig:
+    """Configuration for an ordering profile."""
+
+    name: str
+    description: str = ""
+    sections: List[SectionConfig] = field(default_factory=list)
+
+
+@dataclass
+class OrderingSpec:
+    """Complete ordering specification from YAML."""
+
+    defaults: Dict = field(default_factory=dict)
+    selectors: Dict[str, str] = field(default_factory=dict)
+    prefix_order: List[str] = field(default_factory=list)
+    profiles: Dict[str, ProfileConfig] = field(default_factory=dict)
+
+
+def load_yaml(path: Path) -> dict:
+    """Load and parse a YAML file.
+
+    Args:
+        path: Path to the YAML file
+
+    Returns:
+        Parsed YAML content as dictionary
+
+    Raises:
+        FileNotFoundError: If the file doesn't exist
+        yaml.YAMLError: If the file is not valid YAML
+    """
+    return yaml.safe_load(path.read_text(encoding="utf-8"))
+
+
+def load_ordering_spec(path: Path) -> OrderingSpec:
+    """Load and validate an ordering specification from YAML.
+
+    Args:
+        path: Path to the YAML ordering specification
+
+    Returns:
+        Validated OrderingSpec object
+    """
+    data = load_yaml(path)
+
+    # Parse profiles
+    profiles = {}
+    for prof_name, prof_data in data.get("profiles", {}).items():
+        sections = []
+        for sec in prof_data.get("sections", []):
+            if not isinstance(sec, dict) or not sec:
+                continue
+            sec_name, sec_cfg = next(iter(sec.items()))
+            sec_cfg = sec_cfg or {}
+
+            sections.append(
+                SectionConfig(
+                    name=sec_name,
+                    select=sec_cfg.get("select", sec_name),
+                    sort=sec_cfg.get("sort", "qname_alpha"),
+                    roots=sec_cfg.get("roots"),
+                    cluster=sec_cfg.get("cluster"),
+                    within_level=sec_cfg.get("within_level"),
+                    group_by=sec_cfg.get("group_by"),
+                    group_order=sec_cfg.get("group_order"),
+                    explicit_group_sequence=sec_cfg.get("explicit_group_sequence"),
+                    within_group_tie=sec_cfg.get("within_group_tie"),
+                    anchors=sec_cfg.get("anchors"),
+                    after_anchors=sec_cfg.get("after_anchors"),
+                )
+            )
+
+        profiles[prof_name] = ProfileConfig(
+            name=prof_name, description=prof_data.get("description", ""), sections=sections
+        )
+
+    return OrderingSpec(
+        defaults=data.get("defaults", {}),
+        selectors=data.get("selectors", {}),
+        prefix_order=data.get("prefix_order", []),
+        profiles=profiles,
+    )

rdf_construct/core/ordering.py

@@ -0,0 +1,219 @@
+"""Ordering and sorting logic for RDF subjects."""
+
+from typing import Optional
+
+from rdflib import Graph, URIRef, RDF, RDFS
+from rdflib.namespace import OWL
+
+from .utils import expand_curie, qname_sort_key
+
+
+def build_adjacency(
+        graph: Graph, nodes: set, edge_predicate: URIRef
+) -> tuple[dict[URIRef, set[URIRef]], dict[URIRef, int]]:
+    """Build adjacency list and indegree map for topological sorting.
+
+    Creates parent->children adjacency representation within the given node set.
+
+    Args:
+        graph: RDF graph containing the relationships
+        nodes: Set of nodes to build adjacency for
+        edge_predicate: Predicate defining parent-child relationship
+                       (typically rdfs:subClassOf or rdfs:subPropertyOf)
+
+    Returns:
+        Tuple of (adjacency dict, indegree dict) where:
+        - adjacency maps parent URIRef to set of child URIRefs
+        - indegree maps each URIRef to its incoming edge count
+    """
+    adj: dict[URIRef, set[URIRef]] = {n: set() for n in nodes}
+    indeg: dict[URIRef, int] = {n: 0 for n in nodes}
+
+    for n in nodes:
+        for parent in graph.objects(n, edge_predicate):
+            if parent in nodes:
+                adj[parent].add(n)  # parent before child
+                indeg[n] += 1
+
+    return adj, indeg
+
+
+def topo_sort_subset(graph: Graph, nodes: set, edge_predicate: URIRef) -> list:
+    """Topologically sort a subset of nodes using Kahn's algorithm.
+
+    Sorts nodes so parents appear before children. Uses alphabetical
+    tie-breaking for deterministic output. Handles cycles by appending
+    remaining nodes alphabetically.
+
+    Args:
+        graph: RDF graph containing the relationships
+        nodes: Set of nodes to sort
+        edge_predicate: Predicate defining parent-child relationship
+
+    Returns:
+        List of URIRefs in topological order
+    """
+    if not nodes:
+        return []
+
+    adj, indeg = build_adjacency(graph, nodes, edge_predicate)
+
+    # Start with nodes that have no incoming edges
+    zero = [n for n, d in indeg.items() if d == 0]
+    zero.sort(key=lambda t: qname_sort_key(graph, t))
+
+    out: list = []
+
+    while zero:
+        u = zero.pop(0)
+        out.append(u)
+
+        # Process children in alphabetical order
+        for v in sorted(adj[u], key=lambda t: qname_sort_key(graph, t)):
+            indeg[v] -= 1
+            if indeg[v] == 0:
+                zero.append(v)
+                zero.sort(key=lambda t: qname_sort_key(graph, t))
+
+    # Handle any remaining nodes (cycles or disconnected components)
+    if len(out) < len(nodes):
+        remaining = [n for n in nodes if n not in out]
+        remaining.sort(key=lambda t: qname_sort_key(graph, t))
+        out.extend(remaining)
+
+    return out
+
+
+def descendants_of(
+        graph: Graph, root: URIRef, nodes: set, edge_predicate: URIRef
+) -> set:
+    """Find all descendants of a root node within a set of nodes.
+
+    Traverses the graph following child edges (subClassOf/subPropertyOf)
+    to find all nodes reachable from the root.
+
+    Args:
+        graph: RDF graph containing the relationships
+        root: Root node to start traversal from
+        nodes: Set of nodes to consider (search space)
+        edge_predicate: Predicate defining parent-child relationship
+
+    Returns:
+        Set of URIRefs reachable from root (including root itself if in nodes)
+    """
+    # Build parent->children map
+    children: dict[URIRef, set[URIRef]] = {n: set() for n in nodes}
+    for n in nodes:
+        for parent in graph.objects(n, edge_predicate):
+            if parent in nodes:
+                children[parent].add(n)
+
+    reachable = set()
+    stack = [root] if root in nodes else []
+
+    while stack:
+        u = stack.pop()
+        for v in children.get(u, ()):
+            if v not in reachable:
+                reachable.add(v)
+                stack.append(v)
+
+    # Include root itself if it's in the node set
+    if root in nodes:
+        reachable.add(root)
+
+    return reachable
+
+
+def sort_with_roots(
+        graph: Graph, subjects: set, mode: str, roots_cfg: Optional[list[str]]
+) -> list:
+    """Sort subjects with explicit root ordering.
+
+    When roots are provided, emits each root's branch contiguously
+    (topologically within each branch), then emits remaining subjects
+    topologically. This creates a deterministic ordering that respects
+    both hierarchy and explicit sequencing preferences.
+
+    Args:
+        graph: RDF graph containing the relationships
+        subjects: Set of subjects to sort
+        mode: Sorting mode (should be 'topological' or 'topological_then_alpha')
+        roots_cfg: List of root CURIEs/IRIs defining branch order
+
+    Returns:
+        List of URIRefs in the specified order
+    """
+    mode = (mode or "qname_alpha").lower()
+
+    # Determine appropriate edge predicate based on subject types
+    looks_like_props = any(
+        (s, RDF.type, OWL.ObjectProperty) in graph
+        or (s, RDF.type, OWL.DatatypeProperty) in graph
+        for s in subjects
+    )
+    edge = RDFS.subPropertyOf if looks_like_props else RDFS.subClassOf
+
+    # Fall back to simple topological if no roots or mode doesn't support them
+    if mode not in ("topological", "topological_then_alpha") or not roots_cfg:
+        if mode in ("topological", "topological_then_alpha"):
+            return topo_sort_subset(graph, subjects, edge)
+        return sorted(subjects, key=lambda t: qname_sort_key(graph, t))
+
+    # Expand roots to IRIs
+    root_iris: list[URIRef] = []
+    for r in roots_cfg:
+        iri = expand_curie(graph, r)
+        if iri is not None:
+            root_iris.append(iri)
+
+    remaining: set = set(subjects)
+    ordered: list = []
+
+    # Emit branches in the order of roots list
+    for root in root_iris:
+        branch_nodes = descendants_of(graph, root, remaining, edge)
+        if not branch_nodes:
+            continue
+
+        branch_order = topo_sort_subset(graph, branch_nodes, edge)
+        for n in branch_order:
+            if n in remaining:
+                ordered.append(n)
+                remaining.remove(n)
+
+    # Emit whatever is left (disconnected components)
+    tail_order = topo_sort_subset(graph, remaining, edge)
+    ordered.extend(tail_order)
+
+    return ordered
+
+
+def sort_subjects(
+        graph: Graph, subjects: set, sort_mode: str, roots_cfg: Optional[list[str]] = None
+) -> list:
+    """Sort subjects according to the specified mode.
+
+    Supported modes:
+    - 'alpha' or 'qname_alpha': Alphabetical by QName
+    - 'topological' or 'topological_then_alpha': Topological with optional roots
+
+    Args:
+        graph: RDF graph containing the relationships
+        subjects: Set of subjects to sort
+        sort_mode: Sorting mode identifier
+        roots_cfg: Optional list of root CURIEs for topological sorting
+
+    Returns:
+        List of URIRefs in the specified order
+    """
+    mode = (sort_mode or "qname_alpha").lower()
+
+    if mode in ("alpha", "qname_alpha"):
+        return sorted(subjects, key=lambda t: qname_sort_key(graph, t))
+
+    if mode in ("topological", "topological_then_alpha"):
+        return sort_with_roots(graph, subjects, mode, roots_cfg)
+
+    # Fallback to alphabetical
+    return sorted(subjects, key=lambda t: qname_sort_key(graph, t))

rdf_construct/core/predicate_order.py

@@ -0,0 +1,212 @@
+"""Predicate ordering configuration and logic for RDF serialisation.
+
+Controls the order in which predicates (properties) appear when serialising
+RDF subjects. Supports different orderings for different subject types
+(classes, properties, individuals).
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from rdflib import Graph, RDF, RDFS, URIRef
+from rdflib.namespace import OWL
+
+
+@dataclass
+class PredicateOrderSpec:
+    """Ordering specification for predicates of a particular subject type.
+
+    Attributes:
+        first: Predicates to appear first, in order (after rdf:type)
+        last: Predicates to appear last, in order
+    """
+
+    first: list[str] = field(default_factory=list)
+    last: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "PredicateOrderSpec":
+        """Create from dictionary configuration.
+
+        Args:
+            data: Dictionary with 'first' and/or 'last' keys
+
+        Returns:
+            PredicateOrderSpec instance
+        """
+        if not data:
+            return cls()
+        return cls(
+            first=data.get("first", []) or [],
+            last=data.get("last", []) or [],
+        )
+
+
+@dataclass
+class PredicateOrderConfig:
+    """Configuration for predicate ordering across subject types.
+
+    Defines how predicates should be ordered for different types of
+    RDF subjects (classes, properties, individuals).
+
+    Attributes:
+        classes: Ordering for owl:Class and rdfs:Class subjects
+        properties: Ordering for property subjects (ObjectProperty, etc.)
+        individuals: Ordering for individual/instance subjects
+        default: Fallback ordering for unmatched subject types
+    """
+
+    classes: PredicateOrderSpec = field(default_factory=PredicateOrderSpec)
+    properties: PredicateOrderSpec = field(default_factory=PredicateOrderSpec)
+    individuals: PredicateOrderSpec = field(default_factory=PredicateOrderSpec)
+    default: PredicateOrderSpec = field(default_factory=PredicateOrderSpec)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "PredicateOrderConfig":
+        """Create from dictionary configuration.
+
+        Args:
+            data: Dictionary with subject type keys (classes, properties, etc.)
+
+        Returns:
+            PredicateOrderConfig instance
+        """
+        if not data:
+            return cls()
+        return cls(
+            classes=PredicateOrderSpec.from_dict(data.get("classes")),
+            properties=PredicateOrderSpec.from_dict(data.get("properties")),
+            individuals=PredicateOrderSpec.from_dict(data.get("individuals")),
+            default=PredicateOrderSpec.from_dict(data.get("default")),
+        )
+
+    def get_spec_for_type(self, subject_type: str) -> PredicateOrderSpec:
+        """Get the predicate ordering spec for a subject type.
+
+        Args:
+            subject_type: One of 'class', 'property', 'individual', or other
+
+        Returns:
+            Appropriate PredicateOrderSpec for the subject type
+        """
+        if subject_type == "class":
+            return self.classes if self.classes.first or self.classes.last else self.default
+        elif subject_type == "property":
+            return self.properties if self.properties.first or self.properties.last else self.default
+        elif subject_type == "individual":
+            return self.individuals if self.individuals.first or self.individuals.last else self.default
+        else:
+            return self.default
+
+
+def classify_subject(graph: Graph, subject: URIRef) -> str:
+    """Determine the type category of an RDF subject.
+
+    Classifies subjects into one of: 'class', 'property', 'individual'.
+
+    Args:
+        graph: RDF graph containing the subject
+        subject: The subject URI to classify
+
+    Returns:
+        Subject type: 'class', 'property', or 'individual'
+    """
+    types = set(graph.objects(subject, RDF.type))
+
+    # Check if it's a class
+    if OWL.Class in types or RDFS.Class in types:
+        return "class"
+
+    # Check if it's a property
+    property_types = {
+        OWL.ObjectProperty,
+        OWL.DatatypeProperty,
+        OWL.AnnotationProperty,
+        RDF.Property,
+    }
+    if types & property_types:
+        return "property"
+
+    # Default to individual
+    return "individual"
+
+
+def expand_curie(graph: Graph, curie: str) -> URIRef | None:
+    """Expand a CURIE (prefix:local) to a full URI.
+
+    Args:
+        graph: RDF graph with namespace bindings
+        curie: CURIE string like 'rdfs:label'
+
+    Returns:
+        Expanded URIRef, or None if prefix not found
+    """
+    if ":" not in curie:
+        return None
+
+    prefix, local = curie.split(":", 1)
+    for bound_prefix, namespace in graph.namespace_manager.namespaces():
+        if bound_prefix == prefix:
+            return URIRef(str(namespace) + local)
+    return None
+
+
+def order_predicates(
+    graph: Graph,
+    predicates: list[URIRef],
+    spec: PredicateOrderSpec,
+    format_fn: callable,
+) -> list[URIRef]:
+    """Order predicates according to a specification.
+
+    Ordering logic:
+    1. rdf:type always first (handled by caller)
+    2. 'first' predicates in specified order
+    3. Remaining predicates sorted alphabetically by QName
+    4. 'last' predicates in specified order
+
+    Args:
+        graph: RDF graph with namespace bindings
+        predicates: List of predicate URIs to order
+        spec: Predicate ordering specification
+        format_fn: Function to format URIRef as string (for sorting)
+
+    Returns:
+        Ordered list of predicates
+    """
+    # Expand CURIEs to URIs
+    first_uris = [expand_curie(graph, c) for c in spec.first]
+    first_uris = [u for u in first_uris if u is not None]
+
+    last_uris = [expand_curie(graph, c) for c in spec.last]
+    last_uris = [u for u in last_uris if u is not None]
+
+    # Build sets for quick lookup
+    first_set = set(first_uris)
+    last_set = set(last_uris)
+    special_set = first_set | last_set | {RDF.type}
+
+    # Partition predicates
+    first_found = []
+    middle = []
+    last_found = []
+
+    # Collect 'first' predicates in specified order
+    for uri in first_uris:
+        if uri in predicates:
+            first_found.append(uri)
+
+    # Collect 'last' predicates in specified order
+    for uri in last_uris:
+        if uri in predicates:
+            last_found.append(uri)
+
+    # Collect middle predicates (everything else except rdf:type)
+    for pred in predicates:
+        if pred not in special_set:
+            middle.append(pred)
+
+    # Sort middle predicates alphabetically by QName
+    middle.sort(key=lambda x: format_fn(x))
+
+    return first_found + middle + last_found