rdf-construct 0.3.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

rdf_construct/describe/hierarchy.py

@@ -0,0 +1,232 @@
+"""Class hierarchy analysis for ontology description.
+
+Analyses class hierarchy structure including roots, depth, orphans, and cycles.
+"""
+
+from collections import defaultdict
+
+from rdflib import Graph, URIRef, RDF, RDFS
+from rdflib.namespace import OWL
+
+from rdf_construct.describe.models import HierarchyAnalysis
+
+
+# Classes that should not count as "real" superclasses for root detection
+TOP_CLASSES = {
+    OWL.Thing,
+    RDFS.Resource,
+    # Some ontologies use owl:Class as a type marker
+    OWL.Class,
+    RDFS.Class,
+}
+
+
+def analyse_hierarchy(graph: Graph, max_roots_display: int = 10) -> HierarchyAnalysis:
+    """Analyse the class hierarchy structure.
+
+    Args:
+        graph: RDF graph to analyse.
+        max_roots_display: Maximum number of root classes to list.
+
+    Returns:
+        HierarchyAnalysis with hierarchy metrics.
+    """
+    # Get all classes
+    all_classes = _get_all_classes(graph)
+
+    if not all_classes:
+        return HierarchyAnalysis()
+
+    # Build parent-child relationships
+    parents: dict[URIRef, set[URIRef]] = defaultdict(set)
+    children: dict[URIRef, set[URIRef]] = defaultdict(set)
+
+    for cls in all_classes:
+        for superclass in graph.objects(cls, RDFS.subClassOf):
+            if isinstance(superclass, URIRef) and superclass in all_classes:
+                parents[cls].add(superclass)
+                children[superclass].add(cls)
+
+    # Find root classes (no parent except top classes)
+    root_classes: list[str] = []
+    for cls in all_classes:
+        real_parents = parents[cls] - TOP_CLASSES
+        if not real_parents:
+            root_classes.append(_curie(graph, cls))
+
+    # Sort and limit for display
+    root_classes.sort()
+    display_roots = root_classes[:max_roots_display]
+    if len(root_classes) > max_roots_display:
+        display_roots.append(f"...and {len(root_classes) - max_roots_display} more")
+
+    # Find orphan classes (neither parent nor child of anything)
+    orphan_classes: list[str] = []
+    for cls in all_classes:
+        has_parent = bool(parents[cls] - TOP_CLASSES)
+        has_child = bool(children[cls])
+        if not has_parent and not has_child:
+            orphan_classes.append(_curie(graph, cls))
+
+    orphan_classes.sort()
+
+    # Calculate maximum depth
+    max_depth = _calculate_max_depth(all_classes, parents)
+
+    # Detect cycles
+    has_cycles, cycle_members = _detect_cycles(all_classes, parents)
+
+    return HierarchyAnalysis(
+        root_classes=display_roots,
+        max_depth=max_depth,
+        orphan_classes=orphan_classes,
+        has_cycles=has_cycles,
+        cycle_members=[_curie(graph, uri) for uri in cycle_members],
+    )
+
+
+def _get_all_classes(graph: Graph) -> set[URIRef]:
+    """Get all classes from the graph.
+
+    Args:
+        graph: RDF graph to query.
+
+    Returns:
+        Set of class URIRefs.
+    """
+    classes: set[URIRef] = set()
+
+    # owl:Class
+    for cls in graph.subjects(RDF.type, OWL.Class):
+        if isinstance(cls, URIRef):
+            classes.add(cls)
+
+    # rdfs:Class
+    for cls in graph.subjects(RDF.type, RDFS.Class):
+        if isinstance(cls, URIRef):
+            classes.add(cls)
+
+    return classes
+
+
+def _calculate_max_depth(
+    classes: set[URIRef],
+    parents: dict[URIRef, set[URIRef]],
+) -> int:
+    """Calculate the maximum depth of the class hierarchy.
+
+    Uses iterative deepening to handle potentially cyclic graphs.
+
+    Args:
+        classes: Set of all classes.
+        parents: Parent relationships.
+
+    Returns:
+        Maximum hierarchy depth (0 if no hierarchy).
+    """
+    if not classes:
+        return 0
+
+    # Calculate depth for each class using BFS from roots
+    depths: dict[URIRef, int] = {}
+
+    # Find roots
+    roots = {
+        cls for cls in classes
+        if not (parents[cls] - TOP_CLASSES)
+    }
+
+    # BFS to assign depths
+    current_level = roots
+    depth = 0
+
+    while current_level:
+        for cls in current_level:
+            if cls not in depths:
+                depths[cls] = depth
+
+        # Find children at next level
+        next_level: set[URIRef] = set()
+        for cls in current_level:
+            for child_cls in classes:
+                if cls in parents[child_cls] and child_cls not in depths:
+                    next_level.add(child_cls)
+
+        current_level = next_level
+        depth += 1
+
+        # Safety limit to prevent infinite loops
+        if depth > 1000:
+            break
+
+    return max(depths.values()) if depths else 0
+
+
+def _detect_cycles(
+    classes: set[URIRef],
+    parents: dict[URIRef, set[URIRef]],
+) -> tuple[bool, list[URIRef]]:
+    """Detect cycles in the class hierarchy.
+
+    Uses DFS-based cycle detection.
+
+    Args:
+        classes: Set of all classes.
+        parents: Parent relationships.
+
+    Returns:
+        Tuple of (has_cycles, list of cycle member URIs).
+    """
+    # Build reverse mapping for traversal
+    # Note: We traverse "up" via parents to detect cycles
+
+    visited: set[URIRef] = set()
+    rec_stack: set[URIRef] = set()
+    cycle_members: set[URIRef] = set()
+
+    def dfs(cls: URIRef) -> bool:
+        visited.add(cls)
+        rec_stack.add(cls)
+
+        for parent in parents[cls]:
+            if parent not in visited:
+                if dfs(parent):
+                    cycle_members.add(cls)
+                    return True
+            elif parent in rec_stack:
+                # Found a cycle
+                cycle_members.add(cls)
+                cycle_members.add(parent)
+                return True
+
+        rec_stack.remove(cls)
+        return False
+
+    for cls in classes:
+        if cls not in visited:
+            if dfs(cls):
+                # Continue to find all cycle members
+                pass
+
+    return bool(cycle_members), list(cycle_members)
+
+
+def _curie(graph: Graph, uri: URIRef) -> str:
+    """Convert URI to CURIE or short form for display.
+
+    Args:
+        graph: Graph with namespace bindings.
+        uri: URI to convert.
+
+    Returns:
+        CURIE or shortened URI string.
+    """
+    try:
+        return graph.namespace_manager.normalizeUri(uri)
+    except Exception:
+        s = str(uri)
+        if "#" in s:
+            return s.split("#")[-1]
+        elif "/" in s:
+            return s.split("/")[-1]
+        return s

