#336 - Introduce Annotation class

cassis/cas.py

@@ -4,7 +4,7 @@
 from collections import defaultdict
 from functools import lru_cache
 from pathlib import Path
-from typing import Dict, Iterable, List, Optional, Tuple, Union
+from typing import Dict, Iterable, List, Optional, Tuple, Union, cast
 
 import attr
 import deprecation
@@ -15,15 +15,16 @@
     FEATURE_BASE_NAME_HEAD,
     FEATURE_BASE_NAME_LANGUAGE,
     TYPE_NAME_DOCUMENT_ANNOTATION,
-    TYPE_NAME_ANNOTATION,
     TYPE_NAME_FS_ARRAY,
     TYPE_NAME_FS_LIST,
     TYPE_NAME_SOFA,
     FeatureStructure,
+    Annotation,
     Type,
     TypeCheckError,
     TypeSystem,
     TypeSystemMode,
+    is_annotation,
 )
 
 _validator_optional_string = validators.optional(validators.instance_of(str))
@@ -171,29 +172,59 @@ def type_index(self) -> Dict[str, SortedKeyList]:
         """
         return self._indices
 
+    def add_fs_to_indexes(self, fs: FeatureStructure):
+        """Adds a feature structure to the indexes of this view."""
+        self._indices[fs.type.name].add(fs)
+
+    @deprecation.deprecated(details="Use add_fs_to_indexes()")
     def add_annotation_to_index(self, annotation: FeatureStructure):
-        self._indices[annotation.type.name].add(annotation)
+        """Adds a feature structure to the indexes of this view.
 
-    def get_all_annotations(self) -> List[FeatureStructure]:
-        """Gets all the annotations in this view.
+        .. deprecated::
+            Use :meth:`add_fs_to_indexes`.
+        """
+        self.add_fs_to_indexes(annotation)
+
+    def get_all_fs(self) -> List[FeatureStructure]:
+        """Gets all indexed feature structures in this view.
 
         Returns:
-            A list of all annotations in this view.
+            A list of all indexed feature structures (annotations and non-annotations) in this view.
 
         """
         result = []
-        for annotations_by_type in self._indices.values():
-            result.extend(annotations_by_type)
+        for fs_by_type in self._indices.values():
+            result.extend(fs_by_type)
         return result
 
-    def remove_annotation_from_index(self, annotation: FeatureStructure):
-        """Removes an annotation from an index. This throws if the
-        annotation was not present.
+    @deprecation.deprecated(details="Use get_all_fs() for all indexed feature structures or filter with cassis.typesystem.is_annotation")
+    def get_all_annotations(self) -> List[FeatureStructure]:
+        """Gets all indexed annotations in this view.
+
+        .. deprecated::
+            Use :meth:`get_all_fs` for all indexed feature structures, or filter the result
+            with :func:`cassis.typesystem.is_annotation`.
+        """
+        return [fs for fs in self.get_all_fs() if is_annotation(fs)]
+
+    def remove_fs_from_indexes(self, fs: FeatureStructure):
+        """Removes a feature structure from the indexes of this view. Throws if the
+        feature structure was not present.
 
         Args:
-            annotation: The annotation to remove.
+            fs: The feature structure to remove.
         """
-        self._indices[annotation.type.name].remove(annotation)
+        self._indices[fs.type.name].remove(fs)
+
+    @deprecation.deprecated(details="Use remove_fs_from_indexes()")
+    def remove_annotation_from_index(self, annotation: FeatureStructure):
+        """Removes a feature structure from the indexes of this view. Throws if the
+        feature structure was not present.
+
+        .. deprecated::
+            Use :meth:`remove_fs_from_indexes`.
+        """
+        self.remove_fs_from_indexes(annotation)
 
 
 class Index:
@@ -335,7 +366,9 @@ def add(self, annotation: FeatureStructure, keep_id: Optional[bool] = True):
         if hasattr(annotation, "sofa"):
             annotation.sofa = self.get_sofa()
 
-        self._current_view.add_annotation_to_index(annotation)
+        # Add to the index. The view index accepts any FeatureStructure;
+        # `_sort_func` will duck-type annotation-like objects when sorting.
+        self._current_view.add_fs_to_indexes(annotation)
 
     @deprecation.deprecated(details="Use add()")
     def add_annotation(self, annotation: FeatureStructure, keep_id: Optional[bool] = True):
@@ -404,36 +437,36 @@ def crop_sofa_string(self, sofa_begin: int, sofa_end: int, overlap: bool = True)
             self.sofa_string = self.sofa_string[sofa_begin:sofa_end]
             # Make an explicit snapshot of the current annotations to avoid
             # issues when removing/modifying elements during iteration.
-            for annotation in list(self.select_all()):
+            for annotation in list(self.select_all_annotations()):
                 # Determine whether the annotation will be kept and how its
                 # offsets need to be adjusted. If offsets are adjusted we must
                 # reindex the annotation (remove then add) so that the
                 # underlying SortedKeyList remains correctly ordered by the
                 # updated begin/end values.
                 if sofa_begin <= annotation.begin and annotation.end <= sofa_end:
                     # fully contained
-                    self._current_view.remove_annotation_from_index(annotation)
+                    self._current_view.remove_fs_from_indexes(annotation)
                     annotation.begin = annotation.begin - sofa_begin
                     annotation.end = annotation.end - sofa_begin
-                    self._current_view.add_annotation_to_index(annotation)
+                    self._current_view.add_fs_to_indexes(annotation)
                 elif overlap and sofa_begin < annotation.end <= sofa_end:
                     # left overlap (annotation starts before cut)
-                    self._current_view.remove_annotation_from_index(annotation)
+                    self._current_view.remove_fs_from_indexes(annotation)
                     annotation.begin = 0
                     annotation.end = annotation.end - sofa_begin
-                    self._current_view.add_annotation_to_index(annotation)
+                    self._current_view.add_fs_to_indexes(annotation)
                 elif overlap and sofa_begin <= annotation.begin < sofa_end:
                     # right overlap (annotation ends after cut)
-                    self._current_view.remove_annotation_from_index(annotation)
+                    self._current_view.remove_fs_from_indexes(annotation)
                     annotation.begin = annotation.begin - sofa_begin
                     annotation.end = len(self.sofa_string)
-                    self._current_view.add_annotation_to_index(annotation)
+                    self._current_view.add_fs_to_indexes(annotation)
                 elif overlap and annotation.begin <= sofa_begin and sofa_end <= annotation.end:
                     # annotation fully covers the cut
-                    self._current_view.remove_annotation_from_index(annotation)
+                    self._current_view.remove_fs_from_indexes(annotation)
                     annotation.begin = 0
                     annotation.end = len(self.sofa_string)
-                    self._current_view.add_annotation_to_index(annotation)
+                    self._current_view.add_fs_to_indexes(annotation)
                 else:
                     # annotation falls completely outside the cut; remove it
                     self.remove(annotation)
@@ -447,7 +480,7 @@ def remove(self, annotation: FeatureStructure):
         Args:
             annotation: The annotation to remove.
         """
-        self._current_view.remove_annotation_from_index(annotation)
+        self._current_view.remove_fs_from_indexes(annotation)
 
     @deprecation.deprecated(details="Use remove()")
     def remove_annotation(self, annotation: FeatureStructure):
