Merge branch 'develop' into main

3 files changed, 124 insertions, 0 deletions

diff --git a/bsfs/front/__init__.py b/bsfs/front/__init__.py
new file mode 100644
index 0000000..92886ab
--- /dev/null
+++ b/bsfs/front/__init__.py
@@ -0,0 +1,20 @@
+"""
+
+Part of the BlackStar filesystem (bsfs) module.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# imports
+import typing
+
+# inner-module imports
+from .bsfs import Open
+from .builder import build_graph
+
+# exports
+__all__: typing.Sequence[str] = (
+    'Open',
+    'build_graph',
+    )
+
+## EOF ##
diff --git a/bsfs/front/bsfs.py b/bsfs/front/bsfs.py
new file mode 100644
index 0000000..968b3f5
--- /dev/null
+++ b/bsfs/front/bsfs.py
@@ -0,0 +1,29 @@
+"""
+
+Part of the BlackStar filesystem (bsfs) module.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# imports
+import typing
+
+# bsfs imports
+from bsfs.graph import Graph
+
+# inner-module imports
+from . import builder
+
+# exports
+__all__: typing.Sequence[str] = (
+    'Open',
+    )
+
+
+## code ##
+
+# NOTE: Capitalized to mark entry point and to separate from builtin open.
+def Open(cfg: typing.Any) -> Graph: # pylint: disable=invalid-name
+    """Open a BSFS storage and return a `bsfs.graph.Graph` instance."""
+    return builder.build_graph(cfg)
+
+## EOF ##
diff --git a/bsfs/front/builder.py b/bsfs/front/builder.py
new file mode 100644
index 0000000..73f1703
--- /dev/null
+++ b/bsfs/front/builder.py
@@ -0,0 +1,75 @@
+"""
+
+Part of the BlackStar filesystem (bsfs) module.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# imports
+import typing
+
+# bsfs imports
+from bsfs.graph import Graph
+from bsfs.triple_store import TripleStoreBase, SparqlStore
+from bsfs.utils import URI, errors
+
+# exports
+__all__: typing.Sequence[str] = (
+    'build_graph',
+    )
+
+# constants
+_graph_classes = {
+    'Graph': Graph,
+    }
+
+_backend_classes = {
+    'SparqlStore': SparqlStore,
+    }
+
+
+## code ##
+
+def build_backend(cfg: typing.Any) -> TripleStoreBase:
+    """Build and return a backend from user-provided config."""
+    # essential checks
+    if not isinstance(cfg, dict):
+        raise TypeError(cfg)
+    if len(cfg) != 1:
+        raise errors.ConfigError(f'expected a single key that identifies the backend class, found {list(cfg)}')
+    # unpack from config
+    name = next(iter(cfg))
+    args = cfg[name]
+    # check name
+    if name not in _backend_classes:
+        raise errors.ConfigError(f'{name} is not a valid triple store class name')
+    # build and return backend
+    cls = _backend_classes[name]
+    return cls.Open(**args)
+
+
+def build_graph(cfg: typing.Any) -> Graph:
+    """Build and return a Graph from user-provided config."""
+    # essential checks
+    if not isinstance(cfg, dict):
+        raise TypeError(cfg)
+    if len(cfg) != 1:
+        raise errors.ConfigError(f'expected a single key that identifies the graph class, found {list(cfg)}')
+    # unpack from config
+    name = next(iter(cfg))
+    args = cfg[name]
+    # check name
+    if name not in _graph_classes:
+        raise errors.ConfigError(f'{name} is not a valid graph class name')
+    # check user argument
+    if 'user' not in args:
+        raise errors.ConfigError('required argument "user" is not provided')
+    user = URI(args['user'])
+    # check backend argument
+    if 'backend' not in args:
+        raise errors.ConfigError('required argument "backend" is not provided')
+    backend = build_backend(args['backend'])
+    # build and return graph
+    cls = _graph_classes[name]
+    return cls(backend, user)
+
+## EOF ##