iolanta 2.1.11__py3-none-any.whl → 2.1.12__py3-none-any.whl

iolanta/iolanta.py

@@ -6,7 +6,6 @@ from typing import (  # noqa: WPS235
     Any,
     Iterable,
     List,
-    Mapping,
     Optional,
     Protocol,
     Set,
@@ -27,7 +26,6 @@ from iolanta import entry_points, namespaces
 from iolanta.conversions import path_to_iri
 from iolanta.errors import UnresolvedIRI
 from iolanta.facets.errors import FacetError
-from iolanta.facets.facet import Facet
 from iolanta.facets.locator import FacetFinder
 from iolanta.models import ComputedQName, LDContext, NotLiteralNode
 from iolanta.node_to_qname import node_to_qname
@@ -43,13 +41,13 @@ from iolanta.resolvers.base import Resolver
 from iolanta.resolvers.dispatch import SchemeDispatchResolver
 from iolanta.resolvers.pypi import PyPIResolver
 from iolanta.resolvers.python_import import PythonImportResolver
-from iolanta.sparqlspace.processor import normalize_term
+from iolanta.sparqlspace.processor import normalize_term  # noqa: WPS201
 
 
 class LoggerProtocol(Protocol):
     """Abstract Logger interface that unites `loguru` & standard `logging`."""
 
-    def info(self, message: str, *args: Any, **kwargs: Any) -> None:
+    def info(self, message: str, *args: Any, **kwargs: Any) -> None:  # noqa: WPS110
         """Log an INFO message."""
 
     def error(self, message: str, *args: Any, **kwargs: Any) -> None:
@@ -60,20 +58,20 @@ class LoggerProtocol(Protocol):
 
 
 def _create_default_graph():
-    return ConjunctiveGraph(identifier=namespaces.LOCAL.term('_inference'))
+    return ConjunctiveGraph(identifier=namespaces.LOCAL.term("_inference"))
 
 
 @dataclass
-class Iolanta:   # noqa: WPS214
+class Iolanta:  # noqa: WPS214, WPS338
     """Iolanta is a Semantic web browser."""
 
-    language: Literal = Literal('en')
+    language: Literal = Literal("en")
 
     project_root: Annotated[
         Path | None,
         (
-            'File or directory the contents of which '
-            'Iolanta will automatically load into the graph.'
+            "File or directory the contents of which "
+            "Iolanta will automatically load into the graph."
         ),
     ] = None
     graph: ConjunctiveGraph = field(default_factory=_create_default_graph)
@@ -94,18 +92,100 @@ class Iolanta:   # noqa: WPS214
         init=False,
     )
 
+    _facet_inference_needed: bool = field(
+        default=False,
+        init=False,
+    )
+
     @property
     def plugin_classes(self) -> List[Type[Plugin]]:
         """Installed Iolanta plugins."""
-        return self.force_plugins or entry_points.plugins('iolanta.plugins')
+        return self.force_plugins or entry_points.plugins("iolanta.plugins")
 
     @functools.cached_property
     def plugins(self) -> List[Plugin]:
         """Construct a list of installed plugin instances."""
