Update Spacy component, create a serializable component to save configuration. Remove get_kb_id() from Keyword ; add kb_id in Entity (Term renamed), adds a new IEntity interface ; refactor code accordingly

Author: scossin

CHANGELOG.md

@@ -10,7 +10,9 @@ In the Matcher class, this parameter becomes an attribute.
 - SpellWiseWrapper init: 'spellwise_algo' argument renamed 'measure' to be consistent with string distance algorithm.
 - SpellWiseWrapper *add_words_to_ignore* is deprecated, moved to the init function.
 - Fuzzyregex init: 'algo_name' argument renamed 'name'.
-
+- IKeyword: remove *get_kb_id* function, a keyword doesn't have a kb_id.
+An IEntity was created to store a kb_id attribute.
+- Term class is renamed 'Entity', code attribute is replace by 'kb_id'.
 
 ### Enhancement
 

docs/source/api_doc.rst

@@ -47,7 +47,13 @@ IKeyword
  :undoc-members:
  :show-inheritance:
 
- .. automethod:: __init__
+IEntity
+^^^^^^^^
+.. autoclass:: iamsystem.IEntity
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
 
 
 Keyword
@@ -59,17 +65,17 @@ Keyword
 
  .. automethod:: __init__
 
-Term
-^^^^^^^
-.. autoclass:: iamsystem.Term
+Entity
+^^^^^^
+.. autoclass:: iamsystem.Entity
  :members:
  :undoc-members:
  :show-inheritance:
 
  .. automethod:: __init__
 
 Terminology
-^^^^^^^
+^^^^^^^^^^^
 .. autoclass:: iamsystem.Terminology
  :members:
  :show-inheritance:

docs/source/brat.rst

@@ -31,7 +31,7 @@ The first line is the brat entity, the second is the brat note. T1 is the ID of
 Each note is linked to a brat entity by its ID, here T1.
 In the brat note, 'North America (NA)' is the comment related to this entity.
 By default, this comment is generated by calling the *__str__* method of the :ref:`api_doc:Keyword`.
-Here the __str__ method of the :ref:`api_doc:Term` class concatenated the label 'North America' and the code '(NA)'.
+Here the __str__ method of the :ref:`api_doc:Entity` class concatenated the label 'North America' and the code '(NA)'.
 You can modify this last value by overriding the *get_note* function of the :ref:`api_doc:BratDocument` class.
 
 Also note that in the above example, the Brat type "CONTINENT" is passed as a parameter and

docs/source/matcher.rst

@@ -18,10 +18,10 @@ The matcher outputs a list of :ref:`annotation:Annotation`.
 By default, it performs exact match only.
 A limitation of passing words to the matcher is that no attributes are associated.
 
-With a list of terms
-^^^^^^^^^^^^^^^^^^^^
+With a list of entities
+^^^^^^^^^^^^^^^^^^^^^^^
 Often, keywords are derived from a knowledge graph that associates a label with a unique identifier.
-The :ref:`api_doc:Term` has a *code* attribute to store an identifier.
+The :ref:`api_doc:Entity` has a *kb_id* attribute to store an identifier.
 
 .. literalinclude:: ../../tests/test_doc.py
  :language: python

src/iamsystem/__init__.py

@@ -9,7 +9,7 @@
  "NoStopwords",
  "NegativeStopwords",
  "Keyword",
- "Term",
+ "Entity",
  "Terminology",
  "Offsets",
  "Token",
@@ -36,6 +36,7 @@
  "FuzzyAlgo",
  "IOffsets",
  "IKeyword",
+ "IEntity",
  "NormLabelAlgo",
  "ISpan",
  "IToken",
@@ -66,10 +67,11 @@
 from iamsystem.fuzzy.spellwise import SpellWiseWrapper
 from iamsystem.fuzzy.util import IWords2ignore
 from iamsystem.fuzzy.util import SimpleWords2ignore
+from iamsystem.keywords.api import IEntity
 from iamsystem.keywords.api import IKeyword
 from iamsystem.keywords.collection import Terminology
+from iamsystem.keywords.keywords import Entity
 from iamsystem.keywords.keywords import Keyword
-from iamsystem.keywords.keywords import Term
 from iamsystem.matcher.annotation import Annotation
 from iamsystem.matcher.annotation import replace_annots
 from iamsystem.matcher.annotation import rm_nested_annots

src/iamsystem/fuzzy/simstring.py

@@ -5,6 +5,7 @@
 from enum import Enum
 from typing import Iterable
 from typing import Optional
+from typing import Union
 
 from pysimstring import simstring
 