rdf_construct/describe/imports.py

@@ -0,0 +1,213 @@
+"""Import analysis for ontology description.
+
+Handles owl:imports declarations and optional resolvability checking.
+"""
+
+import urllib.request
+import urllib.error
+from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeout
+from typing import Optional
+
+from rdflib import Graph, URIRef
+from rdflib.namespace import OWL
+
+from rdf_construct.describe.models import ImportAnalysis, ImportInfo, ImportStatus
+
+
+# Timeout for HTTP requests (seconds)
+REQUEST_TIMEOUT = 10
+
+# Maximum concurrent resolution checks
+MAX_WORKERS = 5
+
+
+def analyse_imports(
+    graph: Graph,
+    resolve: bool = True,
+    timeout: int = REQUEST_TIMEOUT,
+) -> ImportAnalysis:
+    """Analyse owl:imports declarations in the ontology.
+
+    Args:
+        graph: RDF graph to analyse.
+        resolve: Whether to check resolvability of imports.
+        timeout: Timeout for resolution checks in seconds.
+
+    Returns:
+        ImportAnalysis with import information.
+    """
+    # Find all owl:imports declarations
+    import_uris: list[URIRef] = []
+    for ontology in graph.subjects(None, OWL.Ontology):
+        for import_uri in graph.objects(ontology, OWL.imports):
+            if isinstance(import_uri, URIRef):
+                import_uris.append(import_uri)
+
+    if not import_uris:
+        return ImportAnalysis(imports=[], resolve_attempted=False)
+
+    # Build import info list
+    imports: list[ImportInfo] = []
+
+    if resolve:
+        # Resolve imports in parallel with timeout
+        with ThreadPoolExecutor(max_workers=MAX_WORKERS) as executor:
+            futures = {
+                executor.submit(_check_resolvable, str(uri), timeout): uri
+                for uri in import_uris
+            }
+
+            for future in futures:
+                uri = futures[future]
+                try:
+                    status, error = future.result(timeout=timeout + 5)
+                    imports.append(ImportInfo(
+                        uri=str(uri),
+                        status=status,
+                        error=error,
+                    ))
+                except FuturesTimeout:
+                    imports.append(ImportInfo(
+                        uri=str(uri),
+                        status=ImportStatus.UNRESOLVABLE,
+                        error="Resolution timed out",
+                    ))
+                except Exception as e:
+                    imports.append(ImportInfo(
+                        uri=str(uri),
+                        status=ImportStatus.UNRESOLVABLE,
+                        error=str(e),
+                    ))
+    else:
+        # Just list imports without resolution
+        imports = [
+            ImportInfo(uri=str(uri), status=ImportStatus.UNCHECKED)
+            for uri in import_uris
+        ]
+
+    return ImportAnalysis(
+        imports=imports,
+        resolve_attempted=resolve,
+    )
+
+
+def _check_resolvable(uri: str, timeout: int) -> tuple[ImportStatus, Optional[str]]:
+    """Check if a URI is resolvable via HTTP HEAD request.
+
+    Args:
+        uri: URI to check.
+        timeout: Request timeout in seconds.
+
+    Returns:
+        Tuple of (status, error_message).
+    """
+    try:
+        # Create a HEAD request to check resolvability without downloading
+        request = urllib.request.Request(
+            uri,
+            method="HEAD",
+            headers={
+                "Accept": "application/rdf+xml, text/turtle, application/ld+json, */*",
+                "User-Agent": "rdf-construct/describe",
+            },
+        )
+
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            if response.status == 200:
+                return ImportStatus.RESOLVABLE, None
+            else:
+                return ImportStatus.UNRESOLVABLE, f"HTTP {response.status}"
+
+    except urllib.error.HTTPError as e:
+        # Some servers don't support HEAD but work with GET
+        if e.code == 405:  # Method Not Allowed
+            return _try_get_request(uri, timeout)
+        return ImportStatus.UNRESOLVABLE, f"HTTP {e.code}: {e.reason}"
+
+    except urllib.error.URLError as e:
+        return ImportStatus.UNRESOLVABLE, f"Network error: {e.reason}"
+
+    except TimeoutError:
+        return ImportStatus.UNRESOLVABLE, "Request timed out"
+
+    except Exception as e:
+        return ImportStatus.UNRESOLVABLE, str(e)
+
+
+def _try_get_request(uri: str, timeout: int) -> tuple[ImportStatus, Optional[str]]:
+    """Fall back to GET request if HEAD is not allowed.
+
+    Args:
+        uri: URI to check.
+        timeout: Request timeout in seconds.
+
+    Returns:
+        Tuple of (status, error_message).
+    """
+    try:
+        request = urllib.request.Request(
+            uri,
+            headers={
+                "Accept": "application/rdf+xml, text/turtle, application/ld+json, */*",
+                "User-Agent": "rdf-construct/describe",
+            },
+        )
+
+        # Only read a small amount to check availability
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            # Read just enough to confirm it's responding
+            response.read(1024)
+            return ImportStatus.RESOLVABLE, None
+
+    except urllib.error.HTTPError as e:
+        return ImportStatus.UNRESOLVABLE, f"HTTP {e.code}: {e.reason}"
+
+    except urllib.error.URLError as e:
+        return ImportStatus.UNRESOLVABLE, f"Network error: {e.reason}"
+
+    except Exception as e:
+        return ImportStatus.UNRESOLVABLE, str(e)
+
+
+def get_imported_namespaces(graph: Graph) -> set[str]:
+    """Get the namespace URIs of imported ontologies.
+
+    Used for namespace categorisation.
+
+    Args:
+        graph: RDF graph to analyse.
+
+    Returns:
+        Set of namespace URI strings.
+    """
+    namespaces = set()
+
+    for ontology in graph.subjects(None, OWL.Ontology):
+        for import_uri in graph.objects(ontology, OWL.imports):
+            if isinstance(import_uri, URIRef):
+                # The import URI is typically the namespace or close to it
+                ns = _extract_namespace(str(import_uri))
+                namespaces.add(ns)
+
+    return namespaces
+
+
+def _extract_namespace(uri: str) -> str:
+    """Extract namespace from an ontology URI.
+
+    Args:
+        uri: Ontology URI.
+
+    Returns:
+        Namespace string.
+    """
+    # Common patterns:
+    # - http://example.org/ontology# -> http://example.org/ontology#
+    # - http://example.org/ontology/ -> http://example.org/ontology/
+    # - http://example.org/ontology -> http://example.org/ontology#
+
+    if uri.endswith("#") or uri.endswith("/"):
+        return uri
+
+    # Add hash if no separator at end
+    return uri + "#"