-        return [
-            plugin_class(iolanta=self)
-            for plugin_class in self.plugin_classes
-        ]
+        return [plugin_class(iolanta=self) for plugin_class in self.plugin_classes]
+
+    def _run_facet_inference(self):
+        """Run inference queries from facet inference directories."""
+        for facet_class in self.facet_classes:
+            inference_path = facet_class.inference_path
+
+            if inference_path is not None:
+                facet_name = facet_class.__name__.lower()
+                self._run_inference_from_directory(
+                    inference_path,
+                    graph_prefix=f"facet-{facet_name}",
+                )
+
+    def _run_inference_from_directory(  # noqa: WPS210, WPS231
+        self,
+        inference_dir: Path,
+        graph_prefix: str = "inference",
+    ):
+        """
+        Run inference queries from a given inference directory.
+
+        For each SPARQL file in the inference directory:
+        1. Truncate the named graph `local:{graph_prefix}-{filename}`
+        2. Execute the CONSTRUCT query
+        3. Insert the resulting triples into that graph
+        """
+        if not inference_dir.exists():
+            return
+
+        inference_files = sorted(inference_dir.glob("*.sparql"))
+
+        for inference_file in inference_files:
+            filename = inference_file.stem  # filename without .sparql extension
+            inference_graph = URIRef(f"{graph_prefix}:{filename}")
+
+            # Truncate the inference graph
+            context = self.graph.get_context(inference_graph)
+            context.remove((None, None, None))
+
+            # Read and execute the CONSTRUCT query
+            query_text = inference_file.read_text()
+            try:
+                query_result = self.graph.query(query_text)  # noqa: WPS110
+            except (SyntaxError, ParseException) as err:
+                self.logger.error(
+                    "Invalid SPARQL syntax in inference query {filename}: {error}",
+                    filename=filename,
+                    error=err,
+                )
+                raise SPARQLParseException(
+                    error=err,
+                    query=query_text,
+                ) from err
+
+            # CONSTRUCT queries return a SPARQLResult with a graph attribute
+            result_graph = (
+                query_result.get("graph")
+                if isinstance(query_result, dict)
+                else query_result.graph
+            )
+            if result_graph is None:
+                raise ValueError(
+                    f"CONSTRUCT query {filename} returned None result_graph. "
+                    f"query_result type: {type(query_result)}, "
+                    f"query_result: {query_result}"
+                )
+
+            inferred_quads = [
+                (s, p, o, inference_graph)  # noqa: WPS111
+                for s, p, o in result_graph  # noqa: WPS111
+            ]
+            self.logger.info(f"Inference {filename}: generated quads: {inferred_quads}")
+
+            if inferred_quads:
+                self.graph.addN(inferred_quads)  # noqa: WPS220
+                self.logger.info(  # noqa: WPS220
+                    "Inference {filename}: added {count} triples",
+                    filename=filename,
+                    count=len(inferred_quads),
+                )
 
     def query(
         self,
@@ -116,7 +196,7 @@ class Iolanta:   # noqa: WPS214
         try:
             sparql_result: SPARQLResult = self.graph.query(
                 query_text,
-                processor='sparqlspace',
+                processor="sparqlspace",
                 initBindings=kwargs,
             )
         except SyntaxError as err:
@@ -125,6 +205,11 @@ class Iolanta:   # noqa: WPS214
                 query=query_text,
             ) from err
 
+        # Run facet-specific inference if needed
+        if self._facet_inference_needed:
+            self._run_facet_inference()
+            self._facet_inference_needed = False
+
         if sparql_result.askAnswer is not None:
             return sparql_result.askAnswer
 
@@ -139,7 +224,8 @@ class Iolanta:   # noqa: WPS214
 
     def reset(self):
         """Reset Iolanta graph."""
-        self.graph = _create_default_graph()   # noqa: WPS601
+        self.graph = _create_default_graph()  # noqa: WPS601
+        self._facet_inference_needed = False
         self.__post_init__()
 
     def add(  # noqa: C901, WPS231, WPS210, WPS213
@@ -147,14 +233,14 @@ class Iolanta:   # noqa: WPS214
         source: Path,
         context: Optional[LDContext] = None,
         graph_iri: Optional[URIRef] = None,
-    ) -> 'Iolanta':
+    ) -> "Iolanta":
         """Parse & load information from given URL into the graph."""
-        self.logger.info(f'Adding to graph: {source}')
+        self.logger.info(f"Adding to graph: {source}")
 
         if not isinstance(source, Path):
             source = Path(source)
 
-        for source_file in list(source.rglob('*')) or [source]:
+        for source_file in list(source.rglob("*")) or [source]:
             if source_file.is_dir():
                 continue
 
@@ -162,23 +248,23 @@ class Iolanta:   # noqa: WPS214
                 ld_rdf = yaml_ld.to_rdf(source_file)
             except ConnectionError as name_resolution_error:
                 self.logger.warning(
-                    '%s | name resolution error: %s',
+                    "%s | name resolution error: %s",
                     source_file,
                     str(name_resolution_error),
                 )
                 continue
             except ParserNotFound as parser_not_found:
-                self.logger.error(f'{source} | {parser_not_found}')
+                self.logger.error(f"{source} | {parser_not_found}")
                 continue
             except YAMLLDError as yaml_ld_error:
                 # .add() only processes local files, so errors should be raised
-                self.logger.error(f'{source_file} | {yaml_ld_error}')
+                self.logger.error(f"{source_file} | {yaml_ld_error}")
                 raise
             except ValueError as value_error:
-                self.logger.error(f'{source} | {value_error}')
+                self.logger.error(f"{source} | {value_error}")
                 continue
 
-            self.logger.info(f'{source_file} is loaded.')
+            self.logger.info(f"{source_file} is loaded.")
 
             graph = path_to_iri(source_file)
             try:
@@ -186,7 +272,7 @@ class Iolanta:   # noqa: WPS214
                     parse_quads(
                         quads_document=ld_rdf,
                         graph=graph,
-                        blank_node_prefix=str(source),
+                        blank_node_prefix=str(source_file),
                     ),
                 )
             except UnresolvedIRI as err:
@@ -197,44 +283,45 @@ class Iolanta:   # noqa: WPS214
                 )
 
             if not quads:
-                self.logger.info(f'{source_file} | No data found')
+                self.logger.info(f"{source_file} | No data found")
                 continue
 
             self.graph.addN(quads)
+            self._facet_inference_needed = True
 
         return self
 
-    def infer(self, closure_class=None) -> 'Iolanta':
+    def infer(self, closure_class=None) -> "Iolanta":
         """Apply inference."""
         return self
 
-    def bind_namespaces(self):
+    def bind_namespaces(self):  # noqa: WPS213
         """Bind namespaces."""
         self.graph.namespace_manager = NamespaceManager(
             self.graph,
-            bind_namespaces='none',
+            bind_namespaces="none",
         )
-        self.graph.bind(prefix='local', namespace=namespaces.LOCAL)
-        self.graph.bind(prefix='iolanta', namespace=namespaces.IOLANTA)
-        self.graph.bind(prefix='rdf', namespace=namespaces.RDF)
-        self.graph.bind(prefix='rdfs', namespace=namespaces.RDFS)
-        self.graph.bind(prefix='owl', namespace=namespaces.OWL)
-        self.graph.bind(prefix='foaf', namespace=namespaces.FOAF)
-        self.graph.bind(prefix='schema', namespace=namespaces.SDO)
-        self.graph.bind(prefix='vann', namespace=namespaces.VANN)
-        self.graph.bind(prefix='np', namespace=namespaces.NP)
-        self.graph.bind(prefix='dcterms', namespace=namespaces.DCTERMS)
-        self.graph.bind(prefix='rdfg', namespace=namespaces.RDFG)
+        self.graph.bind(prefix="local", namespace=namespaces.LOCAL)
+        self.graph.bind(prefix="iolanta", namespace=namespaces.IOLANTA)
+        self.graph.bind(prefix="rdf", namespace=namespaces.RDF)
+        self.graph.bind(prefix="rdfs", namespace=namespaces.RDFS)
+        self.graph.bind(prefix="owl", namespace=namespaces.OWL)
+        self.graph.bind(prefix="foaf", namespace=namespaces.FOAF)
+        self.graph.bind(prefix="schema", namespace=namespaces.SDO)
+        self.graph.bind(prefix="vann", namespace=namespaces.VANN)
+        self.graph.bind(prefix="np", namespace=namespaces.NP)
+        self.graph.bind(prefix="dcterms", namespace=namespaces.DCTERMS)
+        self.graph.bind(prefix="rdfg", namespace=namespaces.RDFG)
 
     @functools.cached_property
     def context_paths(self) -> Iterable[Path]:
         """Compile list of context files."""
-        directory = Path(__file__).parent / 'data'
+        directory = Path(__file__).parent / "data"
 
-        yield directory / 'context.yaml'
+        yield directory / "context.yaml"
 
         for plugin in self.plugins:
-            if path := plugin.context_path:
+            if path := plugin.context_path:  # noqa: WPS332
                 yield path
 
     def add_files_from_plugins(self):
@@ -244,13 +331,13 @@ class Iolanta:   # noqa: WPS214
                 self.add(plugin.data_files)
             except Exception as error:
                 self.logger.error(
-                    f'Cannot load {plugin} plugin data files: {error}',
+                    f"Cannot load {plugin} plugin data files: {error}",
                 )
 
     @property
     def facet_classes(self):
         """Get all registered facet classes."""
-        return entry_points.plugins('iolanta.facets')
+        return entry_points.plugins("iolanta.facets")
 
     def add_files_from_facets(self):
         """Add files from all registered facets to the graph."""
@@ -258,7 +345,7 @@ class Iolanta:   # noqa: WPS214
             try:
                 self.add(facet_class.META)
             except AttributeError:
-                pass
+                pass  # noqa: WPS420
 
     def __post_init__(self):
         """Initialize after instance creation."""
@@ -278,11 +365,11 @@ class Iolanta:   # noqa: WPS214
 
         if not as_datatype:
             raise ValueError(
-                f'Please provide the datatype to render {node} as.',
+                f"Please provide the datatype to render {node} as.",
             )
 
         if isinstance(as_datatype, list):
