iolanta 2.0.8__py3-none-any.whl → 2.1.4__py3-none-any.whl

iolanta/labeled_triple_set/labeled_triple_set.py

@@ -0,0 +1,137 @@
+from pathlib import Path
+from typing import Annotated, Iterable
+from typing import Literal as TypingLiteral
+
+from pydantic import (
+    AnyUrl,
+    BaseModel,
+    Field,
+    TypeAdapter,
+    field_serializer,
+    field_validator,
+    validator,
+)
+from rdflib import BNode, Literal, Node, URIRef
+
+from iolanta import Facet
+from iolanta.models import NotLiteralNode
+from iolanta.namespaces import DATATYPES
+
+
+class WithFeedback(BaseModel):
+    feedback: Annotated[list[str], Field(default_factory=list)]
+
+
+class LabeledURI(WithFeedback, BaseModel):
+    type: TypingLiteral['uri'] = 'uri'
+    uri: AnyUrl
+    label: str
+
+    def construct_feedback(self) -> Iterable[str]:
+        if str(self.label) == str(self.uri):
+            yield (
+                'For this URI, the label is the same as the URI. We were '
+                'unable to render that URI.'
+            )
+
+
+class LabeledBlank(WithFeedback, BaseModel):
+    type: TypingLiteral['blank'] = 'blank'
+    identifier: str
+    label: str
+
+
+class LabeledLiteral(WithFeedback, BaseModel):
+    type: TypingLiteral['literal'] = 'literal'
+    value: str
+    language: str | None
+    datatype: str | None
+    label: str
+
+
+class LabeledTriple(BaseModel):
+    subject: LabeledURI | LabeledBlank
+    predicate: LabeledURI
+    object_: LabeledURI | LabeledBlank | LabeledLiteral
+
+
+def construct_uri_feedback(uri: AnyUrl, label: str) -> Iterable[str]:
+    if str(uri) == str(label):
+        yield (
+            'For this URI, the label is the same as the URI. We were '
+            'unable to render that URI.'
+        )
+
+
+def construct_blank_feedback(bnode, label) -> Iterable[str]:
+    if str(bnode) == str(label):
+        yield (
+            'For this blank node, the label is the same as the blank node. '
+            'We were unable to render that blank node.'
+        )
+
+
+def construct_literal_feedback(literal, label):
+    if label.startswith('http'):
+        yield (
+            'This RDF literal seems to be actually a URL. Good chance is '
+            'that it should not be a literal.'
+        )
+    
+    elif ':' in label[:5]:
+        yield (
+            'This RDF literal seems to be actually a QName (prefixed URI). '
+            'Good chance is that it should not be a literal.'
+        )
+
+
+class LabeledTripleSet(Facet[list[LabeledTriple]]):
+    """A set of labeled triples."""
+
+    META = Path(__file__).parent / 'data' / 'labeled_triple_set.yamlld'
+
+    def render_label(self, node: NotLiteralNode) -> str:
+        return self.render(node, as_datatype=DATATYPES.title)
+
+    def parse_term(self, term: Node):
+        match term:
+            case URIRef() as uriref:
+                uri = AnyUrl(uriref)
+                label = self.render_label(uriref)
+
+                return LabeledURI(
+                    uri=uri,
+                    label=label,
+                    feedback=list(construct_uri_feedback(uri=uri, label=label)),
+                )
+
+            case BNode() as bnode:
+                label = self.render_label(bnode)
+                return LabeledBlank(
+                    identifier=bnode,
+                    label=label,
+                    feedback=list(construct_blank_feedback(bnode=bnode, label=label)),
+                )
+
+            case Literal() as literal:
+                label = self.render_label(literal)
+                return LabeledLiteral(
+                    value=literal,
+                    language=literal.language,
+                    datatype=literal.datatype,
+                    label=label,
+                    feedback=list(construct_literal_feedback(literal=literal, label=label)),
+                )
+
+    def show(self):
+        rows = self.stored_query('triples.sparql', graph=self.this)
+        triples = [
+            LabeledTriple(
+                subject=self.parse_term(row['subject']),
+                predicate=self.parse_term(row['predicate']),
+                object_=self.parse_term(row['object']),
+            )
+            for row in rows
+        ]
+
+        return TypeAdapter(list[LabeledTriple]).dump_json(triples, indent=2).decode()

