Feature support in the schema

* Type annotations
* Feature type
* Moved from_string from Schema to its own file/function
* Root predicate has a valid (not-None) range
* ROOT_... export in schema.types
* Empty as the default Schema constructor
* Schema loads some additional default symbols
* _Type instances compare along class hierarchy

4 files changed, 325 insertions, 117 deletions

diff --git a/bsfs/schema/__init__.py b/bsfs/schema/__init__.py
index ad4d456..dc24313 100644
--- a/bsfs/schema/__init__.py
+++ b/bsfs/schema/__init__.py
@@ -9,7 +9,8 @@ import typing
 
 # inner-module imports
 from .schema import Schema
-from .types import Literal, Node, Predicate
+from .serialize import from_string, to_string
+from .types import Literal, Node, Predicate, _Vertex # FIXME: _Vertex
 
 # exports
 __all__: typing.Sequence[str] = (
@@ -17,6 +18,8 @@ __all__: typing.Sequence[str] = (
     'Node',
     'Predicate',
     'Schema',
+    'from_string',
+    'to_string',
     )
 
 ## EOF ##
diff --git a/bsfs/schema/schema.py b/bsfs/schema/schema.py
index c5d4571..1c4c807 100644
--- a/bsfs/schema/schema.py
+++ b/bsfs/schema/schema.py
@@ -51,11 +51,13 @@ class Schema():
 
     def __init__(
             self,
-            predicates: typing.Iterable[types.Predicate],
+            predicates: typing.Optional[typing.Iterable[types.Predicate]] = None,
             nodes: typing.Optional[typing.Iterable[types.Node]] = None,
             literals: typing.Optional[typing.Iterable[types.Literal]] = None,
             ):
         # materialize arguments
+        if predicates is None:
+            predicates = set()
         if nodes is None:
             nodes = set()
         if literals is None:
@@ -63,24 +65,36 @@ class Schema():
         nodes = set(nodes)
         literals = set(literals)
         predicates = set(predicates)
+
+        # add root types to the schema
+        nodes.add(types.ROOT_NODE)
+        literals.add(types.ROOT_LITERAL)
+        predicates.add(types.ROOT_PREDICATE)
+        # add minimally necessary types to the schema
+        literals.add(types.ROOT_NUMBER)
+        predicates.add(types.ROOT_FEATURE)
+
         # include parents in predicates set
         # TODO: review type annotations and ignores for python >= 3.11 (parents is _Type but should be typing.Self)
         predicates |= {par for pred in predicates for par in pred.parents()} # type: ignore [misc]
         # include predicate domain in nodes set
         nodes |= {pred.domain for pred in predicates}
         # include predicate range in nodes and literals sets
-        prange = {pred.range for pred in predicates if pred.range is not None}
+        prange = {pred.range for pred in predicates}
         nodes |= {vert for vert in prange if isinstance(vert, types.Node)}
         literals |= {vert for vert in prange if isinstance(vert, types.Literal)}
+        # NOTE: ROOT_PREDICATE has a _Vertex as range which is neither in nodes nor literals
+        # FIXME: with the ROOT_VERTEX missing, the schema is not complete anymore!
+
         # include parents in nodes and literals sets
-        # NOTE: Must be done after predicate domain/range was handled
-        # so that their parents are included as well.
+        # NOTE: Must come after predicate domain/range was handled to have their parents as well.
         nodes |= {par for node in nodes for par in node.parents()} # type: ignore [misc]
         literals |= {par for lit in literals for par in lit.parents()} # type: ignore [misc]
         # assign members
         self._nodes = {node.uri: node for node in nodes}
         self._literals = {lit.uri: lit for lit in literals}
         self._predicates = {pred.uri: pred for pred in predicates}
+
         # verify unique uris
         if len(nodes) != len(self._nodes):
             raise errors.ConsistencyError('inconsistent nodes')
@@ -214,6 +228,7 @@ class Schema():
         >>> Schema.Union([a, b, c])
 
         """
+        # FIXME: copy type annotations?
         if len(args) == 0:
             raise TypeError('Schema.Union requires at least one argument (Schema or Iterable)')
         if isinstance(args[0], cls): # args is sequence of Schema instances
@@ -295,92 +310,4 @@ class Schema():
         """Return the Literal matching the *uri*."""
         return self._literals[uri]
 
-
-    ## constructors ##
-
-
-    @classmethod
-    def Empty(cls) -> 'Schema': # pylint: disable=invalid-name # capitalized classmethod
-        """Return a minimal Schema."""
-        node = types.Node(ns.bsfs.Node, None)
-        literal = types.Literal(ns.bsfs.Literal, None)
-        predicate = types.Predicate(
-            uri=ns.bsfs.Predicate,
-            parent=None,
-            domain=node,
-            range=None,
-            unique=False,
-            )
-        return cls((predicate, ), (node, ), (literal, ))
-
-
-    @classmethod
-    def from_string(cls, schema: str) -> 'Schema': # pylint: disable=invalid-name # capitalized classmethod
-        """Load and return a Schema from a string."""
-        # parse string into rdf graph
-        graph = rdflib.Graph()
-        graph.parse(data=schema, format='turtle')
-
-        def _fetch_hierarchically(factory, curr):
-            # emit current node
-            yield curr
-            # walk through childs
-            for child in graph.subjects(rdflib.URIRef(ns.rdfs.subClassOf), rdflib.URIRef(curr.uri)):
-                # convert to URI
-                child = URI(child)
-                # check circular dependency
-                if child == curr.uri or child in {node.uri for node in curr.parents()}:
-                    raise errors.ConsistencyError('circular dependency')
-                # recurse and emit (sub*)childs
-                yield from _fetch_hierarchically(factory, factory(child, curr))
-
-        # fetch nodes
-        nodes = set(_fetch_hierarchically(types.Node, types.Node(ns.bsfs.Node, None)))
-        nodes_lut = {node.uri: node for node in nodes}
-        if len(nodes_lut) != len(nodes):
-            raise errors.ConsistencyError('inconsistent nodes')
-
-        # fetch literals
-        literals = set(_fetch_hierarchically(types.Literal, types.Literal(ns.bsfs.Literal, None)))
-        literals_lut = {lit.uri: lit for lit in literals}
-        if len(literals_lut) != len(literals):
-            raise errors.ConsistencyError('inconsistent literals')
-
-        # fetch predicates
-        def build_predicate(uri, parent):
-            uri = rdflib.URIRef(uri)
-            # get domain
-            domains = set(graph.objects(uri, rdflib.RDFS.domain))
-            if len(domains) != 1:
-                raise errors.ConsistencyError(f'inconsistent domain: {domains}')
-            dom = nodes_lut.get(next(iter(domains)))
-            if dom is None:
-                raise errors.ConsistencyError('missing domain')
-            # get range
-            ranges = set(graph.objects(uri, rdflib.RDFS.range))
-            if len(ranges) != 1:
-                raise errors.ConsistencyError(f'inconsistent range: {ranges}')
-            rng = next(iter(ranges))
-            rng = nodes_lut.get(rng, literals_lut.get(rng))
-            if rng is None:
-                raise errors.ConsistencyError('missing range')
-            # get unique flag
-            uniques = set(graph.objects(uri, rdflib.URIRef(ns.bsfs.unique)))
-            if len(uniques) != 1:
-                raise errors.ConsistencyError(f'inconsistent unique flags: {uniques}')
-            unique = bool(next(iter(uniques)))
-            # build Predicate
-            return types.Predicate(URI(uri), parent, dom, rng, unique)
-
-        root_predicate = types.Predicate(
-            uri=ns.bsfs.Predicate,
-            parent=None,
-            domain=nodes_lut[ns.bsfs.Node],
-            range=None, # FIXME: Unclear how to handle this! Can be either a Literal or a Node
-            unique=False,
-            )
-        predicates = _fetch_hierarchically(build_predicate, root_predicate)
-        # return Schema
-        return cls(predicates, nodes, literals)
-
 ## EOF ##
diff --git a/bsfs/schema/serialize.py b/bsfs/schema/serialize.py
new file mode 100644
index 0000000..1222aa6
--- /dev/null
+++ b/bsfs/schema/serialize.py
@@ -0,0 +1,143 @@
+"""
+
+Part of the BlackStar filesystem (bsfs) module.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# standard imports
+from collections import abc
+import itertools
+import typing
+
+# external imports
+import rdflib
+
+# bsfs imports
+from bsfs.namespace import ns
+from bsfs.utils import errors, URI, typename
+
+# inner-module imports
+from . import types
+from . import schema
+
+# exports
+__all__: typing.Sequence[str] = (
+    'to_string',
+    'from_string',
+    )
+
+
+## code ##
+
+def from_string(schema_str: str) -> schema.Schema:
+    """Load and return a Schema from a string."""
+    # parse string into rdf graph
+    graph = rdflib.Graph()
+    graph.parse(data=schema_str, format='turtle')
+
+    # helper functions
+    def _convert(value):
+        """Convert the subject type from rdflib to a bsfs native type."""
+        if isinstance(value, rdflib.Literal):
+            return value.value
+        if isinstance(value, rdflib.URIRef):
+            return URI(value)
+        raise errors.BackendError(f'expected Literal or URIRef, found {typename(value)}')
+
+    def _fetch_hierarchically(factory, curr):
+        """Walk through a rdfs:subClassOf hierarchy, creating symbols along the way."""
+        # emit current node
+        yield curr
+        # walk through childs
+        for child in graph.subjects(rdflib.URIRef(ns.rdfs.subClassOf), rdflib.URIRef(curr.uri)):
+            # fetch annotations
+            annotations = {
+                URI(pred): _convert(value)
+                for pred, value # FIXME: preserve datatype of value?!
+                in graph.predicate_objects(child)
+                if URI(pred) != ns.rdfs.subClassOf
+                }
+            # convert child to URI
+            child = URI(child)
+            # check circular dependency
+            if child == curr.uri or child in {node.uri for node in curr.parents()}:
+                raise errors.ConsistencyError('circular dependency')
+            # recurse and emit (sub*)childs
+            yield from _fetch_hierarchically(factory, factory(child, curr, **annotations))
+
+    # fetch nodes
+    nodes = set(_fetch_hierarchically(types.Node, types.ROOT_NODE))
+    nodes_lut = {node.uri: node for node in nodes}
+    if len(nodes_lut) != len(nodes):
+        raise errors.ConsistencyError('inconsistent nodes')
+
+    # fetch literals
+    literals = set(_fetch_hierarchically(types.Literal, types.ROOT_LITERAL))
+    literals_lut = {lit.uri: lit for lit in literals}
+    if len(literals_lut) != len(literals):
+        raise errors.ConsistencyError('inconsistent literals')
+
+    # fetch predicates
+    # FIXME: type annotation
+    def _fetch_value(subject: URI, predicate: rdflib.URIRef, value_factory) -> typing.Optional[typing.Any]:
+        """Fetch the object of a given subject and predicate. Raises a `errors.ConsistencyError` if multiple objects match."""
+        values = list(graph.objects(rdflib.URIRef(subject), predicate))
+        if len(values) == 0:
+            return None
+        elif len(values) == 1:
+            return value_factory(values[0])
+        else:
+            raise errors.ConsistencyError(f'{subject} has multiple values for predicate {str(predicate)}, expected zero or one')
+
+    def _build_predicate(uri, parent, **annotations):
+        """Predicate factory."""
+        # break out on root feature type
+        if uri == types.ROOT_FEATURE.uri:
+            return types.ROOT_FEATURE
+        # clean annotations
+        annotations.pop(ns.rdfs.domain, None)
+        annotations.pop(ns.rdfs.range, None)
+        annotations.pop(ns.bsfs.unique, None)
+        # get domain
+        dom = _fetch_value(uri, rdflib.RDFS.domain, URI)
+        if dom is not None and dom not in nodes_lut:
+            raise errors.ConsistencyError(f'predicate {uri} has undefined domain {dom}')
+        elif dom is not None:
+            dom = nodes_lut[dom]
+        # get range
+        rng = _fetch_value(uri, rdflib.RDFS.range, URI)
+        if rng is not None and rng not in nodes_lut and rng not in literals_lut:
+            raise errors.ConsistencyError(f'predicate {uri} has undefined range {rng}')
+        elif rng is not None:
+            rng = nodes_lut.get(rng, literals_lut.get(rng))
+        # get unique
+        unique = _fetch_value(uri, rdflib.URIRef(ns.bsfs.unique), bool)
+        # handle feature types
+        if isinstance(parent, types.Feature):
+            # clean annotations
+            annotations.pop(ns.bsfs.dimension, None)
+            annotations.pop(ns.bsfs.dtype, None)
+            annotations.pop(ns.bsfs.distance, None)
+            # get dimension
+            dimension = _fetch_value(uri, rdflib.URIRef(ns.bsfs.dimension), int)
+            # get dtype
+            dtype = _fetch_value(uri, rdflib.URIRef(ns.bsfs.dtype), URI)
+            # get distance
+            distance = _fetch_value(uri, rdflib.URIRef(ns.bsfs.distance), URI)
+            # return feature
+            return parent.get_child(URI(uri), domain=dom, range=rng, unique=unique,
+                dtype=dtype, dimension=dimension, distance=distance, **annotations)
+        # handle non-feature predicate
+        return parent.get_child(URI(uri), domain=dom, range=rng, unique=unique, **annotations)
+    predicates = _fetch_hierarchically(_build_predicate, types.ROOT_PREDICATE)
+
+    return schema.Schema(predicates, nodes, literals)
+
+
+
+def to_string(schema_inst: schema.Schema) -> str:
+    """
+    """
+    raise NotImplementedError()
+
+## EOF ##
diff --git a/bsfs/schema/types.py b/bsfs/schema/types.py
index 54a7e99..e737263 100644
--- a/bsfs/schema/types.py
+++ b/bsfs/schema/types.py
@@ -8,6 +8,7 @@ Author: Matthias Baumgartner, 2022
 import typing
 
 # bsfs imports
+from bsfs.namespace import ns
 from bsfs.utils import errors, URI, typename
 
 # exports
@@ -15,6 +16,7 @@ __all__: typing.Sequence[str] = (
     'Literal',
     'Node',
     'Predicate',
+    'Feature',
     )
 
 
@@ -99,9 +101,11 @@ class _Type():
             self,
             uri: URI,
             parent: typing.Optional['_Type'] = None,
+            **annotations: typing.Any,
             ):
         self.uri = uri
         self.parent = parent