rdf_construct/describe/metadata.py

@@ -0,0 +1,187 @@
+"""Metadata extraction for ontology description.
+
+Extracts ontology-level metadata like IRI, title, description, license, creators.
+"""
+
+from rdflib import Graph, URIRef, Literal, RDF, RDFS
+from rdflib.namespace import OWL
+
+from rdf_construct.describe.models import OntologyMetadata
+
+
+# Dublin Core namespaces
+DC = URIRef("http://purl.org/dc/elements/1.1/")
+DCTERMS = URIRef("http://purl.org/dc/terms/")
+
+# Common metadata predicates
+DC_TITLE = URIRef(str(DC) + "title")
+DC_DESCRIPTION = URIRef(str(DC) + "description")
+DC_CREATOR = URIRef(str(DC) + "creator")
+DC_RIGHTS = URIRef(str(DC) + "rights")
+
+DCTERMS_TITLE = URIRef(str(DCTERMS) + "title")
+DCTERMS_DESCRIPTION = URIRef(str(DCTERMS) + "description")
+DCTERMS_CREATOR = URIRef(str(DCTERMS) + "creator")
+DCTERMS_LICENSE = URIRef(str(DCTERMS) + "license")
+DCTERMS_RIGHTS = URIRef(str(DCTERMS) + "rights")
+
+# Creative Commons namespace
+CC = URIRef("http://creativecommons.org/ns#")
+CC_LICENSE = URIRef(str(CC) + "license")
+
+
+def extract_metadata(graph: Graph) -> OntologyMetadata:
+    """Extract ontology-level metadata.
+
+    Looks for owl:Ontology declaration and extracts common metadata
+    properties like title, description, license, and creators.
+
+    Args:
+        graph: RDF graph to analyse.
+
+    Returns:
+        OntologyMetadata with extracted values.
+    """
+    metadata = OntologyMetadata()
+
+    # Find ontology subject(s)
+    ontology_subjects = list(graph.subjects(RDF.type, OWL.Ontology))
+
+    if not ontology_subjects:
+        return metadata
+
+    # Use first ontology subject (typically there's only one)
+    ontology = ontology_subjects[0]
+
+    # Ontology IRI
+    if isinstance(ontology, URIRef):
+        metadata.ontology_iri = str(ontology)
+
+    # Version IRI
+    version_iri = _get_single_value(graph, ontology, OWL.versionIRI)
+    if version_iri:
+        metadata.version_iri = str(version_iri)
+
+    # Version info
+    version_info = _get_single_literal(graph, ontology, OWL.versionInfo)
+    if version_info:
+        metadata.version_info = version_info
+
+    # Title (try multiple predicates)
+    title = (
+        _get_single_literal(graph, ontology, RDFS.label)
+        or _get_single_literal(graph, ontology, DCTERMS_TITLE)
+        or _get_single_literal(graph, ontology, DC_TITLE)
+    )
+    if title:
+        metadata.title = title
+
+    # Description (try multiple predicates)
+    description = (
+        _get_single_literal(graph, ontology, RDFS.comment)
+        or _get_single_literal(graph, ontology, DCTERMS_DESCRIPTION)
+        or _get_single_literal(graph, ontology, DC_DESCRIPTION)
+    )
+    if description:
+        metadata.description = description
+
+    # License
+    license_uri = (
+        _get_single_value(graph, ontology, DCTERMS_LICENSE)
+        or _get_single_value(graph, ontology, CC_LICENSE)
+    )
+    if license_uri:
+        metadata.license_uri = str(license_uri)
+        # Try to get a label for the license
+        if isinstance(license_uri, URIRef):
+            license_label = _get_single_literal(graph, license_uri, RDFS.label)
+            if license_label:
+                metadata.license_label = license_label
+
+    # If no structured license, check for rights statement
+    if not metadata.license_uri:
+        rights = (
+            _get_single_literal(graph, ontology, DCTERMS_RIGHTS)
+            or _get_single_literal(graph, ontology, DC_RIGHTS)
+        )
+        if rights:
+            metadata.license_label = rights
+
+    # Creators
+    creators = []
+    for pred in [DCTERMS_CREATOR, DC_CREATOR]:
+        for creator in graph.objects(ontology, pred):
+            if isinstance(creator, Literal):
+                creators.append(str(creator))
+            elif isinstance(creator, URIRef):
+                # Try to get a label for the creator
+                label = _get_single_literal(graph, creator, RDFS.label)
+                if label:
+                    creators.append(label)
+                else:
+                    # Use URI local name
+                    creators.append(_local_name(str(creator)))
+
+    if creators:
+        metadata.creators = creators
+
+    return metadata
+
+
+def _get_single_value(graph: Graph, subject: URIRef, predicate: URIRef):
+    """Get a single value for a predicate (URI or literal).
+
+    Args:
+        graph: RDF graph to query.
+        subject: Subject to query.
+        predicate: Predicate to look for.
+
+    Returns:
+        First value found or None.
+    """
+    for obj in graph.objects(subject, predicate):
+        return obj
+    return None
+
+
+def _get_single_literal(graph: Graph, subject: URIRef, predicate: URIRef) -> str | None:
+    """Get a single literal value for a predicate.
+
+    Prefers English language literals if multiple exist.
+
+    Args:
+        graph: RDF graph to query.
+        subject: Subject to query.
+        predicate: Predicate to look for.
+
+    Returns:
+        Literal string value or None.
+    """
+    english_value = None
+    any_value = None
+
+    for obj in graph.objects(subject, predicate):
+        if isinstance(obj, Literal):
+            value = str(obj)
+            if obj.language == "en":
+                english_value = value
+            elif any_value is None:
+                any_value = value
+
+    return english_value or any_value
+
+
+def _local_name(uri: str) -> str:
+    """Extract local name from a URI.
+
+    Args:
+        uri: Full URI string.
+
+    Returns:
+        Local name portion.
+    """
+    if "#" in uri:
+        return uri.split("#")[-1]
+    elif "/" in uri:
+        return uri.split("/")[-1]
+    return uri