@@ -29,8 +30,8 @@ class SimStringWrapper(StringDistance):
 
  def __init__(
  self,
- words=Iterable[str],
- measure=ESimStringMeasure.JACCARD,
+ words: Iterable[str],
+ measure: Union[str, ESimStringMeasure] = ESimStringMeasure.JACCARD,
  name: str = None,
  threshold=0.5,
  min_nb_char=5,
@@ -42,7 +43,7 @@ def __init__(
  An easy way to provide these words is to call
  :py:meth:`~iamsystem.Matcher.get_keywords_unigrams`.
  :param name: a name given to this algorithm. Default measure name.
- :param measure: a similarity measure selected from
+ :param measure: a similarity measure string or selected from
  :class:`~iamsystem.fuzzy.simstring.ESimStringMeasure`.
  Default JACCARD.
  :param threshold: similarity measure threshold.
@@ -51,6 +52,13 @@ def __init__(
  :param words2ignore: words that must be ignored by the algorithm to
  avoid false positives, for example English vocabulary words.
  """
+ # If an error occured during initialization, file is not opened
+ # the __del__ is called and return an error
+ # I add this attribute to check if the file was opened before trying
+ # to close it.
+ self.__file_is_open = False
+ if isinstance(measure, str):
+ measure = ESimStringMeasure[measure.upper()]
  if name is None:
  name = measure.name
  super().__init__(
@@ -63,6 +71,7 @@ def __init__(
  for word in words:
  ss_db.insert(word)
  self.ss_reader = simstring.reader(abs_path)
+ self.__file_is_open = True
  self.ss_reader.measure = getattr(simstring, measure.value)
  self.ss_reader.threshold = threshold
 
@@ -79,7 +88,8 @@ def __del__(self):
  # call. However, it takes more time. It seems to be ok to close
  # the file here.
  # https://stackoverflow.com/questions/44142836/open-file-inside-class
- self.ss_reader.close()
+ if self.__file_is_open:
+ self.ss_reader.close()
 
 
 class SimstringWriter:

src/iamsystem/fuzzy/spellwise.py

@@ -5,6 +5,7 @@
 from typing import Iterable
 from typing import List
 from typing import Optional
+from typing import Union
 
 from spellwise import CaverphoneOne
 from spellwise import CaverphoneTwo
@@ -61,16 +62,16 @@ class SpellWiseWrapper(StringDistance):
 
  def __init__(
  self,
- measure: ESpellWiseAlgo,
+ measure: Union[str, ESpellWiseAlgo],
  max_distance: int,
  min_nb_char=5,
  words2ignore: Optional[IWords2ignore] = None,
  name: str = None,
  ):
  """Create an instance to take advantage of a spellwise algorithm.
 
- :param measure: A value from :class:`~iamsystem.SpellWiseAlgo`
- enumerated list.
+ :param measure: The measure string or a value selected
+  from :class:`~iamsystem.SpellWiseAlgo` enumerated list.
  :param max_distance: maximum edit distance
  (see spellwise documentation).
  :param min_nb_char: the minimum number of characters a word
@@ -80,6 +81,8 @@ def __init__(
  :param name: a name given to this algorithm.
  Default: spellwise algorithm's name.
  """
+ if isinstance(measure, str):
+ measure = ESpellWiseAlgo[measure.upper()]
  if name is None:
  name = measure.name
  super().__init__(

src/iamsystem/keywords/api.py

@@ -11,9 +11,12 @@ class IKeyword(Protocol):
 
  label: str
 
- def get_kb_id(self):
- """Get the knowledge base id of this keyword."""
- raise NotImplementedError
+
+@runtime_checkable
+class IEntity(IKeyword, Protocol):
+ """An entity of a knowledge base."""
+
+ kb_id: str
 
 
 @runtime_checkable

src/iamsystem/keywords/keywords.py

@@ -1,47 +1,46 @@
 """ Keywords implementation."""
+from dataclasses import asdict
+from dataclasses import dataclass
+
+from iamsystem.keywords.api import IEntity
 from iamsystem.keywords.api import IKeyword
 
 
-class Keyword(IKeyword):
- """Base class to search keywords in a document."""
+# I considered TypedDict to store keywords but type checking is complicated.
+# See https://dev.to/meeshkan/typeddict-vs-dataclasses-in-python-epic-typing-battle-onb # noqa
 
- def __init__(self, label: str):
- """Create a keyword.
 
- :param label: a string to search in a document (ex: "heart failure").
- """
-  self.label = label
+@dataclass
+class Keyword(IKeyword):
+ """Base class to search keywords in a document.
 
- def get_kb_id(self):
- """Return the id of this keyword in a knowledge base.
-  It returns the label if this method is not overriden in the subclass.
+ Args:
+ label (str): The string to search.
+ """
 
- :return: A unique identifier.
- """
- return self.label
+ label: str
 
- def __str__(self):
- """Return the only attribute."""
- return self.label
+ def asdict(self):
+ """Returns the fields of the dataclass instance."""
+ return asdict(
+ self,
+ )
 
+ def __str__(self):
+ """Return a string representation."""
+ return f"{self.label}"
 
-class Term(Keyword):
- """This class represents a term in a particular domain where each
- keyword is associated to a unique identifier called a code."""
 
- def __init__(self, label: str, code: str):
- """Create a term.
+@dataclass
+class Entity(Keyword, IEntity):
+ """An entity of a knowledge base.
 
- :param label: a string to search in a document (ex: "heart failure").
- :param code: the code associated to this keyword.
- """
- super().__init__(label)
- self.code = code
+ Args:
+ kb_id (str): The entity id in the knowledge base.
+ """
 
- def get_kb_id(self):
- """returns the code of this term."""
- return self.code
+ kb_id: str
 
  def __str__(self):
  """An opinionated string representation."""
- return f"{self.label} ({self.code})"
+ return f"{self.label} ({self.kb_id})"

src/iamsystem/matcher/annotation.py

@@ -8,6 +8,7 @@
 from typing import Sequence
 from typing import Tuple
 
+from iamsystem.keywords.api import IEntity
 from iamsystem.keywords.api import IKeyword
 from iamsystem.matcher.util import TransitionState
 from iamsystem.tokenization.api import TokenT
@@ -59,7 +60,11 @@ def to_dict(self, text: str = None) -> Dict[str, Any]:
  "norm_label": self.norm_label,
  "tokens": [itoken_to_dict(token) for token in self.tokens],
  "algos": self.algos,
- "kb_ids": [keyword.get_kb_id() for keyword in self.keywords],
+ "kb_ids": [
+ keyword.kb_id
+ for keyword in self.keywords
+ if isinstance(keyword, IEntity)
+ ],
  "kw_labels": [keyword.label for keyword in self.keywords],
  }
  if text is not None: