Fetch in graph including results view

4 files changed, 248 insertions, 9 deletions

diff --git a/bsfs/graph/ac/base.py b/bsfs/graph/ac/base.py
index 0703e2e..79b09e5 100644
--- a/bsfs/graph/ac/base.py
+++ b/bsfs/graph/ac/base.py
@@ -72,4 +72,8 @@ class AccessControlBase(abc.ABC):
     def filter_read(self, node_type: schema.Node, query: ast.filter.FilterExpression) -> ast.filter.FilterExpression:
         """Re-write a filter *query* to get (i.e., read) *node_type* nodes."""
 
+    @abc.abstractmethod
+    def fetch_read(self, node_type: schema.Node, query: ast.fetch.FetchExpression) -> ast.fetch.FetchExpression:
+        """Re-write a fetch *query* to get (i.e, read) values for *node_type* nodes."""
+
 ## EOF ##
diff --git a/bsfs/graph/ac/null.py b/bsfs/graph/ac/null.py
index 12b4e87..6a923a5 100644
--- a/bsfs/graph/ac/null.py
+++ b/bsfs/graph/ac/null.py
@@ -54,4 +54,8 @@ class NullAC(base.AccessControlBase):
         """Re-write a filter *query* to get (i.e., read) *node_type* nodes."""
         return query
 
+    def fetch_read(self, node_type: schema.Node, query: ast.fetch.FetchExpression) -> ast.fetch.FetchExpression:
+        """Re-write a fetch *query* to get (i.e, read) values for *node_type* nodes."""
+        return query
+
 ## EOF ##
diff --git a/bsfs/graph/nodes.py b/bsfs/graph/nodes.py
index 5a93f77..a4ba45f 100644
--- a/bsfs/graph/nodes.py
+++ b/bsfs/graph/nodes.py
@@ -5,17 +5,20 @@ A copy of the license is provided with the project.
 Author: Matthias Baumgartner, 2022
 """
 # imports
+from collections import abc
 import time
 import typing
 
 # bsfs imports
-from bsfs import schema as _schema
+from bsfs import schema as bsc
 from bsfs.namespace import ns
+from bsfs.query import ast, validate
 from bsfs.triple_store import TripleStoreBase
 from bsfs.utils import errors, URI, typename
 
 # inner-module imports
 from . import ac
+from . import result
 
 # exports
 __all__: typing.Sequence[str] = (
@@ -37,7 +40,7 @@ class Nodes():
     _user: URI
 
     # node type.
-    _node_type: _schema.Node
+    _node_type: bsc.Node
 
     # guids of nodes. Can be empty.
     _guids: typing.Set[URI]
@@ -46,13 +49,16 @@ class Nodes():
             self,
             backend: TripleStoreBase,
             user: URI,
-            node_type: _schema.Node,
+            node_type: bsc.Node,
             guids: typing.Iterable[URI],
             ):
+        # set main members
         self._backend = backend
         self._user = user
         self._node_type = node_type
         self._guids = set(guids)
+        # create helper instances
+        # FIXME: Assumes that the schema does not change while the instance is in use!
         self._ac = ac.NullAC(self._backend, self._user)
 
     def __eq__(self, other: typing.Any) -> bool:
@@ -72,7 +78,7 @@ class Nodes():
         return f'{typename(self)}({self._node_type}, {self._guids})'
 
     @property
-    def node_type(self) -> _schema.Node:
+    def node_type(self) -> bsc.Node:
         """Return the node's type."""
         return self._node_type
 
@@ -83,7 +89,7 @@ class Nodes():
 
     def set(
             self,
-            pred: URI, # FIXME: URI or _schema.Predicate?
+            pred: URI, # FIXME: URI or bsc.Predicate?
             value: typing.Any,
             ) -> 'Nodes':
         """Set predicate *pred* to *value*."""
@@ -91,7 +97,7 @@ class Nodes():
 
     def set_from_iterable(
             self,
-            predicate_values: typing.Iterable[typing.Tuple[URI, typing.Any]], # FIXME: URI or _schema.Predicate?
+            predicate_values: typing.Iterable[typing.Tuple[URI, typing.Any]], # FIXME: URI or bsc.Predicate?
             ) -> 'Nodes':
         """Set mutliple predicate-value pairs at once."""
         # TODO: Could group predicate_values by predicate to gain some efficiency