-            raise NotImplementedError('Got a list for as_datatype :(')
+            raise NotImplementedError("Got a list for as_datatype :(")
 
         found = FacetFinder(
             iolanta=self,
@@ -290,12 +377,12 @@ class Iolanta:   # noqa: WPS214
             as_datatype=as_datatype,
         ).facet_and_output_datatype
 
-        facet_class = self.facet_resolver.resolve(found['facet'])
+        facet_class = self.facet_resolver.resolve(found["facet"])
 
         facet = facet_class(
             this=node,
             iolanta=self,
-            as_datatype=found['output_datatype'],
+            as_datatype=found["output_datatype"],
         )
 
         try:
@@ -304,14 +391,18 @@ class Iolanta:   # noqa: WPS214
         except Exception as err:
             raise FacetError(
                 node=node,
-                facet_iri=found['facet'],
+                facet_iri=found["facet"],
                 error=err,
             ) from err
 
     def node_as_qname(self, node: Node):
         """Render node as a QName if possible."""
         qname = node_to_qname(node, self.graph)
-        return f'{qname.namespace_name}:{qname.term}' if isinstance(
-            qname,
-            ComputedQName,
-        ) else node
+        return (
+            f"{qname.namespace_name}:{qname.term}"
+            if isinstance(
+                qname,
+                ComputedQName,
+            )
+            else node
+        )

iolanta/mermaid/models.py

@@ -2,29 +2,45 @@ import enum
 import hashlib
 import re
 import textwrap
-import urllib.parse
-
-
-def escape_label(label: str) -> str:
-    """Escape a label to prevent Mermaid from interpreting URLs as markdown links."""
-    # Remove https://, http://, and www. prefixes to prevent markdown link parsing
-    return label.replace('https://', '').replace('http://', '').replace('www.', '')
+from urllib import parse as urllib_parse
 
 from documented import Documented
 from pydantic import AnyUrl, BaseModel
 from rdflib import BNode, Literal, URIRef
 
-from iolanta.models import NotLiteralNode
+from iolanta.models import NotLiteralNode  # noqa: WPS202
+
+
+def escape_label(label: str) -> str:
+    """Escape a label to prevent Mermaid from interpreting URLs as markdown links and handle quotes.
+
+    Escapes quotes in labels that will be wrapped in quotes in Mermaid syntax.
+    """
+    # Remove https://, http://, and www. prefixes to prevent markdown link parsing
+    safe_label = (
+        label.replace("https://", "").replace("http://", "").replace("www.", "")
+    )
+    # Escape quotes for use inside quoted strings in Mermaid
+    return safe_label.replace('"', r'\"')
 
 
 class Direction(enum.StrEnum):
     """Mermaid diagram direction."""
 