+        self.annotations = annotations
 
     def parents(self) -> typing.Generator['_Type', None, None]:
         """Generate a list of parent nodes."""
@@ -110,9 +114,17 @@ class _Type():
             yield curr
             curr = curr.parent
 
-    def get_child(self, uri: URI, **kwargs):
+    def get_child(
+            self,
+            uri: URI,
+            **kwargs,
+            ):
         """Return a child of the current class."""
-        return type(self)(uri, self, **kwargs)
+        return type(self)(
+            uri=uri,
+            parent=self,
+            **kwargs
+            )
 
     def __str__(self) -> str:
         return f'{typename(self)}({self.uri})'
@@ -138,7 +150,7 @@ class _Type():
 
     def __lt__(self, other: typing.Any) -> bool:
         """Return True iff *self* is a true subclass of *other*."""
-        if not type(self) is type(other): # type mismatch # pylint: disable=unidiomatic-typecheck
+        if not isinstance(other, type(self)):
             return NotImplemented
         if self.uri == other.uri: # equivalence
             return False
@@ -151,7 +163,7 @@ class _Type():
 
     def __le__(self, other: typing.Any) -> bool:
         """Return True iff *self* is equivalent or a subclass of *other*."""
-        if not type(self) is type(other): # type mismatch # pylint: disable=unidiomatic-typecheck
+        if not isinstance(other, type(self)):
             return NotImplemented
         if self.uri == other.uri: # equivalence
             return True