@@ -120,6 +126,119 @@ class Nodes():
 
         return self
 
+    def get(
+            self,
+            *paths: typing.Union[URI, typing.Iterable[URI]],
+            view: typing.Union[typing.Type[list], typing.Type[dict]] = dict,
+            **view_kwargs,
+            ) -> typing.Any:
+        """Get values or nodes at *paths*.
+        Return an iterator (view=list) or a dict (view=dict) over the results.
+        """
+        # check args
+        if len(paths) == 0:
+            raise AttributeError('expected at least one path, found none')
+        if view not in (dict, list):
+            raise ValueError(f'expected dict or list, found {view}')
+        # process paths: create fetch ast, build name mapping, and find unique paths
+        schema = self._backend.schema
+        statements = set()
+        name2path = {}
+        unique_paths = set() # paths that result in a single (unique) value
+        normpath: typing.Tuple[URI, ...]
+        for idx, path in enumerate(paths):
+            # normalize path
+            if isinstance(path, str):
+                normpath = (URI(path), )
+            elif isinstance(path, abc.Iterable):
+                if not all(isinstance(step, str) for step in path):
+                    raise TypeError(path)
+                normpath = tuple(URI(step) for step in path)
+            else:
+                raise TypeError(path)
+            # check path's schema consistency
+            if not all(schema.has_predicate(pred) for pred in normpath):
+                raise errors.ConsistencyError(f'path is not fully covered by the schema: {path}')
+            # check path's uniqueness
+            if all(schema.predicate(pred).unique for pred in normpath):
+                unique_paths.add(path)
+            # fetch tail predicate
+            tail = schema.predicate(normpath[-1])
+            # determine tail ast node type
+            factory = ast.fetch.Node if isinstance(tail.range, bsc.Node) else ast.fetch.Value
+            # assign name
+            name = f'fetch{idx}'
+            name2path[name] = (path, tail)
+            # create tail ast node
+            curr: ast.fetch.FetchExpression = factory(tail.uri, name)
+            # walk towards front
+            hop: URI
+            for hop in normpath[-2::-1]:
+                curr = ast.fetch.Fetch(hop, curr)
+            # add to fetch query
+            statements.add(curr)
+        # aggregate fetch statements
+        if len(statements) == 1:
+            fetch = next(iter(statements))
+        else:
+            fetch = ast.fetch.All(*statements)
+        # add access controls to fetch
+        fetch = self._ac.fetch_read(self.node_type, fetch)
+
+        # compose filter ast
+        filter = ast.filter.IsIn(self.guids) # pylint: disable=redefined-builtin
+        # add access controls to filter
+        filter = self._ac.filter_read(self.node_type, filter)
+
+        # validate queries
+        validate.Filter(self._backend.schema)(self.node_type, filter)
+        validate.Fetch(self._backend.schema)(self.node_type, fetch)
+
+        # process results, convert if need be
+        def triple_iter():
+            # query the backend
+            triples = self._backend.fetch(self.node_type, filter, fetch)
+            # process triples
+            for root, name, raw in triples:
+                # get node
+                node = Nodes(self._backend, self._user, self.node_type, {root})
+                # get path
+                path, tail = name2path[name]
+                # covert raw to value
+                if isinstance(tail.range, bsc.Node):
+                    value = Nodes(self._backend, self._user, tail.range, {raw})
+                else:
+                    value = raw
+                # emit triple
+                yield node, path, value
+
+        # simplify by default
+        view_kwargs['node'] = view_kwargs.get('node', len(self._guids) == 1)
+        view_kwargs['path'] = view_kwargs.get('path', len(paths) == 1)
+        view_kwargs['value'] = view_kwargs.get('value', True)
+
+        # return results view
+        if view == list:
+            return result.to_list_view(
+                triple_iter(),
+                # aggregation args
+                **view_kwargs,
+                )
+
+        if view == dict:
+            return result.to_dict_view(
+                triple_iter(),
+                # context
+                len(self._guids) == 1,
+                len(paths) == 1,
+                unique_paths,
+                # aggregation args
+                **view_kwargs,
+                )
+
+        raise errors.UnreachableError() # view was already checked
+
+
     def __set(self, predicate: URI, value: typing.Any):
         """
         """