iolanta/labeled_triple_set/sparql/triples.sparql

@@ -0,0 +1,5 @@
+SELECT * WHERE {
+    GRAPH $graph {
+        ?subject ?predicate ?object .
+    }
+}

iolanta/mermaid/facet.py

@@ -0,0 +1,127 @@
+import functools
+from pathlib import Path
+from typing import Iterable
+
+import boltons
+import cachetools
+import funcy
+from boltons.cacheutils import cached, cachedmethod
+from pydantic import AnyUrl
+from rdflib import BNode, Literal, Node, URIRef
+
+from iolanta import Facet
+from iolanta.mermaid.models import (
+    Diagram,
+    MermaidBlankNode,
+    MermaidEdge,
+    MermaidLiteral,
+    MermaidScalar,
+    MermaidSubgraph,
+    MermaidURINode,
+)
+from iolanta.models import NotLiteralNode
+from iolanta.namespaces import DATATYPES
+
+
+def filter_edges(edges: Iterable[MermaidEdge]) -> Iterable[MermaidEdge]:
+    for edge in edges:
+        if isinstance(edge.target, MermaidLiteral) and edge.source.title == edge.target.title:
+            continue
+
+        yield edge
+
+
+def filter_nodes(edges: Iterable[MermaidEdge], except_uris: Iterable[NotLiteralNode]) -> Iterable[MermaidURINode | MermaidLiteral | MermaidBlankNode]:
+    nodes = [
+        node
+        for edge in edges
+        for node in edge.nodes
+    ]
+
+    literals_in_edges = {edge.target for edge in edges if isinstance(edge.target, MermaidLiteral)}
+    for node in nodes:
+        if isinstance(node, MermaidLiteral) and node not in literals_in_edges:
+            continue
+
+        if isinstance(node, MermaidURINode) and node.uri in except_uris:
+            continue
+
+        if isinstance(node, MermaidBlankNode) and node.node in except_uris:
+            continue
+
+        if isinstance(node, MermaidSubgraph):
+            continue
+
+        yield node
+
+
+class Mermaid(Facet[str]):
+    """Mermaid diagram."""
+
+    META = Path(__file__).parent / 'mermaid.yamlld'
+
+    def as_mermaid(self, node: Node):
+        match node:
+            case URIRef() as uri:
+                if uri in self.subgraph_uris:
+                    return MermaidSubgraph(children=[], uri=uri, title=self.render(uri, as_datatype=DATATYPES.title))
+
+                return MermaidURINode(uri=uri, url=AnyUrl(uri), title=self.render(uri, as_datatype=DATATYPES.title))
+            case Literal() as literal:
+                return MermaidLiteral(literal=literal)
+            case BNode() as bnode:
+                return MermaidBlankNode(node=bnode, title=self.render(bnode, as_datatype=DATATYPES.title))
+            case unknown:
+                unknown_type = type(unknown)
+                raise ValueError(f'Unknown something: {unknown} ({unknown_type})')
+
+    def construct_mermaid_for_graph(self, graph: URIRef) -> Iterable[MermaidScalar]:
+        """Render graph as mermaid."""
+        rows = self.stored_query('graph.sparql', this=graph)
+        edges = [
+            MermaidEdge(
+                source=self.as_mermaid(row['s']),
+                target=self.as_mermaid(row['o']),
+                title=self.render(row['p'], as_datatype=DATATYPES.title),
+                predicate=row['p'],
+            ) for row in rows
+        ]
+
+        edges = list(filter_edges(edges))
+        nodes = list(
+            filter_nodes(
+                edges=edges,
+                except_uris=self.subgraph_uris,
+            ),
+        )
+
+        return *nodes, *edges
+
+    @functools.cached_property
+    def subgraph_uris(self) -> set[NotLiteralNode]:
+        return set(
+            funcy.pluck(
+                'subgraph',
+                self.stored_query('subgraphs.sparql', this=self.this),
+            ),
+        )
+
+    def construct_mermaid_subgraphs(self) -> Iterable[MermaidSubgraph]:
+        for subgraph_uri in self.subgraph_uris:
+            children = list(self.construct_mermaid_for_graph(subgraph_uri))
+            if children:
+                title = self.render(subgraph_uri, as_datatype=DATATYPES.title)
+                yield MermaidSubgraph(
+                    children=children,
+                    uri=subgraph_uri,
+                    title=title,
+                )
+
+    def show(self) -> str:
+        """Render mermaid diagram."""
+        direct_children = self.construct_mermaid_for_graph(self.this)
+        subgraphs = self.construct_mermaid_subgraphs()
+        return str(Diagram(children=[*direct_children, *subgraphs]))
+
+
+