@@ -164,7 +176,7 @@ class _Type():
 
     def __gt__(self, other: typing.Any) -> bool:
         """Return True iff *self* is a true superclass of *other*."""
-        if not type(self) is type(other): # type mismatch # pylint: disable=unidiomatic-typecheck
+        if not isinstance(other, type(self)):
             return NotImplemented
         if self.uri == other.uri: # equivalence
             return False
@@ -177,7 +189,7 @@ class _Type():
 
     def __ge__(self, other: typing.Any) -> bool:
         """Return True iff *self* is eqiuvalent or a superclass of *other*."""
-        if not type(self) is type(other): # type mismatch # pylint: disable=unidiomatic-typecheck
+        if not isinstance(other, type(self)):
             return NotImplemented
         if self.uri == other.uri: # equivalence
             return True
@@ -191,30 +203,33 @@ class _Type():
 
 class _Vertex(_Type):
     """Graph vertex types. Can be a Node or a Literal."""
-    def __init__(self, uri: URI, parent: typing.Optional['_Vertex']):
-        super().__init__(uri, parent)
+    parent: typing.Optional['_Vertex']
+    def __init__(self, uri: URI, parent: typing.Optional['_Vertex'], **kwargs):
+        super().__init__(uri, parent, **kwargs)
 
 
 class Node(_Vertex):
     """Node type."""