@@ -145,7 +264,7 @@ class Nodes():
         guids = set(self._ensure_nodes(node_type, guids))
 
         # check value
-        if isinstance(pred.range, _schema.Literal):
+        if isinstance(pred.range, bsc.Literal):
             # check write permissions on existing nodes
             # As long as the user has write permissions, we don't restrict
             # the creation or modification of literal values.
@@ -160,7 +279,7 @@ class Nodes():
                 [value],
                 )
 
-        elif isinstance(pred.range, _schema.Node):
+        elif isinstance(pred.range, bsc.Node):
             # check value type
             if not isinstance(value, Nodes):
                 raise TypeError(value)
@@ -192,7 +311,7 @@ class Nodes():
         else:
             raise errors.UnreachableError()
 
-    def _ensure_nodes(self, node_type: _schema.Node, guids: typing.Iterable[URI]):
+    def _ensure_nodes(self, node_type: bsc.Node, guids: typing.Iterable[URI]):
         """
         """
         # check node existence
diff --git a/bsfs/graph/result.py b/bsfs/graph/result.py
new file mode 100644
index 0000000..3009801
--- /dev/null
+++ b/bsfs/graph/result.py
@@ -0,0 +1,112 @@
+"""
+
+Part of the BlackStar filesystem (bsfs) module.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# imports
+from collections import defaultdict
+import typing
+
+# bsfs imports
+from bsfs.utils import URI
+
+# exports
+__all__: typing.Sequence[str] = (
+    'to_list_view',
+    'to_dict_view',
+    )
+
+
+## code ##
+
+def to_list_view(
+        triples,
+        # aggregators
+        node: bool,
+        path: bool,
+        value: bool, # pylint: disable=unused-argument
+        ):
+    """Return an iterator over results.
+
+    Dependent on the *node*, *path*, and *value* flags,
+    the respective component is omitted.
+
+    """
+    if node and path:
+        return iter(val for _, _, val in triples)
+    if node:
+        return iter((pred, val) for _, pred, val in triples)
+    if path:
+        return iter((subj, val) for subj, _, val in triples)
+    return iter((subj, pred, val) for subj, pred, val in triples)
+
+
+def to_dict_view(
+        triples,
+        # context
+        one_node: bool,
+        one_path: bool,
+        unique_paths: typing.Set[typing.Union[URI, typing.Iterable[URI]]],
+        # aggregators
+        node: bool,
+        path: bool,
+        value: bool,
+        ) -> typing.Any:
+    """Return a dict of results.
+
+    Note that triples are materialized to create this view.
+
+    The returned structure depends on the *node*, *path*, and *value* flags.
+    If all flags are set to False, returns a dict(node -> dict(path -> set(values))).
+    Setting a flag to true omits or simplifies the respective component (if possible).
+
+    """
+    # NOTE: To create a dict, we need to materialize or make further assumptions
+    # (e.g., sorted in a specific order).
+
+    data: typing.Any # disable type checks on data since it's very flexibly typed.
+
+    # FIXME: type of data can be overwritten later on (if value)
+
+    if node and path:
+        data = set()
+    elif node ^ path:
+        data = defaultdict(set)
+    else:
+        data = defaultdict(lambda: defaultdict(set))
+
+    for subj, pred, val in triples:
+        unique = pred in unique_paths
+        if node and path:
+            if value and unique and one_node and one_path:
+                return val
+            data.add(val)
+        elif node:
+            # remove node from result, group by predicate
+            if value and unique and one_node:
+                data[pred] = val
+            else:
+                data[pred].add(val)
+        elif path:
+            # remove predicate from result, group by node
+            if value and unique and one_path:
+                data[subj] = val
+            else:
+                data[subj].add(val)
+        else:
+            if value and unique:
+                data[subj][pred] = val
+            else:
+                data[subj][pred].add(val)
+
+    # FIXME: Combine multiple Nodes instances into one?
+
+    # convert defaultdict to ordinary dict
+    if node and path:
+        return data
+    if node ^ path:
+        return dict(data)
+    return {key: dict(val) for key, val in data.items()}
+
+## EOF ##