Merge branch 'mb/arch' into develop

4 files changed, 144 insertions, 0 deletions

diff --git a/bsie/base/__init__.py b/bsie/base/__init__.py
new file mode 100644
index 0000000..0154862
--- /dev/null
+++ b/bsie/base/__init__.py
@@ -0,0 +1,24 @@
+"""The base module defines the BSIE interfaces.
+
+You'll mostly find abstract classes here.
+
+Part of the bsie module.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# imports
+import typing
+
+# inner-module imports
+from . import errors
+from . import extractor
+from . import reader
+
+# exports
+__all__: typing.Sequence[str] = (
+    'errors',
+    'extractor',
+    'reader',
+    )
+
+## EOF ##
diff --git a/bsie/base/errors.py b/bsie/base/errors.py
new file mode 100644
index 0000000..f86ffb2
--- /dev/null
+++ b/bsie/base/errors.py
@@ -0,0 +1,22 @@
+"""Common BSIE exceptions.
+
+Part of the bsie module.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# imports
+import typing
+
+# exports
+__all__: typing.Sequence[str] = []
+
+
+## code ##
+
+class _BSIE_Error(Exception):
+    """Generic BSIE error."""
+
+class ReaderError(_BSIE_Error):
+    """The Reader failed to read the given file."""
+
+## EOF ##
diff --git a/bsie/base/extractor.py b/bsie/base/extractor.py
new file mode 100644
index 0000000..d5b0922
--- /dev/null
+++ b/bsie/base/extractor.py
@@ -0,0 +1,50 @@
+"""The Extractor classes transform content into triples.
+
+Part of the bsie module.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# imports
+import abc
+import collections
+import typing
+
+# inner-module imports
+from . import reader
+from bsie.utils import node
+from bsie.utils.bsfs import URI, typename
+
+# exports
+__all__: typing.Sequence[str] = (
+    'Extractor',
+    )
+
+
+## code ##
+
+class Extractor(abc.ABC, collections.abc.Iterable, collections.abc.Callable):
+    """Produce (node, predicate, value)-triples from some content."""
+
+    # what type of content is expected (i.e. reader subclass).
+    CONTENT_READER: typing.Optional[typing.Type[reader.Reader]] = None
+
+    def __str__(self) -> str:
+        return typename(self)
+
+    def __repr__(self) -> str:
+        return f'{typename(self)}()'
+
+    @abc.abstractmethod
+    def schema(self) -> str:
+        """Return the schema (predicates and nodes) produced by this Extractor."""
+
+    @abc.abstractmethod
+    def extract(
+            self,
+            subject: node.Node,
+            content: typing.Any,
+            predicates: typing.Iterable[URI],
+            ) -> typing.Iterator[typing.Tuple[node.Node, URI, typing.Any]]:
+        """Return (node, predicate, value) triples."""
+
+## EOF ##
diff --git a/bsie/base/reader.py b/bsie/base/reader.py
new file mode 100644
index 0000000..f29e451
--- /dev/null
+++ b/bsie/base/reader.py
@@ -0,0 +1,48 @@
+"""The Reader classes return high-level content structures from files.
+
+The Reader fulfills two purposes:
+    First, it brokers between multiple libraries and file formats.
+    Second, it separates multiple aspects of a file into distinct content types.
+
+Part of the bsie module.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# imports
+import abc
+import typing
+
+# inner-module imports
+from bsie.utils.bsfs import URI, typename
+
+# exports
+__all__: typing.Sequence[str] = (
+    'Aggregator',
+    'Reader',
+    )
+
+
+## code ##
+
+class Reader(abc.ABC):
+    """Read and return some content from a file."""
+
+    # In what data structure content is returned
+    CONTENT_TYPE = typing.Union[typing.Any]
+    # NOTE: Child classes must also assign a typing.Union even if there's
+    # only one options
+
+    def __str__(self) -> str:
+        return typename(self)
+
+    def __repr__(self) -> str:
+        return f'{typename(self)}()'
+
+    # FIXME: How about using contexts instead of calls?
+    @abc.abstractmethod
+    def __call__(self, path: URI) -> CONTENT_TYPE:
+        """Return some content of the file at *path*.
+        Raises a `ReaderError` if the reader cannot make sense of the file format.
+        """
+
+## EOF ##