iolanta/mermaid/mermaid.yamlld

@@ -0,0 +1,42 @@
+"@context":
+  "@import": https://json-ld.org/contexts/dollar-convenience.jsonld
+  vann: https://purl.org/vocab/vann/
+  foaf: https://xmlns.com/foaf/0.1/
+  owl: https://www.w3.org/2002/07/owl#
+  iolanta: https://iolanta.tech/
+  rdfs: "https://www.w3.org/2000/01/rdf-schema#"
+  rdf: https://www.w3.org/1999/02/22-rdf-syntax-ns#
+  dcterms: https://purl.org/dc/terms/
+  dcam: https://purl.org/dc/dcam/
+
+  iolanta:outputs:
+    "@type": "@id"
+
+  iolanta:when-no-facet-found:
+    "@type": "@id"
+
+  $: rdfs:label
+  →:
+    "@type": "@id"
+    "@id": iolanta:outputs
+
+  ⊆:
+    "@type": "@id"
+    "@id": rdfs:subClassOf
+
+  ⪯:
+    "@type": "@id"
+    "@id": iolanta:is-preferred-over
+
+  ↦: iolanta:matches
+  iolanta:hasDefaultFacet:
+    "@type": "@id"
+
+$id: pkg:pypi/iolanta#mermaid-graph
+$: Mermaid Graph
+→:
+  $id: https://iolanta.tech/datatypes/mermaid
+  $: Mermaid
+↦:
+  - ASK WHERE { GRAPH $this { ?s ?p ?o } }
+  - ASK WHERE { $this iolanta:has-sub-graph ?subgraph }

iolanta/mermaid/models.py

