xandergraph 0.1.0__py3-none-any.whl

xandergraph/__init__.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+Package definitions for the `xandergraph` library.
+see copyright/license https://github.com/DerwenAI/xandergraph/README.md
+"""
+
+from .kg import KnowledgeGraph
+from .ottr import OttrGenerator, OttrInstances
+

xandergraph/kg.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+KnowledgeGraph definitions.
+see copyright/license https://github.com/DerwenAI/xandergraph/README.md
+"""
+
+import pathlib
+
+import pyshacl
+import rdflib
+
+from .ottr import OttrGenerator, OttrInstances
+
+
+class KnowledgeGraph:
+    """
+Represents a knowledge graph, with accessors for both the `RDFlib`
+semantic graph and the `NetworkX` property graph.
+    """
+    def __init__ (
+        self,
+        *,
+        ns: dict[ str, str ] = {},
+        ) -> None:
+        """
+Constructor.
+        """
+        self.graph: rdflib.Graph = rdflib.Graph()
+
+        for prefix, ns_uri in ns.items():
+            self.graph.bind(prefix, rdflib.Namespace(ns_uri))
+
+        self.ottr_generator: OttrGenerator = OttrGenerator()
+
+
+    def load_stottr (
+        self,
+        stottr_path: pathlib.Path,
+        ) -> rdflib.Graph:
+        """
+Define and load the OTTR templates.
+        """
+        with open(stottr_path, "r", encoding = "utf-8") as fp:
+            stottr_template: str = fp.read().strip()
+
+            self.ottr_generator.load_templates(
+                stottr_template,
+                format = "stottr",
+            )
+
+
+    def gen_ottr_rdf (
+        self,
+        rdf_data: str,
+        ) -> rdflib.Graph:
+        """
+Generate RDF triples based on applying the given text data to the
+loaded OTTR templates.
+        """
+        instances: OttrInstances = self.ottr_generator.instanciate(
+            rdf_data,
+            format = "stottr",
+        )
+
+        for s, p, o in instances.execute(as_nt = False):
+            self.graph.add((s, p, o))
+
+
+    def run_shacl (
+        self,
+        data_file: str,
+        shacl_file: str,
+        onto_file: str,
+        *,
+        inference: str = "rdfs",
+        debug: bool = False,
+        ) -> tuple[ bool, rdflib.Graph, str ]:
+        """
+This wrapper calls `pySHACL`, a pure Python module which allows for
+validating RDF graphs against Shapes Constraint Language (SHACL) shape
+constraint rules.
+        """
+        return pyshacl.validate(
+            data_file,
+            shacl_graph = shacl_file,
+            ont_graph = onto_file,
+            inference = inference,
+            debug = debug,
+            abort_on_first = False,
+            allow_infos = False,
+            allow_warnings = False,
+            meta_shacl = False,
+            advanced = False,
+            js = False,
+        )

xandergraph/ottr/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Thomas Minier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xandergraph/ottr/README.md