-    TB = 'TB'
-    LR = 'LR'
+    TB = "TB"
+    LR = "LR"
 
 
-class MermaidURINode(Documented, BaseModel, arbitrary_types_allowed=True, frozen=True):
+class MermaidScalar(Documented, BaseModel, arbitrary_types_allowed=True):
+    """Base class for Mermaid scalar elements (nodes and edges)."""
+
+    @property
+    def id(self) -> str:
+        """Get the unique identifier for this Mermaid element."""
+        raise NotImplementedError()
+
+
+class MermaidURINode(MermaidScalar, frozen=True):
     """
     {self.id}{self.maybe_title}
     click {self.id} "{self.url}"
@@ -32,29 +48,31 @@ class MermaidURINode(Documented, BaseModel, arbitrary_types_allowed=True, frozen
 
     uri: URIRef
     url: AnyUrl
-    title: str = ''
+    title: str = ""
 
     @property
     def maybe_title(self):
         if not self.title:
-            return ''
+            return ""
         # Escape URLs to prevent Mermaid from interpreting them as markdown links
         safe_title = escape_label(self.title)
         return f'("{safe_title}")'
 
     @property
     def id(self):
-        return re.sub(r'[:\/\.#()]', '_', urllib.parse.unquote(str(self.url)).strip('/'))
+        return re.sub(
+            r"[:\/\.#()]", "_", urllib_parse.unquote(str(self.url)).strip("/")
+        )
 
 
-class MermaidLiteral(Documented, BaseModel, arbitrary_types_allowed=True, frozen=True):
+class MermaidLiteral(MermaidScalar, frozen=True):
     """{self.id}[["{self.title}"]]"""
 
     literal: Literal
 
     @property
     def title(self) -> str:
-        raw_title = str(self.literal) or 'EMPTY'
+        raw_title = str(self.literal) or "EMPTY"
         # Replace quotes with safer characters for Mermaid
         return raw_title.replace('"', '"').replace("'", "'")
 
@@ -63,53 +81,53 @@ class MermaidLiteral(Documented, BaseModel, arbitrary_types_allowed=True, frozen
         # Use the lexical form of the literal, not rdflib's .value (which may be empty for typed literals),
         # to ensure different texts get distinct node IDs in Mermaid.
         value_hash = hashlib.md5(str(self.literal).encode()).hexdigest()
-        return f'Literal-{value_hash}'
+        return f"Literal-{value_hash}"
 
 
-class MermaidBlankNode(Documented, BaseModel, arbitrary_types_allowed=True):
-    """{self.id}({self.escaped_title})"""
+class MermaidBlankNode(MermaidScalar):
+    """{self.id}("{self.escaped_title}")"""
 
     node: BNode
     title: str
 
     @property
     def id(self) -> str:
-        return self.node.replace('_:', '')
-    
+        return self.node.replace("_:", "")
+
     @property
     def escaped_title(self) -> str:
-        return self.title
+        """Escape the title to prevent Mermaid parsing issues."""
+        return escape_label(self.title)
 
 
-class MermaidEdge(Documented, BaseModel, arbitrary_types_allowed=True):
+class MermaidEdge(MermaidScalar):
     """
     {self.source.id} --- {self.id}(["{self.escaped_title}"])--> {self.target.id}
     click {self.id} "{self.predicate}"
     class {self.id} predicate
     """
 
-    source: 'MermaidURINode | MermaidBlankNode | MermaidSubgraph'
-    target: 'MermaidURINode | MermaidLiteral | MermaidBlankNode | MermaidSubgraph'
+    source: "MermaidURINode | MermaidBlankNode | MermaidSubgraph"
+    target: "MermaidURINode | MermaidLiteral | MermaidBlankNode | MermaidSubgraph"
     predicate: URIRef
     title: str
 
     @property
     def id(self) -> str:
-        return hashlib.md5(f'{self.source.id}{self.predicate}{self.target.id}'.encode()).hexdigest()
+        return hashlib.md5(
+            f"{self.source.id}{self.predicate}{self.target.id}".encode()  # noqa: WPS237
+        ).hexdigest()
 
     @property
     def nodes(self):
         return [self.source, self.target]
-    
+
     @property
     def escaped_title(self) -> str:
         # Escape URLs to prevent Mermaid from interpreting them as markdown links
         return escape_label(self.title)
 
 
-MermaidScalar = MermaidLiteral | MermaidBlankNode | MermaidURINode | MermaidEdge
-
-
 class MermaidSubgraph(Documented, BaseModel, arbitrary_types_allowed=True, frozen=True):
     """
     subgraph {self.id}["{self.escaped_title}"]
@@ -117,6 +135,7 @@ class MermaidSubgraph(Documented, BaseModel, arbitrary_types_allowed=True, froze
       {self.formatted_body}
     end
     """
+
     children: list[MermaidScalar]
     uri: NotLiteralNode
     title: str
@@ -125,8 +144,8 @@ class MermaidSubgraph(Documented, BaseModel, arbitrary_types_allowed=True, froze
     @property
     def id(self):
         uri_hash = hashlib.md5(str(self.uri).encode()).hexdigest()
-        return f'subgraph_{uri_hash}'
-    
+        return f"subgraph_{uri_hash}"
+
     @property
     def escaped_title(self) -> str:
         """Escape the subgraph title to prevent markdown link parsing."""
@@ -135,8 +154,8 @@ class MermaidSubgraph(Documented, BaseModel, arbitrary_types_allowed=True, froze
     @property
     def formatted_body(self):
         return textwrap.indent(
-            '\n'.join(map(str, self.children)),
-            prefix='  ',
+            "\n".join(map(str, self.children)),
+            prefix="  ",
         )
 
 
@@ -145,14 +164,20 @@ class Diagram(Documented, BaseModel):
     graph {self.direction}
     {self.formatted_body}
       classDef predicate fill:transparent,stroke:transparent,stroke-width:0px;
+      {self.formatted_tail}
     """
 
     children: list[MermaidScalar | MermaidSubgraph]
     direction: Direction = Direction.LR
+    tail: str | None = None
+
+    @property
+    def formatted_tail(self) -> str:
+        return self.tail or ""
 
     @property
     def formatted_body(self):
         return textwrap.indent(
-            '\n'.join(map(str, self.children)),
-            prefix='  ',
+            "\n".join(map(str, self.children)),
+            prefix="  ",
         )