-    def __init__(self, uri: URI, parent: typing.Optional['Node']):
-        super().__init__(uri, parent)
+    parent: typing.Optional['Node']
+    def __init__(self, uri: URI, parent: typing.Optional['Node'], **kwargs):
+        super().__init__(uri, parent, **kwargs)
 
 
 class Literal(_Vertex):
     """Literal type."""
-    def __init__(self, uri: URI, parent: typing.Optional['Literal']):
-        super().__init__(uri, parent)
+    parent: typing.Optional['Literal']
+    def __init__(self, uri: URI, parent: typing.Optional['Literal'] ,**kwargs):
+        super().__init__(uri, parent, **kwargs)
 
 
 class Predicate(_Type):
-    """Predicate type."""
+    """Predicate base type."""
 
     # source type.
     domain: Node
 
     # destination type.
-    range: typing.Optional[typing.Union[Node, Literal]]
+    range: _Vertex
 
     # maximum cardinality of type.
     unique: bool
@@ -223,25 +238,26 @@ class Predicate(_Type):
             self,
             # Type members
             uri: URI,
-            parent: typing.Optional['Predicate'],
+            parent: '_PredicateBase',
             # Predicate members
             domain: Node,
-            range: typing.Optional[typing.Union[Node, Literal]], # pylint: disable=redefined-builtin
+            range: _Vertex, # pylint: disable=redefined-builtin
             unique: bool,