@@ -0,0 +1,92 @@
+# pyOTTR
+[![Build Status](https://travis-ci.com/Callidon/pyOTTR.svg?branch=master)](https://travis-ci.com/Callidon/pyOTTR)
+
+Manipulate [OTTR Reasonable Ontology Templates](http://ottr.xyz/) in Python.
+
+[Package documentation](https://callidon.github.io/pyOTTR)
+
+[OTTR documentation](http://ottr.xyz/)
+
+:white_check_mark: **Supported features:**
+* [Definition and execution of templates](http://spec.ottr.xyz/pOTTR/0.1/01-basics.html#2_Templates_and_Instances) in the [stOTTR syntax](http://spec.ottr.xyz/stOTTR/0.1/)
+* [Nesting templates](http://spec.ottr.xyz/pOTTR/0.1/01-basics.html#3_Nesting_templates)
+* [Type checking](http://spec.ottr.xyz/pOTTR/0.1/01-basics.html#4_Types)
+* [Non blank](http://spec.ottr.xyz/pOTTR/0.1/01-basics.html#5_NonBlank), [Optional](http://spec.ottr.xyz/pOTTR/0.1/01-basics.html#6_Optionals_and_None) and [default values](http://spec.ottr.xyz/pOTTR/0.1/01-basics.html#7_Default_values) for template parameters.
+* *RDF and RDFS templates* from the [OTTR template library](http://tpl.ottr.xyz/) are loaded by default.
+
+:wrench: **In development:**
+* [Expansion modes](http://spec.ottr.xyz/pOTTR/0.1/01-basics.html#8_Expansion_modes)
+* Support for [OWL templates](http://tpl.ottr.xyz/owl/) from the template library
+
+# Installation
+
+## Using pip (recommended)
+
+```
+pip install ottr
+```
+
+## Manual installation
+
+**Requirement:** [poetry](https://python-poetry.org/) (v0.12 or higher).
+
+```
+git clone https://github.com/Callidon/pyOTTR.git
+cd pyOTTR/
+poetry install
+```
+
+# Getting started
+
+The main class to manipulate is `OttrGenerator`, which is used to load OTTR templates and expand template instances.
+So, in practice, you only need to create a new generator, load some templates and then execute your instances to produce RDF triples.
+Otherwise, everything else is done using classic OTTR syntax!
+
+By default, **all templates** from the [OTTR template library](http://tpl.ottr.xyz/) are loaded when the generator is created.
+
+```python
+# an OttrGenerator is used to load templates and expand instances
+
+import ottr
+
+template: str = """
+@prefix ex: <http://example.org#> .
+
+ex:FirstName [ ottr:IRI ?uri, ?firstName ] :: {
+  ottr:Triple ( ?uri, foaf:firstName, ?firstName )
+} .
+
+ex:Person[ ?firstName ] :: {
+  ottr:Triple ( _:person, rdf:type, foaf:Person ),
+  ex:FirstName ( _:person, ?firstName )
+} .
+""".strip()
+
+# load a simple OTTR template definition
+
+generator: ottr.OttrGenerator = ottr.OttrGenerator()
+generator.load_templates(template)
+
+# parse and prepare an instance for execution
+
+rdf_data: str = """
+@prefix ex: <http://example.org#> .
+
+ex:Person("Ann") .
+""".strip()
+
+instances: ottr.generator.OttrInstances = generator.instanciate(rdf_data)
+
+# execute the instance, which yield RDF triples
+# the following prints (_:person0, rdf:type, foaf:Person) and (_:person0, foaf:firstName, "Ann")
+
+for s, p, o in instances.execute(as_nt = True):
+    print("# ----- RDF triple ----- #")
+    print((s, p, o)
+```
+
+
+## Addendum
+
+Updated for more recent releases of `RDFlib` by [Derwen](https://derwen.ai)
+since the source did not appear to have been maintained for ~7 years.

xandergraph/ottr/__init__.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+Package definitions for the `pyOTTR` library.
+see copyright/license https://github.com/DerwenAI/xandergraph/README.md
+"""
+
+from .generator import OttrGenerator, OttrInstances

xandergraph/ottr/base/argument.py

@@ -0,0 +1,145 @@
+# argument.py
+# Author: Thomas MINIER - MIT License 2019-2020
+
+from abc import ABC, abstractmethod
+from typing import Iterable, Tuple
+
+from rdflib import BNode, URIRef
+
+from ... ottr.base.utils import OTTR
+from ... ottr.types import ExpansionResults, InputBindings, Term
+
+
+class InstanceArgument(ABC):
+    """An abstract instance argument, which corresponds to the parameter of a template.
+
+    Args:
+      * value: Argument's value.
+      * position: Argument's position in the template's parameters list.
+    """
+
+    def __init__(self, value: Term, position: int):
+        super(InstanceArgument, self).__init__()
+        self._value = value
+        self._position = position
+
+    def __str__(self) -> str:
+        return f"InstanceArgument({self._value}, {self._position})"
+
+    def __repr__(self) -> str:
+        return self.__str__()
+
+    @property
+    def value(self) -> Term:
+        """The argument's value"""
+        return self._value
+
+    @property
+    def position(self) -> int:
+        """The argument's position in the template's parameters list"""
+        return self._position
+
+    @property
+    def is_bound(self) -> bool:
+        """Return True if the argument is bound (it is not a Variable), False otherwise"""
+        return False
+
+    @abstractmethod
+    def evaluate(self, bindings: InputBindings = dict(), bnode_suffix: Tuple[int, int] = (0, 0), as_nt: bool = False) -> Iterable[ExpansionResults]:
+        """Evaluate the argument using an optional set of bindings.
+
+        Args:
+          * bindings: set of bindings used for evaluation.
+          * bnode_suffix: Pair of suffixes used for creating unique blank nodes.
+          * as_nt: True if the RDF triples produced should be in n-triples format, False to use the rdflib format.
+
+        Yields:
+          RDF triples, in rdflib or n-triples format.
+        """
+        pass
+
+
+class ConcreteArgument(InstanceArgument):
+    """An argument that evaluates to a constant RDF term, i.e., a RDF term.
+
+    Args:
+      * value: Argument's value.
+      * position: Argument's position in the template's parameters list.
+    """
+
+    def __init__(self, value: Term, position: int):
+        super(ConcreteArgument, self).__init__(value, position)
+
+    def __str__(self) -> str:
+        return f"ConcreteArgument({self._value}, {self._position})"
+
+    @property
+    def is_bound(self) -> bool:
+        return True
+
+    def evaluate(self, bindings: InputBindings = dict(), bnode_suffix: Tuple[int, int] = (0, 0), as_nt: bool = False) -> Iterable[ExpansionResults]:
+        """Evaluate the argument using an optional set of bindings.
+
+        Args:
+          * bindings: set of bindings used for evaluation.
+          * bnode_suffix: Pair of suffixes used for creating unique blank nodes.
+          * as_nt: True if the RDF triples produced should be in n-triples format, False to use the rdflib format.
+
+        Yields:
+          RDF triples, in rdflib or n-triples format.
+        """
+        term = self._value
+        if type(term) == BNode and bnode_suffix is not None:
+            term = BNode(f"{term}_{bnode_suffix[0]}_{bnode_suffix[1]}")
+        return term.n3() if as_nt else term
+
+
+class URIArgument(ConcreteArgument):
+    """A ConcreteArgument that always evaluates to an URI.
+
+    Args:
+      * value: Argument's value (an URI).
+      * position: Argument's position in the template's parameters list.
+    """
+
+    def __init__(self, uri: URIRef, position: int):
+        super(URIArgument, self).__init__(URIRef(uri), position)
+
+    def __str__(self) -> str:
+        return f"URIArgument({self._value}, {self._position})"
+
+
+class VariableArgument(InstanceArgument):
+    """A variable argument, i.e., a SPARQL variable.
+
+    Args:
+      * value: Argument's value (a SPARQL variable).
+      * position: Argument's position in the template's parameters list.
+    """
+
+    def __init__(self, value: Term, position: int):
+        super(VariableArgument, self).__init__(value, position)
+
+    def __str__(self) -> str:
+        return f"VariableArgument({self._value}, {self._position})"
+
+    def evaluate(self, bindings: InputBindings = dict(), bnode_suffix: Tuple[int, int] = (0, 0), as_nt: bool = False) -> Iterable[ExpansionResults]:
+        """Evaluate the argument using an optional set of bindings.
+
+        Args:
+          * bindings: set of bindings used for evaluation.
+          * bnode_suffix: Pair of suffixes used for creating unique blank nodes.
+          * as_nt: True if the RDF triples produced should be in n-triples format, False to use the rdflib format.
+
+        Yields:
+          RDF triples, in rdflib or n-triples format.
+        """
+        if self._value in bindings:
+            term = bindings[self._value]
+
+            if type(term) == BNode and bnode_suffix is not None:
+                term = BNode(f"{term}_{bnode_suffix[0]}_{bnode_suffix[1]}")
+
+            return term.n3() if as_nt else term
+
+        return OTTR.none

xandergraph/ottr/base/base_templates.py

@@ -0,0 +1,54 @@
+# base_templates.py
+# Author: Thomas MINIER - MIT License 2019-2020
+from typing import Dict, Iterable, Tuple
+
+from rdflib import URIRef
+
+from ... ottr.base.argument import InstanceArgument
+from ... ottr.base.template import AbstractTemplate
+from ... ottr.base.utils import OTTR_TRIPLE_URI
+from ... ottr.types import ExpansionResults, InputBindings
+
+
+class OttrTriple(AbstractTemplate):
+    """The default ottr:Triple base template, which expand to a RDF triple.
+
+    Args:
+      * subject_arg: Subject argument of the template instance.
+      * predicate_arg: Predicate argument of the template instance.
+      * object_arg: Object argument of the template instance.
+    """
+
+    def __init__(self, subject_arg: InstanceArgument, predicate_arg: InstanceArgument, object_arg: InstanceArgument):
+        super(OttrTriple, self).__init__(OTTR_TRIPLE_URI)
+        self._subject_arg = subject_arg
+        self._predicate_arg = predicate_arg
+        self._object_arg = object_arg
+
+    def __str__(self) -> str:
+        return f"ottr:Triple ({self._subject_arg}, {self._predicate_arg}, {self._object_arg}) :: BASE ."
+
+    def __repr__(self) -> str:
+        return self.__str__()
+
+    def is_base(self) -> bool:
+        """Returns True if the template is a base template, False otherwise"""
+        return True
+
+    def expand(self, arguments: InputBindings, all_templates: Dict[URIRef, AbstractTemplate], bnode_suffix: Tuple[int, int] = (0, 0), as_nt: bool = False) -> Iterable[ExpansionResults]:
+        """Expands the template and yields a single RDF triple.
+
+        Args:
+          * arguments: Template instantation arguments.
+          * all_templates: Map of all templates known at expansion times.
+          * bnode_suffix: Pair of suffixes used for creating unique blank nodes.
+          * as_nt: True if the RDF triples produced should be in n-triples format, False to use the rdflib format.
+
+        Yields:
+          A RDF triple, in rdflib or n-triples format.
+        """
+        yield (
+            self._subject_arg.evaluate(bindings=arguments, bnode_suffix=bnode_suffix, as_nt=as_nt),
+            self._predicate_arg.evaluate(bindings=arguments, bnode_suffix=bnode_suffix, as_nt=as_nt),
+            self._object_arg.evaluate(bindings=arguments, bnode_suffix=bnode_suffix, as_nt=as_nt)
+        )

xandergraph/ottr/base/expansion.py

@@ -0,0 +1,50 @@
+# expansion.py
+# Author: Thomas MINIER - MIT License 2019-2020
+
+from typing import Dict, Iterable, Tuple
+
+from rdflib import URIRef, Variable
+
+from ... ottr.base.template import AbstractTemplate
+from ... ottr.types import ExpansionResults, InputBindings
+
+
+class CrossTemplate(AbstractTemplate):
+    """A CrossTemplate expands a template instance using the 'cross' expansion mode.
+
+    Args:
+      * name: Template's name.
+      * instance: Template instance to expand with the 'cross' expansion mode.
+      * cross_variable: Variable which binds to the list of arguments for the cross-operator.
+    """
+
+    def __init__(self, name: URIRef, instance: AbstractTemplate, cross_variable: Variable):
+        super(CrossTemplate, self).__init__(name)
+        self._inner_instance = instance
+        self._cross_variable = cross_variable
+
+    def expand(self, arguments: InputBindings, all_templates: Dict[URIRef, AbstractTemplate], bnode_suffix: Tuple[int, int] = (0, 0), as_nt: bool = False) -> Iterable[ExpansionResults]:
+        """Expands the template and yields RDF triples.
+
+        Args:
+          * arguments: Template instantation arguments.
+          * all_templates: Map of all templates known at expansion times.
+          * bnode_suffix: Pair of suffixes used for creating unique blank nodes.
+          * as_nt: True if the RDF triples produced should be in n-triples format, False to use the rdflib format.
+
+        Yields:
+          RDF triples, in rdflib or n-triples format.
+        """
+        # assert that the cross variable is found in the arguments
+        if self._cross_variable in arguments:
+            # invoke inner instance with each value of the list variable
+            for value in arguments[self._cross_variable]:
+                # copy arguments and inject the local value for the cross variable
+                local_args: InputBindings = dict()
+                for k, v in arguments.items():
+                    if k == self._cross_variable:
+                        local_args[k] = value
+                    else:
+                        local_args[k] = v
+                # recursively invoke the inner instance with the new set of arguments
+                yield from self._inner_instance.expand(local_args, all_templates, bnode_suffix=bnode_suffix, as_nt=as_nt)