add formats interfaces, fixes #105 #120

- add `interface` sub-pacakge with base.py
  + defines `BaseFormat`
- add seq sub-package in `interface` with base.py
  + defines `SeqLike` interface
- add bbox sub-package in `interface` with base.py
  + definfes `BBoxLike` interface
- import BaseFormat and sub-packages in interface/__init__.py
- import inside __init__ in Transcriber to avoid circular imports

src/crowsetta/__init__.py

@@ -10,11 +10,16 @@
     __version__,
 )
 
+# --- need to import everything used by formats before importing formats
+from . import interface
+
 from .transcriber import Transcriber
 from .segment import Segment
 from .sequence import Sequence
 from .annotation import Annotation
 from .meta import Meta
+
+# ---- ok, now import formats
 from . import (
     birdsongrec,
     formats,

src/crowsetta/interface/__init__.py

@@ -0,0 +1,3 @@
+from .base import BaseFormat
+from .bbox import BBoxLike
+from .seq import SeqLike

src/crowsetta/interface/base.py

@@ -0,0 +1,27 @@
+import abc
+
+
+class BaseFormat(abc.ABC):
+    """abstract base class
+    that declares the interface
+    for any sub-class that
+    represents annotations
+    loaded from a file
+    in a specific format
+    for annotating vocalizations.
+    """
+    @classmethod
+    @abc.abstractmethod
+    def from_file(cls) -> 'Self':
+        """loads an annotation from a file
+        in a given format.
+        """
+        ...
+
+    def to_annot(self) -> 'Union[crowsetta.Annotation,List[crowsetta.Annotation]]':
+        """converts the instance representing annotations
+        loaded from a file into a `crowsetta.Annotation`
+        or a list of `crowsetta.Annotation`s,
+        that can be used to convert to other formats
+        """
+        ...

src/crowsetta/interface/bbox/__init__.py

@@ -0,0 +1 @@
+from .base import BBoxLike

src/crowsetta/interface/bbox/base.py

@@ -0,0 +1,20 @@
+import abc
+
+from ..base import BaseFormat
+
+
+class BBoxLike(BaseFormat, abc.ABC):
+    """abstract base class defining the interface
+    for any annotation format
+    that can be represented as a set of bounding boxes,
+    where each bounding box has corners
+    ((x_min, y_max), (x_min, y_min), (x_max, y_max), (x_max, y_min))
+    and a label.
+    """
+    def to_bbox(self) -> 'Union[crowsetta.BBox, Sequence[crowsetta.BBox]]':
+        """converts the annotation to
+        a ``crowsetta.BBox`` instance
+        or a python set of
+        ``crowsetta.BBox`` instances.
+        """
+        ...

src/crowsetta/interface/seq/__init__.py

@@ -0,0 +1 @@
+from .base import SeqLike

src/crowsetta/interface/seq/base.py

@@ -0,0 +1,20 @@
+import abc
+
+from ..base import BaseFormat
+
+
+class SeqLike(BaseFormat, abc.ABC):
+    """abstract base class defining the interface
+    for any annotation format
+    that can be represented as a sequence of segments,
+    with each segment having an onset time,
+    offset time, and a label.
+    """
+    def to_seq(self) -> 'Union[crowsetta.Sequence, Sequence[crowsetta.Sequence]]':
+        """converts the annotation to
+        a ``crowsetta.Sequence`` instance
+        or a python sequence of
+        ``crowsetta.Sequence``s
+        (e.g., a list or tuple).
+        """
+        ...

src/crowsetta/transcriber.py

@@ -3,12 +3,6 @@
 import importlib.util
 import warnings
 
-from . import (
-    formats,
-    generic
-)
-from .meta import Meta
-
 HERE = os.path.dirname(__file__)
 
 VALID_CONFIG_DICT_KEYS = {'module', 'from_file', 'to_csv', 'to_format'}
@@ -58,6 +52,13 @@ def __init__(self, format, config=None):
         >>> scribe = crowsetta.Transcriber(format='myformat_name', config=my_config)
         >>> seq = scribe.from_file(file='my_annotation.mat')
         """
+        # avoid circular imports
+        from . import (
+            formats,
+            generic
+        )
+        from .meta import Meta
+
         # make sure format specified is either installed or that user also specified a config
         if (format in formats._INSTALLED and config is None) or (format and config is not None):
             pass