+            **kwargs,
             ):
         # check arguments
         if not isinstance(domain, Node):
             raise TypeError(domain)
-        if range is not None and not isinstance(range, Node) and not isinstance(range, Literal):
+        if range != ROOT_VERTEX and not isinstance(range, (Node, Literal)):
             raise TypeError(range)
         # initialize
-        super().__init__(uri, parent)
+        super().__init__(uri, parent, **kwargs)
         self.domain = domain
         self.range = range
-        self.unique = unique
+        self.unique = bool(unique)
 
     def __hash__(self) -> int:
-        return hash((super().__hash__(), self.domain, self.range, self.unique))
+        return hash((super().__hash__(), self.domain, self.unique, self.range))
 
     def __eq__(self, other: typing.Any) -> bool:
         return super().__eq__(other) \
@@ -264,13 +280,132 @@ class Predicate(_Type):
             raise errors.ConsistencyError(f'{domain} must be a subclass of {self.domain}')
         if range is None:
             range = self.range
-        if range is None: # inherited range from ns.bsfs.Predicate
-            raise ValueError('range must be defined by the parent or argument')
-        if self.range is not None and not range <= self.range:
+        # NOTE: The root predicate has a Vertex as range, which is neither a parent of the root
+        # Node nor Literal. Hence, that test is skipped since a child should be allowed to
+        # specialize from Vertex to anything.
+        if self.range != ROOT_VERTEX and not range <= self.range:
             raise errors.ConsistencyError(f'{range} must be a subclass of {self.range}')
         if unique is None:
             unique = self.unique