@@ -0,0 +1,156 @@
+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 documented import Documented
+from pydantic import AnyUrl, BaseModel
+from rdflib import BNode, Literal, URIRef
+
+from iolanta.models import NotLiteralNode
+
+
+class Direction(enum.StrEnum):
+    """Mermaid diagram direction."""
+
+    TB = 'TB'
+    LR = 'LR'
+
+
+class MermaidURINode(Documented, BaseModel, arbitrary_types_allowed=True, frozen=True):
+    """
+    {self.id}{self.maybe_title}
+    click {self.id} "{self.url}"
+    """
+
+    uri: URIRef
+    url: AnyUrl
+    title: str = ''
+
+    @property
+    def maybe_title(self):
+        if not self.title:
+            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('/'))
+
+
+class MermaidLiteral(Documented, BaseModel, arbitrary_types_allowed=True, frozen=True):
+    """{self.id}[["{self.title}"]]"""
+
+    literal: Literal
+
+    @property
+    def title(self) -> str:
+        raw_title = str(self.literal) or 'EMPTY'
+        # Replace quotes with safer characters for Mermaid
+        return raw_title.replace('"', '"').replace("'", "'")
+
+    @property
+    def id(self) -> str:
+        value_hash = hashlib.md5(str(self.literal.value).encode()).hexdigest()
+        return f'Literal-{value_hash}'
+
+
+class MermaidBlankNode(Documented, BaseModel, arbitrary_types_allowed=True):
+    """{self.id}({self.escaped_title})"""
+
+    node: BNode
+    title: str
+
+    @property
+    def id(self) -> str:
+        return self.node.replace('_:', '')
+    
+    @property
+    def escaped_title(self) -> str:
+        return self.title
+
+
+class MermaidEdge(Documented, BaseModel, arbitrary_types_allowed=True):
+    """
+    {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'
+    predicate: URIRef
+    title: str
+
+    @property
+    def id(self) -> str:
+        return hashlib.md5(f'{self.source.id}{self.predicate}{self.target.id}'.encode()).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}"]
+      direction {self.direction}
+      {self.formatted_body}
+    end
+    """
+    children: list[MermaidScalar]
+    uri: NotLiteralNode
+    title: str
+    direction: Direction = Direction.LR
+
+    @property
+    def id(self):
+        uri_hash = hashlib.md5(str(self.uri).encode()).hexdigest()
+        return f'subgraph_{uri_hash}'
+    
+    @property
+    def escaped_title(self) -> str:
+        """Escape the subgraph title to prevent markdown link parsing."""
+        return escape_label(self.title)
+
+    @property
+    def formatted_body(self):
+        return textwrap.indent(
+            '\n'.join(map(str, self.children)),
+            prefix='  ',
+        )
+
+
+class Diagram(Documented, BaseModel):
+    """
+    graph {self.direction}
+    {self.formatted_body}
+      classDef predicate fill:none,stroke:none,stroke-width:0px;
+    """
+
+    children: list[MermaidScalar | MermaidSubgraph]
+    direction: Direction = Direction.LR
+
+    @property
+    def formatted_body(self):
+        return textwrap.indent(
+            '\n'.join(map(str, self.children)),
+            prefix='  ',
+        )

iolanta/mermaid/sparql/graph.sparql

@@ -0,0 +1,5 @@
+SELECT * WHERE {
+    GRAPH $this {
+        ?s ?p ?o .
+    }
+}

iolanta/mermaid/sparql/subgraphs.sparql

@@ -0,0 +1,3 @@
+SELECT ?subgraph WHERE {
+    $this iolanta:has-sub-graph ?subgraph .
+}

iolanta/namespaces.py

@@ -3,7 +3,7 @@ import rdflib
 LOCAL = rdflib.Namespace('local:')
 IOLANTA = rdflib.Namespace('https://iolanta.tech/')
 DATATYPES = rdflib.Namespace('https://iolanta.tech/datatypes/')
-PYTHON = rdflib.Namespace('python://')
+IOLANTA_FACETS = rdflib.Namespace('pkg:pypi/iolanta#')
 NP = rdflib.Namespace('https://www.nanopub.org/nschema#')
 RDFG = rdflib.Namespace('https://www.w3.org/2004/03/trix/rdfg-1/')
 SDO = rdflib.SDO

iolanta/resolvers/base.py

@@ -8,6 +8,7 @@ from iolanta.facets.facet import Facet
 
 class Resolver:
     """Resolve facet IRIs into classes."""
+
     @abstractmethod
-    def __getitem__(self, facet_iri: URIRef) -> Type[Facet]:
+    def resolve(self, uri: URIRef) -> Type[Facet]:
         """Find a resolver by IRI."""

iolanta/resolvers/dispatch.py

@@ -0,0 +1,41 @@
+from typing import Type
+
+from rdflib import URIRef
+from yarl import URL
+
+from iolanta import Facet
+from iolanta.resolvers.base import Resolver
+
+
+class SchemeDispatchResolver(Resolver):
+    """
+    A resolver that dispatches to other resolvers based on URI scheme.
+
+    For example, 'pkg:' URIs are handled by PyPIResolver, while
+    'python:' URIs are handled by PythonImportResolver.
+    """
+
+    def __init__(self, **resolver_by_scheme: Type[Resolver]):
+        """
+        Initialize with a mapping of URI schemes to resolver classes.
+
+        Args:
+            **resolver_by_scheme: Mapping of URI schemes to resolver classes.
+                For example: python=PythonImportResolver.
+        """
+        self.resolver_by_scheme = resolver_by_scheme
+
+    def resolve(self, uri: URIRef) -> Type[Facet]:
+        """
+        Find a resolver by IRI, dispatching to the appropriate scheme handler.
+
+        Args:
+            uri: The URI to resolve.
+
+        Returns:
+            Facet class resolved by the appropriate scheme handler.
+        """
+        url = URL(uri)
+        resolver_class = self.resolver_by_scheme[url.scheme]
+        resolver = resolver_class()
+        return resolver.resolve(uri)