@@ -474,9 +507,7 @@ def remove_annotations_in_range(self, begin: int, end: int, type_: Optional[Unio
         # structures only (those that have `begin` and `end`) to avoid
         # AttributeError for arbitrary FS (e.g., instances of uima.cas.TOP).
         if type_ is None:
-            # Only operate on annotation-like feature structures to avoid
-            # AttributeError for non-annotation FS present in the view.
-            annotations = [a for a in self.select_all() if self.typesystem.is_instance_of(a.type, TYPE_NAME_ANNOTATION)]
+            annotations = self.select_all_annotations()
         else:
             annotations = self.select(type_)
         if self.sofa_string is None:
@@ -492,7 +523,7 @@ def remove_annotations_in_range(self, begin: int, end: int, type_: Optional[Unio
             raise ValueError(f"Invalid indices for begin {begin} and end {end}")
 
     @deprecation.deprecated(details="Use annotation.get_covered_text()")
-    def get_covered_text(self, annotation: FeatureStructure) -> str:
+    def get_covered_text(self, annotation: Annotation) -> str:
         """Gets the text that is covered by `annotation`.
 
         Args:
@@ -518,7 +549,7 @@ def select(self, type_: Union[Type, str]) -> List[FeatureStructure]:
         t = type_ if isinstance(type_, Type) else self.typesystem.get_type(type_)
         return self._get_feature_structures(t)
 
-    def select_covered(self, type_: Union[Type, str], covering_annotation: FeatureStructure) -> List[FeatureStructure]:
+    def select_covered(self, type_: Union[Type, str], covering_annotation: Annotation) -> List[Annotation]:
         """Returns a list of covered annotations.
 
         Return all annotations that are covered
@@ -544,7 +575,7 @@ def select_covered(self, type_: Union[Type, str], covering_annotation: FeatureSt
                 result.append(annotation)
         return result
 
-    def select_covering(self, type_: Union[Type, str], covered_annotation: FeatureStructure) -> List[FeatureStructure]:
+    def select_covering(self, type_: Union[Type, str], covered_annotation: Annotation) -> List[Annotation]:
         """Returns a list of annotations that cover the given annotation.
 
         Return all annotations that are covering. This can be potentially be slow.
@@ -564,20 +595,40 @@ def select_covering(self, type_: Union[Type, str], covered_annotation: FeatureSt
         c_begin = covered_annotation.begin
         c_end = covered_annotation.end
 
-        # We iterate over all annotations and check whether the provided annotation
-        # is covered in the current annotation
+        result = []
         for annotation in self._get_feature_structures(t):
             if c_begin >= annotation.begin and c_end <= annotation.end:
-                yield annotation
+                result.append(annotation)
+        return result
 
-    def select_all(self) -> List[FeatureStructure]:
-        """Finds all feature structures in this Cas
+    def select_all_fs(self) -> List[FeatureStructure]:
+        """Returns all indexed feature structures (annotations and non-annotations) in the current view.
 
         Returns:
-            A list of all annotations in this Cas
+            A list of all indexed feature structures in the current view.
+        """
+        return self._current_view.get_all_fs()
+
+    def select_all_annotations(self) -> List[Annotation]:
+        """Returns all indexed annotations in the current view.
 
+        Non-annotation feature structures present in the view are filtered out, so it is safe
+        to access ``begin``/``end`` on the returned items.
+
+        Returns:
+            A list of all indexed annotations in the current view.
+        """
+        return cast(List[Annotation], [fs for fs in self._current_view.get_all_fs() if is_annotation(fs)])
+
+    @deprecation.deprecated(details="Use select_all_annotations() for annotations only or select_all_fs() for all indexed feature structures")
+    def select_all(self) -> List[Annotation]:
+        """Finds all annotations in this Cas.
+
+        .. deprecated::
+            Use :meth:`select_all_annotations` for annotations only, or
+            :meth:`select_all_fs` for all indexed feature structures.
         """
-        return self._current_view.get_all_annotations()
+        return self.select_all_annotations()
 
     # FS handling
 
@@ -838,7 +889,7 @@ def _find_all_fs(
         else:
             for sofa in self.sofas:
                 view = self.get_view(sofa.sofaID)
-                openlist.extend(view.select_all())
+                openlist.extend(view.select_all_fs())
 
         ts = self.typesystem
         while openlist:
@@ -939,8 +990,8 @@ def _copy(self) -> "Cas":
 
 
 def _sort_func(a: FeatureStructure) -> Tuple[int, int, int]:
-    d = a.__slots__
-    if "begin" in d and "end" in d:
-        return a.begin, a.end, id(a)
-    else:
-        return sys.maxsize, sys.maxsize, id(a)
+    if is_annotation(a):
+        return a.begin, a.end, a.xmiID if getattr(a, "xmiID", None) is not None else id(a)
+
+    # Non-annotation feature structures are sorted after annotations using large sentinels
+    return sys.maxsize, sys.maxsize, a.xmiID if getattr(a, "xmiID", None) is not None else id(a)

cassis/json.py

@@ -565,7 +565,7 @@ def _serialize_ref(self, fs) -> int:
     def _serialize_view(self, view: View):
         return {
             VIEW_SOFA_FIELD: view.sofa.xmiID,
-            VIEW_MEMBERS_FIELD: sorted(x.xmiID for x in view.get_all_annotations()),
+            VIEW_MEMBERS_FIELD: sorted(x.xmiID for x in view.get_all_fs()),
         }
 
     def _to_external_type_name(self, type_name: str):

cassis/typesystem.py

@@ -500,6 +500,23 @@ def __repr__(self):
         return str(self)
 
 
+@attr.s(slots=True, hash=False, eq=True, order=True, repr=False)
+class Annotation(FeatureStructure):
+    """Concrete base class for annotation instances.
+
+    Generated types that represent (subtypes of) `uima.tcas.Annotation` will
+    inherit from this class so that static typing can rely on a nominal base
+    providing `begin` and `end`.
+    """
+
+    begin: int = attr.ib(default=0)
+    end: int = attr.ib(default=0)
+
+
+def is_annotation(fs: FeatureStructure) -> bool:
+    return hasattr(fs, "begin") and isinstance(fs.begin, int) and hasattr(fs, "end") and isinstance(fs.end, int)
+
+
 @attr.s(slots=True, eq=False, order=False, repr=False)
 class Feature:
     """A feature defines one attribute of a feature structure"""
@@ -572,15 +589,44 @@ class Type:
     def __attrs_post_init__(self):
         """Build the constructor that can create feature structures of this type"""
         name = _string_to_valid_classname(self.name)
-        fields = {feature.name: attr.ib(default=None, repr=(feature.name != "sofa")) for feature in self.all_features}
+
+        # Determine whether this type is (transitively) a subtype of uima.tcas.Annotation
+        def _is_annotation_type(t: "Type") -> bool:
+            cur = t
+            while cur is not None:
+                if cur.name == TYPE_NAME_ANNOTATION:
+                    return True
+                cur = cur.supertype
+            return False
+
+        # When inheriting from our concrete Annotation base, do not redeclare
+        # the 'begin' and 'end' features as fields; they are already present.
+        fields = {}
+        for feature in self.all_features:
+            if feature.name in {"begin", "end"} and _is_annotation_type(self):
+                # skip - Annotation base provides these
+                continue
+            fields[feature.name] = attr.ib(default=None, repr=(feature.name != "sofa"))
         fields["type"] = attr.ib(default=self)
 
         # We assign this to a lambda to make it lazy
         # When creating large type systems, almost no types are used so
         # creating them on the fly is on average better
-        self._constructor_fn = lambda: attr.make_class(
-            name, fields, bases=(FeatureStructure,), slots=True, eq=False, order=False
-        )
+        bases = (Annotation,) if _is_annotation_type(self) else (FeatureStructure,)
+
+        def _make_fs_class():
+            cls = attr.make_class(name, fields, bases=bases, slots=True, eq=False, order=False)
+            # Ensure generated FS classes are hashable. When a class defines an
+            # __eq__ (inherited or generated) but no __hash__, Python makes
+            # instances unhashable. We want FeatureStructure-based instances to
+            # be usable as dict/set keys (they are keyed by xmiID), so assign the
+            # base FeatureStructure.__hash__ implementation to the generated
+            # class if it doesn't already provide one.
+            if getattr(cls, "__hash__", None) is None:
+                cls.__hash__ = FeatureStructure.__hash__
+            return cls
+
+        self._constructor_fn = _make_fs_class
 
     def __call__(self, **kwargs) -> FeatureStructure:
         """Creates an feature structure of this type