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

rdf_construct/__init__.py

@@ -4,7 +4,7 @@ Named after the ROM construct from William Gibson's Neuromancer -
 preserved, structured knowledge that can be queried and transformed.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 from . import core, uml
 from .cli import cli

rdf_construct/cli.py

@@ -1810,6 +1810,133 @@ def stats(
         sys.exit(1)
 
 
+@cli.command()
+@click.argument("file", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(path_type=Path),
+    help="Write output to file instead of stdout",
+)
+@click.option(
+    "--format",
+    "-f",
+    "output_format",
+    type=click.Choice(["text", "json", "markdown", "md"], case_sensitive=False),
+    default="text",
+    help="Output format (default: text)",
+)
+@click.option(
+    "--brief",
+    is_flag=True,
+    help="Show brief summary only (metadata, metrics, profile)",
+)
+@click.option(
+    "--no-resolve",
+    is_flag=True,
+    help="Skip import resolution checks",
+)
+@click.option(
+    "--reasoning",
+    is_flag=True,
+    help="Include reasoning analysis",
+)
+@click.option(
+    "--no-colour",
+    "--no-color",
+    is_flag=True,
+    help="Disable coloured output (text format only)",
+)
+def describe(
+    file: Path,
+    output: Path | None,
+    output_format: str,
+    brief: bool,
+    no_resolve: bool,
+    reasoning: bool,
+    no_colour: bool,
+):
+    """Describe an ontology: profile, metrics, imports, and structure.
+
+    Provides a comprehensive analysis of an RDF ontology file, including:
+    - Profile detection (RDF, RDFS, OWL DL, OWL Full)
+    - Basic metrics (classes, properties, individuals)
+    - Import analysis with optional resolvability checking
+    - Namespace categorisation
+    - Class hierarchy analysis
+    - Documentation coverage
+
+    FILE: RDF ontology file to describe (.ttl, .rdf, .owl, etc.)
+
+    \b
+    Examples:
+        # Basic description
+        rdf-construct describe ontology.ttl
+
+        # Brief summary only
+        rdf-construct describe ontology.ttl --brief
+
+        # JSON output for programmatic use
+        rdf-construct describe ontology.ttl --format json -o description.json
+
+        # Markdown for documentation
+        rdf-construct describe ontology.ttl --format markdown -o DESCRIPTION.md
+
+        # Skip slow import resolution
+        rdf-construct describe ontology.ttl --no-resolve
+
+    \b
+    Exit codes:
+        0 - Success
+        1 - Success with warnings (unresolvable imports, etc.)
+        2 - Error (file not found, parse error)
+    """
+    from rdf_construct.describe import describe_file, format_description
+
+    try:
+        click.echo(f"Analysing {file}...", err=True)
+
+        # Perform analysis
+        description = describe_file(
+            file,
+            brief=brief,
+            resolve_imports=not no_resolve,
+            include_reasoning=reasoning,
+        )
+
+        # Format output
+        use_colour = not no_colour and output_format == "text" and output is None
+        formatted = format_description(
+            description,
+            format_name=output_format,
+            use_colour=use_colour,
+        )
+
+        # Write output
+        if output:
+            output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_text(formatted)
+            click.secho(f"✓ Wrote description to {output}", fg="green", err=True)
+        else:
+            click.echo(formatted)
+
+        # Exit code based on warnings
+        if description.imports and description.imports.unresolvable_count > 0:
+            sys.exit(1)
+        else:
+            sys.exit(0)
+
+    except FileNotFoundError as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(2)
+    except ValueError as e:
+        click.secho(f"Error parsing RDF: {e}", fg="red", err=True)
+        sys.exit(2)
+    except Exception as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(2)
+
+
 @cli.command()
 @click.argument("sources", nargs=-1, type=click.Path(exists=True, path_type=Path))
 @click.option(

rdf_construct/describe/__init__.py

@@ -0,0 +1,93 @@
+"""Describe command for RDF ontology analysis.
+
+Provides quick orientation and understanding of ontology files,
+answering: "What is this?", "How big is it?", "What does it depend on?",
+and "Can I work with it?"
+
+Usage:
+    from rdf_construct.describe import describe_file, format_description
+
+    description = describe_file(Path("ontology.ttl"))
+    print(format_description(description))
+
+    # Brief mode (metadata + metrics + profile only)
+    description = describe_file(Path("ontology.ttl"), brief=True)
+
+    # Skip import resolution (faster)
+    description = describe_file(Path("ontology.ttl"), resolve_imports=False)
+
+    # JSON output
+    print(format_description(description, format_name="json"))
+"""
+
+from rdf_construct.describe.models import (
+    OntologyDescription,
+    OntologyMetadata,
+    BasicMetrics,
+    ProfileDetection,
+    OntologyProfile,
+    NamespaceAnalysis,
+    NamespaceInfo,
+    NamespaceCategory,
+    ImportAnalysis,
+    ImportInfo,
+    ImportStatus,
+    HierarchyAnalysis,
+    DocumentationCoverage,
+    ReasoningAnalysis,
+)
+
+from rdf_construct.describe.analyzer import (
+    describe_ontology,
+    describe_file,
+)
+
+from rdf_construct.describe.formatters import (
+    format_description,
+    format_text,
+    format_markdown,
+    format_json,
+)
+
+from rdf_construct.describe.profiles import detect_profile
+from rdf_construct.describe.metrics import collect_metrics
+from rdf_construct.describe.imports import analyse_imports
+from rdf_construct.describe.namespaces import analyse_namespaces
+from rdf_construct.describe.hierarchy import analyse_hierarchy
+from rdf_construct.describe.documentation import analyse_documentation
+from rdf_construct.describe.metadata import extract_metadata
+
+
+__all__ = [
+    # Main functions
+    "describe_file",
+    "describe_ontology",
+    "format_description",
+    # Formatters
+    "format_text",
+    "format_markdown",
+    "format_json",
+    # Analysis functions (for direct use)
+    "detect_profile",
+    "collect_metrics",
+    "analyse_imports",
+    "analyse_namespaces",
+    "analyse_hierarchy",
+    "analyse_documentation",
+    "extract_metadata",
+    # Data models
+    "OntologyDescription",
+    "OntologyMetadata",
+    "BasicMetrics",
+    "ProfileDetection",
+    "OntologyProfile",
+    "NamespaceAnalysis",
+    "NamespaceInfo",
+    "NamespaceCategory",
+    "ImportAnalysis",
+    "ImportInfo",
+    "ImportStatus",
+    "HierarchyAnalysis",
+    "DocumentationCoverage",
+    "ReasoningAnalysis",
+]

rdf_construct/describe/analyzer.py

@@ -0,0 +1,176 @@
+"""Main analyzer for ontology description.
+
+Orchestrates all analysis components and aggregates results into
+a complete OntologyDescription.
+"""
+
+from datetime import datetime
+from pathlib import Path
+
+from rdflib import Graph
+
+from rdf_construct.describe.models import OntologyDescription
+from rdf_construct.describe.metadata import extract_metadata
+from rdf_construct.describe.metrics import collect_metrics
+from rdf_construct.describe.profiles import detect_profile
+from rdf_construct.describe.namespaces import analyse_namespaces
+from rdf_construct.describe.imports import analyse_imports
+from rdf_construct.describe.hierarchy import analyse_hierarchy
+from rdf_construct.describe.documentation import analyse_documentation
+
+
+def describe_ontology(
+    graph: Graph,
+    source: str | Path,
+    brief: bool = False,
+    resolve_imports: bool = True,
+    include_reasoning: bool = False,
+) -> OntologyDescription:
+    """Generate a complete description of an ontology.
+
+    Runs all analysis components and aggregates results.
+
+    Args:
+        graph: Parsed RDF graph to analyse.
+        source: Source file path or identifier.
+        brief: If True, skip detailed analysis (imports, hierarchy, etc.).
+        resolve_imports: Whether to check resolvability of imports.
+        include_reasoning: Whether to include reasoning analysis.
+
+    Returns:
+        OntologyDescription with all analysis results.
+    """
+    # Always perform core analysis
+    metadata = extract_metadata(graph)
+    metrics = collect_metrics(graph)
+    profile = detect_profile(graph)
+
+    # Create base description
+    description = OntologyDescription(
+        source=source,
+        timestamp=datetime.now(),
+        metadata=metadata,
+        metrics=metrics,
+        profile=profile,
+        brief=brief,
+        include_reasoning=include_reasoning,
+    )
+
+    # Skip detailed analysis if brief mode
+    if brief:
+        return description
+
+    # Full analysis
+    description.namespaces = analyse_namespaces(graph)
+    description.imports = analyse_imports(graph, resolve=resolve_imports)
+    description.hierarchy = analyse_hierarchy(graph)
+    description.documentation = analyse_documentation(graph)
+
+    # Reasoning analysis is optional and off by default
+    if include_reasoning:
+        description.reasoning = _analyse_reasoning(graph, profile)
+
+    return description
+
+
+def describe_file(
+    file_path: Path,
+    brief: bool = False,
+    resolve_imports: bool = True,
+    include_reasoning: bool = False,
+) -> OntologyDescription:
+    """Generate a complete description of an ontology file.
+
+    Convenience function that handles file loading and format detection.
+
+    Args:
+        file_path: Path to RDF file.
+        brief: If True, skip detailed analysis.
+        resolve_imports: Whether to check resolvability of imports.
+        include_reasoning: Whether to include reasoning analysis.
+
+    Returns:
+        OntologyDescription with all analysis results.
+
+    Raises:
+        FileNotFoundError: If file does not exist.
+        ValueError: If file cannot be parsed.
+    """
+    if not file_path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    # Detect format from extension
+    rdf_format = _infer_format(file_path)
+
+    # Parse the file
+    graph = Graph()
+    try:
+        graph.parse(str(file_path), format=rdf_format)
+    except Exception as e:
+        raise ValueError(f"Failed to parse {file_path}: {e}") from e
+
+    return describe_ontology(
+        graph=graph,
+        source=file_path,
+        brief=brief,
+        resolve_imports=resolve_imports,
+        include_reasoning=include_reasoning,
+    )
+
+
+def _infer_format(path: Path) -> str:
+    """Infer RDF format from file extension.
+
+    Args:
+        path: Path to RDF file.
+
+    Returns:
+        Format string for rdflib.
+    """
+    suffix = path.suffix.lower()
+    format_map = {
+        ".ttl": "turtle",
+        ".turtle": "turtle",
+        ".rdf": "xml",
+        ".xml": "xml",
+        ".owl": "xml",
+        ".nt": "nt",
+        ".ntriples": "nt",
+        ".n3": "n3",
+        ".jsonld": "json-ld",
+        ".json": "json-ld",
+    }
+    return format_map.get(suffix, "turtle")
+
+
+def _analyse_reasoning(graph: Graph, profile) -> "ReasoningAnalysis":
+    """Perform reasoning analysis (optional feature).
+
+    This is a placeholder for future reasoning analysis functionality.
+
+    Args:
+        graph: RDF graph to analyse.
+        profile: Detected profile.
+
+    Returns:
+        ReasoningAnalysis with reasoning implications.
+    """
+    from rdf_construct.describe.models import ReasoningAnalysis, OntologyProfile
+
+    # Determine entailment regime based on profile
+    regime_map = {
+        OntologyProfile.RDF: "none",
+        OntologyProfile.RDFS: "rdfs",
+        OntologyProfile.OWL_DL_SIMPLE: "owl-dl",
+        OntologyProfile.OWL_DL_EXPRESSIVE: "owl-dl",
+        OntologyProfile.OWL_FULL: "owl-full",
+    }
+
+    regime = regime_map.get(profile.profile, "unknown")
+
+    return ReasoningAnalysis(
+        entailment_regime=regime,
+        inferred_superclasses=[],
+        inferred_types=[],
+        consistency_notes=[],
+    )

rdf_construct/describe/documentation.py

@@ -0,0 +1,146 @@
+"""Documentation coverage analysis for ontology description.
+
+Analyses the presence of labels and definitions for classes and properties.
+"""
+
+from rdflib import Graph, URIRef, RDF, RDFS
+from rdflib.namespace import OWL
+
+from rdf_construct.describe.models import DocumentationCoverage
+
+
+# Predicates considered as providing a label
+LABEL_PREDICATES = {
+    RDFS.label,
+    URIRef("http://www.w3.org/2004/02/skos/core#prefLabel"),
+    URIRef("http://www.w3.org/2004/02/skos/core#altLabel"),
+    URIRef("http://purl.org/dc/elements/1.1/title"),
+    URIRef("http://purl.org/dc/terms/title"),
+}
+
+# Predicates considered as providing a definition/description
+DEFINITION_PREDICATES = {
+    RDFS.comment,
+    URIRef("http://www.w3.org/2004/02/skos/core#definition"),
+    URIRef("http://purl.org/dc/elements/1.1/description"),
+    URIRef("http://purl.org/dc/terms/description"),
+}
+
+
+def analyse_documentation(graph: Graph) -> DocumentationCoverage:
+    """Analyse documentation coverage for classes and properties.
+
+    Args:
+        graph: RDF graph to analyse.
+
+    Returns:
+        DocumentationCoverage with coverage metrics.
+    """
+    # Get all classes
+    classes = _get_all_classes(graph)
+    classes_total = len(classes)
+
+    # Get all properties
+    properties = _get_all_properties(graph)
+    properties_total = len(properties)
+
+    # Count classes with labels
+    classes_with_label = sum(1 for cls in classes if _has_label(graph, cls))
+
+    # Count classes with definitions
+    classes_with_definition = sum(1 for cls in classes if _has_definition(graph, cls))
+
+    # Count properties with labels
+    properties_with_label = sum(1 for prop in properties if _has_label(graph, prop))
+
+    # Count properties with definitions
+    properties_with_definition = sum(
+        1 for prop in properties if _has_definition(graph, prop)
+    )
+
+    return DocumentationCoverage(
+        classes_with_label=classes_with_label,
+        classes_total=classes_total,
+        classes_with_definition=classes_with_definition,
+        properties_with_label=properties_with_label,
+        properties_total=properties_total,
+        properties_with_definition=properties_with_definition,
+    )
+
+
+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()
+
+    for cls in graph.subjects(RDF.type, OWL.Class):
+        if isinstance(cls, URIRef):
+            classes.add(cls)
+
+    for cls in graph.subjects(RDF.type, RDFS.Class):
+        if isinstance(cls, URIRef):
+            classes.add(cls)
+
+    return classes
+
+
+def _get_all_properties(graph: Graph) -> set[URIRef]:
+    """Get all properties from the graph.
+
+    Args:
+        graph: RDF graph to query.
+
+    Returns:
+        Set of property URIRefs.
+    """
+    properties: set[URIRef] = set()
+
+    for prop_type in (
+        OWL.ObjectProperty,
+        OWL.DatatypeProperty,
+        OWL.AnnotationProperty,
+        RDF.Property,
+    ):
+        for prop in graph.subjects(RDF.type, prop_type):
+            if isinstance(prop, URIRef):
+                properties.add(prop)
+
+    return properties
+
+
+def _has_label(graph: Graph, subject: URIRef) -> bool:
+    """Check if a subject has any label predicate.
+
+    Args:
+        graph: RDF graph to query.
+        subject: Subject to check.
+
+    Returns:
+        True if subject has at least one label.
+    """
+    for pred in LABEL_PREDICATES:
+        if any(graph.objects(subject, pred)):
+            return True
+    return False
+
+
+def _has_definition(graph: Graph, subject: URIRef) -> bool:
+    """Check if a subject has any definition/description predicate.
+
+    Args:
+        graph: RDF graph to query.
+        subject: Subject to check.
+
+    Returns:
+        True if subject has at least one definition.
+    """
+    for pred in DEFINITION_PREDICATES:
+        if any(graph.objects(subject, pred)):
+            return True
+    return False

rdf_construct/describe/formatters/__init__.py

@@ -0,0 +1,47 @@
+"""Output formatters for ontology description."""
+
+from typing import Optional
+
+from rdf_construct.describe.models import OntologyDescription
+from rdf_construct.describe.formatters.text import format_text
+from rdf_construct.describe.formatters.markdown import format_markdown
+from rdf_construct.describe.formatters.json import format_json
+
+
+def format_description(
+    description: OntologyDescription,
+    format_name: str = "text",
+    use_colour: bool = True,
+) -> str:
+    """Format ontology description for output.
+
+    Args:
+        description: The description to format.
+        format_name: Output format ("text", "json", "markdown", "md").
+        use_colour: Whether to use ANSI colour codes (text format only).
+
+    Returns:
+        Formatted string representation.
+
+    Raises:
+        ValueError: If format_name is not recognised.
+    """
+    format_name = format_name.lower()
+
+    if format_name == "text":
+        return format_text(description, use_colour=use_colour)
+    elif format_name == "json":
+        return format_json(description)
+    elif format_name in ("markdown", "md"):
+        return format_markdown(description)
+    else:
+        valid = "text, json, markdown, md"
+        raise ValueError(f"Unknown format '{format_name}'. Valid formats: {valid}")
+
+
+__all__ = [
+    "format_description",
+    "format_text",
+    "format_markdown",
+    "format_json",
+]

rdf_construct/describe/formatters/json.py

@@ -0,0 +1,65 @@
+"""JSON formatter for ontology description output.
+
+Produces structured JSON for programmatic consumption.
+"""
+
+import json
+from typing import Any
+
+from rdf_construct.describe.models import OntologyDescription
+
+
+def format_json(
+    description: OntologyDescription,
+    indent: int = 2,
+    ensure_ascii: bool = False,
+) -> str:
+    """Format ontology description as JSON.
+
+    Args:
+        description: OntologyDescription to format.
+        indent: Indentation level for pretty printing.
+        ensure_ascii: If True, escape non-ASCII characters.
+
+    Returns:
+        JSON string.
+    """
+    data = description.to_dict()
+
+    return json.dumps(
+        data,
+        indent=indent,
+        ensure_ascii=ensure_ascii,
+        default=_json_serializer,
+    )
+
+
+def _json_serializer(obj: Any) -> Any:
+    """Custom JSON serializer for non-standard types.
+
+    Args:
+        obj: Object to serialize.
+
+    Returns:
+        JSON-serializable representation.
+
+    Raises:
+        TypeError: If object cannot be serialized.
+    """
+    # Handle Path objects
+    if hasattr(obj, "__fspath__"):
+        return str(obj)
+
+    # Handle datetime
+    if hasattr(obj, "isoformat"):
+        return obj.isoformat()
+
+    # Handle enums
+    if hasattr(obj, "value"):
+        return obj.value
+
+    # Handle dataclasses with to_dict method
+    if hasattr(obj, "to_dict"):
+        return obj.to_dict()
+
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")