iolanta/resolvers/pypi.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import re
+from importlib import metadata
+from typing import Type
+
+from packageurl import PackageURL
+from rdflib import URIRef
+
+from iolanta import Facet
+from iolanta.resolvers.base import Resolver
+
+ENTRY_POINT_GROUP = 'iolanta.facets'
+
+
+def _norm(name: str) -> str:
+    """Normalize package name by replacing common separators with dashes."""
+    return re.sub('[-_.]+', '-', name).lower()
+
+
+class MissingFacetError(RuntimeError):
+    """Raised when a required facet is not found in the installed packages."""
+
+
+class PyPIResolver(Resolver):
+    """Resolve facet IRIs into classes from PyPI packages."""
+
+    def resolve(self, uri: URIRef) -> Type[Facet]:
+        """Find and load a Facet class from a PyPI package."""
+        dist_name, facet_name = self._get_package_info(uri)
+        dist = self._get_distribution(dist_name, facet_name)
+        entry_point = self._find_facet_entry_point(dist, facet_name)
+        facet_class = entry_point.load()
+        self._validate_facet_class(
+            facet_class=facet_class,
+            facet_name=facet_name,
+            dist_name=dist.metadata['Name'],
+        )
+        return facet_class
+
+    def _get_package_info(self, uri: URIRef) -> tuple[str, str]:
+        """Extract and validate package information from URI."""
+        package_url = PackageURL.from_string(str(uri))
+        if package_url.type != 'pypi':
+            raise NotImplementedError(f'{package_url.type} is not supported')
+
+        dist_name = _norm(package_url.name or '')
+        facet_name = package_url.subpath
+
+        if not dist_name or not facet_name:
+            raise ValueError('PURL must be pkg:pypi/<dist>#<FacetName>')
+
+        return dist_name, facet_name
+
+    def _get_distribution(
+        self,
+        dist_name: str,
+        facet_name: str,
+    ) -> metadata.Distribution:
+        """Get package distribution and verify it exists."""
+        try:
+            return metadata.distribution(dist_name)
+        except metadata.PackageNotFoundError as exc:
+            raise MissingFacetError(
+                f'This page requires `{dist_name}` (facet `{facet_name}`). '
+                f'Install with: pip install "{dist_name}"',
+            ) from exc
+
+    def _find_facet_entry_point(
+        self,
+        dist: metadata.Distribution,
+        facet_name: str,
+    ) -> metadata.EntryPoint:
+        """Find the facet entry point in the distribution."""
+        matching_entry_points = [
+            entry_point
+            for entry_point in dist.entry_points
+            if (
+                entry_point.group == ENTRY_POINT_GROUP
+                and entry_point.name == facet_name
+            )
+        ]
+
+        if not matching_entry_points:
+            dist_name = dist.metadata['Name']
+            msg = (
+                f'Facet `{facet_name}` not found in `{dist_name}` '
+                f'{dist.version}. Ensure it exposes entry point '
+                f'`{ENTRY_POINT_GROUP}` named `{facet_name}`.'
+            )
+            raise MissingFacetError(msg)
+
+        return matching_entry_points[0]
+
+    def _validate_facet_class(
+        self,
+        facet_class: Type[Facet],
+        facet_name: str,
+        dist_name: str,
+    ) -> None:
+        """Validate that the loaded class is a Facet subclass."""
+        if not issubclass(facet_class, Facet):
+            raise TypeError(
+                f'Entry point `{facet_name}` in `{dist_name}` '
+                'is not a subclass of iolanta.Facet',
+            )