-        return super().get_child(uri, domain=domain, range=range, unique=unique, **kwargs)
+        return super().get_child(
+            uri=uri,
+            domain=domain,
+            range=range,
+            unique=unique,
+            **kwargs
+            )
+
+
+class Feature(Predicate):
+    """Feature base type."""
+
+    # Number of feature vector dimensions.
+    dimension: int
+
+    # Feature vector datatype.
+    dtype: URI
+
+    # Distance measure to compare feature vectors.
+    distance: URI
+
+    def __init__(
+            self,
+            # Type members
+            uri: URI,
+            parent: Predicate,
+            # Predicate members
+            domain: Node,
+            range: Literal,
+            unique: bool,
+            # Feature members
+            dimension: int,
+            dtype: URI,
+            distance: URI,
+            **kwargs,
+            ):
+        super().__init__(uri, parent, domain, range, unique, **kwargs)
+        self.dimension = int(dimension)
+        self.dtype = URI(dtype)
+        self.distance = URI(distance)
+
+    def __hash__(self) -> int:
+        return hash((super().__hash__(), self.dimension, self.dtype, self.distance))
+
+    def __eq__(self, other: typing.Any) -> bool:
+        return super().__eq__(other) \
+           and self.dimension == other.dimension \
+           and self.dtype == other.dtype \
+           and self.distance == other.distance
+
+    def get_child(
+            self,
+            uri: URI,
+            domain: typing.Optional[Node] = None,
+            range: typing.Optional[Literal] = None, # pylint: disable=redefined-builtin
+            unique: typing.Optional[bool] = None,
+            dimension: typing.Optional[int] = None,
+            dtype: typing.Optional[URI] = None,
+            distance: typing.Optional[URI] = None,
+            **kwargs,
+            ):
+        """Return a child of the current class."""
+        if dimension is None:
+            dimension = self.dimension
+        if dtype is None:
+            dtype = self.dtype
+        if distance is None:
+            distance = self.distance
+        return super().get_child(
+            uri=uri,
+            domain=domain,
+            range=range,
+            unique=unique,
+            dimension=dimension,
+            dtype=dtype,
+            distance=distance,
+            **kwargs,
+            )
 
 
+# essential vertices
+ROOT_VERTEX = _Vertex(
+    uri=ns.bsfs.Vertex,
+    parent=None,
+    )
+
+ROOT_NODE = Node(
+    uri=ns.bsfs.Node,
+    parent=None,
+    )
+
+ROOT_LITERAL = Literal(
+    uri=ns.bsfs.Literal,
+    parent=None,
+    )
+
+ROOT_NUMBER = Literal(
+    uri=ns.bsfs.Number,
+    parent=ROOT_LITERAL,
+    )
+
+# essential predicates
+ROOT_PREDICATE = Predicate(
+    uri=ns.bsfs.Predicate,
+    parent=None,
+    domain=ROOT_NODE,
+    range=ROOT_VERTEX,
+    unique=False,
+    )
+
+ROOT_FEATURE = Feature(
+    uri=ns.bsfs.Feature,
+    parent=ROOT_PREDICATE,
+    domain=ROOT_NODE,
+    range=ROOT_LITERAL,
+    unique=False,
+    dimension=1,
+    dtype=ns.bsfs.f16,
+    distance=ns.bsfs.euclidean,
+    )
+
 ## EOF ##