esgvoc 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

esgvoc/apps/drs/generator.py

@@ -1,19 +1,25 @@
 from typing import Any, Iterable, Mapping, cast
 
 import esgvoc.api.projects as projects
-from esgvoc.api.project_specs import (DrsCollection, DrsConstant, DrsPartKind,
-                                      DrsSpecification, DrsType)
-from esgvoc.apps.drs.report import (AssignedTerm, ConflictingCollections,
-                                    DrsGenerationReport, GenerationError,
-                                    GenerationIssue, GenerationWarning,
-                                    InvalidTerm, MissingTerm,
-                                    TooManyTermCollection)
+from esgvoc.api.project_specs import DrsCollection, DrsConstant, DrsPartKind, DrsSpecification, DrsType
+from esgvoc.apps.drs.report import (
+    AssignedTerm,
+    ConflictingCollections,
+    DrsGenerationReport,
+    GenerationError,
+    GenerationIssue,
+    GenerationWarning,
+    InvalidTerm,
+    MissingTerm,
+    TooManyTermCollection,
+)
 from esgvoc.apps.drs.validator import DrsApplication
+from esgvoc.core.exceptions import EsgvocDbError
 
 
 def _get_first_item(items: set[Any]) -> Any:
     result = None
-    for result in items:
+    for result in items:  # noqa: B007
         break
     return result
 
@@ -74,7 +80,6 @@ class DrsGenerator(DrsApplication):
         """
         return self._generate_from_bag_of_terms(terms, self.dataset_id_specs)
 
-
     def generate_file_name_from_mapping(self, mapping: Mapping[str, str]) -> DrsGenerationReport:
         """
         Generate a file name DRS expression from a mapping of collection ids and terms.
@@ -88,7 +93,7 @@ class DrsGenerator(DrsApplication):
         """
         report = self._generate_from_mapping(mapping, self.file_name_specs)
         report.generated_drs_expression = report.generated_drs_expression + \
-                                          self._get_full_file_name_extension()
+                                          self._get_full_file_name_extension() # noqa E127
         return report
 
     def generate_file_name_from_bag_of_terms(self, terms: Iterable[str]) -> DrsGenerationReport:
@@ -104,11 +109,11 @@ class DrsGenerator(DrsApplication):
         """
         report = self._generate_from_bag_of_terms(terms, self.file_name_specs)
         report.generated_drs_expression = report.generated_drs_expression + \
-                                          self._get_full_file_name_extension()
+                                          self._get_full_file_name_extension() # noqa E127
         return report
 
     def generate_from_mapping(self, mapping: Mapping[str, str],
-                              drs_type: DrsType|str) -> DrsGenerationReport:
+                              drs_type: DrsType | str) -> DrsGenerationReport:
         """
         Generate a DRS expression from a mapping of collection ids and terms.
 
@@ -127,10 +132,10 @@ class DrsGenerator(DrsApplication):
             case DrsType.DATASET_ID:
                 return self.generate_dataset_id_from_mapping(mapping=mapping)
             case _:
-                raise RuntimeError(f'unsupported drs type {drs_type}')
+                raise EsgvocDbError(f"unsupported drs type '{drs_type}'")
 
-    def generate_from_bag_of_terms(self, terms: Iterable[str], drs_type: DrsType|str) \
-                                                                              -> DrsGenerationReport:
+    def generate_from_bag_of_terms(self, terms: Iterable[str], drs_type: DrsType | str) \
+                                                                             -> DrsGenerationReport: # noqa E127
         """
         Generate a DRS expression from an unordered bag of terms.
 
@@ -149,26 +154,25 @@ class DrsGenerator(DrsApplication):
             case DrsType.DATASET_ID:
                 return self.generate_dataset_id_from_bag_of_terms(terms=terms)
             case _:
-                raise RuntimeError(f'unsupported drs type {drs_type}')
-
+                raise EsgvocDbError(f"unsupported drs type '{drs_type}'")
 
     def _generate_from_mapping(self, mapping: Mapping[str, str], specs: DrsSpecification) \
-                                                                              -> DrsGenerationReport:
+                                                                            -> DrsGenerationReport: # noqa E127
         drs_expression, errors, warnings = self.__generate_from_mapping(mapping, specs, True)
         if self.pedantic:
             errors.extend(warnings)
             warnings.clear()
         return DrsGenerationReport(project_id=self.project_id, type=specs.type,
-                                  given_mapping_or_bag_of_terms=mapping,
-                                  mapping_used=mapping,
-                                  generated_drs_expression=drs_expression,
-                                  errors=cast(list[GenerationError], errors),
-                                  warnings=cast(list[GenerationWarning], warnings))
+                                   given_mapping_or_bag_of_terms=mapping,
+                                   mapping_used=mapping,
+                                   generated_drs_expression=drs_expression,
+                                   errors=cast(list[GenerationError], errors),
+                                   warnings=cast(list[GenerationWarning], warnings))
 
     def __generate_from_mapping(self, mapping: Mapping[str, str],
                                 specs: DrsSpecification,
-                                has_to_valid_terms: bool)\
-                                          -> tuple[str, list[GenerationIssue], list[GenerationIssue]]:
+                                has_to_valid_terms: bool) \
+                                        -> tuple[str, list[GenerationIssue], list[GenerationIssue]]: # noqa E127
         errors: list[GenerationIssue] = list()
         warnings: list[GenerationIssue] = list()
         drs_expression = ""
@@ -186,19 +190,19 @@ class DrsGenerator(DrsApplication):
                                                                            collection_id)
                         if not matching_terms:
                             issue = InvalidTerm(term=part_value,
-                                                 term_position=part_position,
-                                                 collection_id_or_constant_value=collection_id)
+                                                term_position=part_position,
+                                                collection_id_or_constant_value=collection_id)
                             errors.append(issue)
                             part_value = DrsGenerationReport.INVALID_TAG
                 else:
                     other_issue = MissingTerm(collection_id=collection_id,
-                                               collection_position=part_position)
+                                              collection_position=part_position)
                     if collection_part.is_required:
                         errors.append(other_issue)
                         part_value = DrsGenerationReport.MISSING_TAG
                     else:
                         warnings.append(other_issue)
-                        continue # The for loop.
+                        continue  # The for loop.
             else:
                 constant_part = cast(DrsConstant, part)
                 part_value = constant_part.value
@@ -209,7 +213,7 @@ class DrsGenerator(DrsApplication):
         return drs_expression, errors, warnings
 
     def _generate_from_bag_of_terms(self, terms: Iterable[str], specs: DrsSpecification) \
-                                                                              -> DrsGenerationReport:
+                                                                             -> DrsGenerationReport: # noqa E127
         collection_terms_mapping: dict[str, set[str]] = dict()
         for term in terms:
             matching_terms = projects.valid_term_in_project(term, self.project_id)
@@ -226,14 +230,14 @@ class DrsGenerator(DrsApplication):
             errors.extend(warnings)
             warnings.clear()
         return DrsGenerationReport(project_id=self.project_id, type=specs.type,
-                                  given_mapping_or_bag_of_terms=terms,
-                                  mapping_used=mapping,generated_drs_expression=drs_expression,
-                                  errors=cast(list[GenerationError], errors),
-                                  warnings=cast(list[GenerationWarning], warnings))
+                                   given_mapping_or_bag_of_terms=terms,
+                                   mapping_used=mapping, generated_drs_expression=drs_expression,
+                                   errors=cast(list[GenerationError], errors),
+                                   warnings=cast(list[GenerationWarning], warnings))
 
     @staticmethod
     def _resolve_conflicts(collection_terms_mapping: dict[str, set[str]]) \
-                                            -> tuple[dict[str, set[str]], list[GenerationIssue]]:
+                                               -> tuple[dict[str, set[str]], list[GenerationIssue]]: # noqa E127
         warnings: list[GenerationIssue] = list()
         conflicting_collection_ids_list: list[list[str]] = list()
         collection_ids: list[str] = list(collection_terms_mapping.keys())
@@ -242,8 +246,8 @@ class DrsGenerator(DrsApplication):
         for l_collection_index in range(0, len_collection_ids - 1):
             conflicting_collection_ids: list[str] = list()
             for r_collection_index in range(l_collection_index + 1, len_collection_ids):
-                if collection_terms_mapping[collection_ids[l_collection_index]].isdisjoint \
-                       (collection_terms_mapping[collection_ids[r_collection_index]]):
+                if collection_terms_mapping[collection_ids[l_collection_index]].isdisjoint(
+                       collection_terms_mapping[collection_ids[r_collection_index]]):
                     continue
                 else:
                     not_registered = True
@@ -286,7 +290,7 @@ class DrsGenerator(DrsApplication):
                     DrsGenerator._remove_ids_from_conflicts(conflicting_collection_ids_list,
                                                             collection_ids_to_be_removed)
                     DrsGenerator._remove_term_from_other_term_sets(collection_terms_mapping,
-                                                      collection_ids_to_be_removed)
+                                                                   collection_ids_to_be_removed)
                 # Every time conflicting_collection_ids_list is modified, we must restart the loop,
                 # as conflicting collections may be resolved.
                 continue
@@ -306,7 +310,7 @@ class DrsGenerator(DrsApplication):
                 DrsGenerator._remove_ids_from_conflicts(conflicting_collection_ids_list,
                                                         wining_collection_ids)
                 DrsGenerator._remove_term_from_other_term_sets(collection_terms_mapping,
-                                                  wining_collection_ids)
+                                                               wining_collection_ids)
                 # Every time conflicting_collection_ids_list is modified, we must restart the loop,
                 # as conflicting collections may be resolved.
                 continue
@@ -316,13 +320,10 @@ class DrsGenerator(DrsApplication):
             wining_id_and_term_pairs: list[tuple[str, str]] = list()
             for collection_ids in conflicting_collection_ids_list:
                 for collection_index in range(0, len(collection_ids)):
+                    collection_set = collection_ids[collection_index + 1:] + collection_ids[:collection_index]
                     diff: set[str] = collection_terms_mapping[collection_ids[collection_index]]\
-                                         .difference(
-                                                     *[collection_terms_mapping[index]
-                                               for index in collection_ids[collection_index + 1 :] +\
-                                                        collection_ids[:collection_index]
-                                                      ]
-                                                    )
+                                         .difference(*[collection_terms_mapping[index] # noqa E127
+                                                     for index in collection_set])
                     if len(diff) == 1:
                         wining_id_and_term_pairs.append((collection_ids[collection_index],
                                                          _get_first_item(diff)))
@@ -341,12 +342,12 @@ class DrsGenerator(DrsApplication):
                                                                wining_collection_ids)
                 continue
             else:
-                break # Stop the loop when no progress is made.
+                break  # Stop the loop when no progress is made.
         return collection_terms_mapping, warnings
 
     @staticmethod
     def _check_collection_terms_mapping(collection_terms_mapping: dict[str, set[str]]) \
-                                                     -> tuple[dict[str, str], list[GenerationIssue]]:
+                                                    -> tuple[dict[str, str], list[GenerationIssue]]: # noqa E127
         errors: list[GenerationIssue] = list()
         # 1. Looking for collections that share strictly the same term(s).
         collection_ids: list[str] = list(collection_terms_mapping.keys())
@@ -358,7 +359,7 @@ class DrsGenerator(DrsApplication):
             for r_collection_index in range(l_collection_index + 1, len_collection_ids):
                 r_collection_id = collection_ids[r_collection_index]
                 r_term_set = collection_terms_mapping[r_collection_id]
-                # check if the set is empty because the difference will always be an empty set!
+                # Check if the set is empty because the difference will always be an empty set!
                 if l_term_set and (not l_term_set.difference(r_term_set)):
                     not_registered = True
                     for faulty_collections in faulty_collections_list:
@@ -386,9 +387,9 @@ class DrsGenerator(DrsApplication):
                 result[collection_id] = _get_first_item(term_set)
             elif len_term_set > 1:
                 other_issue = TooManyTermCollection(collection_id=collection_id,
-                                                     terms=_transform_set_and_sort(term_set))
+                                                    terms=_transform_set_and_sort(term_set))
                 errors.append(other_issue)
-            #else: Don't add emptied collection to the result.
+            # else: Don't add emptied collection to the result.
         return result, errors
 
     @staticmethod
@@ -408,22 +409,3 @@ class DrsGenerator(DrsApplication):
             for conflicting_collection_ids in conflicting_collection_ids_list:
                 if collection_id_to_be_removed in conflicting_collection_ids:
                     conflicting_collection_ids.remove(collection_id_to_be_removed)
-
-
-if __name__ == "__main__":
-    project_id = 'cmip6plus'
-    generator = DrsGenerator(project_id)
-    mapping = \
-    {
-        'member_id': 'r2i2p1f2',
-        'activity_id': 'CMIP',
-        'source_id': 'MIROC6',
-        'mip_era': 'CMIP6Plus',
-        'experiment_id': 'amip',
-        'variable_id': 'od550aer',
-        'table_id': 'ACmon',
-        'grid_label': 'gn',
-        'institution_id': 'IPSL',
-    }
-    report = generator.generate_file_name_from_mapping(mapping)
-    print(report.warnings)

esgvoc/apps/drs/report.py

@@ -1,7 +1,6 @@
 from abc import ABC, abstractmethod
 from enum import Enum
-from typing import (Annotated, Any, ClassVar, Iterable, Literal, Mapping,
-                    Protocol)
+from typing import Annotated, Any, ClassVar, Iterable, Literal, Mapping, Protocol
 
 from pydantic import BaseModel, Field, computed_field
 
@@ -46,15 +45,19 @@ class ParsingIssueVisitor(Protocol):
     def visit_space_issue(self, issue: "Space") -> Any:
         """Visit a space issue."""
         pass
+
     def visit_unparsable_issue(self, issue: "Unparsable") -> Any:
         """Visit a unparsable issue."""
         pass
+
     def visit_extra_separator_issue(self, issue: "ExtraSeparator") -> Any:
         """Visit an extra separator issue."""
         pass
+
     def visit_extra_char_issue(self, issue: "ExtraChar") -> Any:
         """Visit an extra char issue."""
         pass
+
     def visit_blank_term_issue(self, issue: "BlankTerm") -> Any:
         """Visit a blank term issue."""
         pass
@@ -67,12 +70,15 @@ class ComplianceIssueVisitor(Protocol):
     def visit_filename_extension_issue(self, issue: "FileNameExtensionIssue") -> Any:
         """Visit a file name extension issue."""
         pass
+
     def visit_invalid_term_issue(self, issue: "InvalidTerm") -> Any:
         """Visit an invalid term issue."""
         pass
+
     def visit_extra_term_issue(self, issue: "ExtraTerm") -> Any:
         """Visit an extra term issue."""
         pass
+
     def visit_missing_term_issue(self, issue: "MissingTerm") -> Any:
         """Visit a missing term issue."""
         pass
@@ -89,15 +95,19 @@ class GenerationIssueVisitor(Protocol):
     def visit_invalid_term_issue(self, issue: "InvalidTerm") -> Any:
         """Visit an invalid term issue."""
         pass
+
     def visit_missing_term_issue(self, issue: "MissingTerm") -> Any:
         """Visit a missing term issue."""
         pass
+
     def visit_too_many_terms_collection_issue(self, issue: "TooManyTermCollection") -> Any:
         """Visit a too many terms collection issue."""
         pass
+
     def visit_conflicting_collections_issue(self, issue: "ConflictingCollections") -> Any:
         """Visit a conflicting collections issue."""
         pass
+
     def visit_assign_term_issue(self, issue: "AssignedTerm") -> Any:
         """Visit an assign term issue."""
         pass
@@ -126,7 +136,7 @@ class ParsingIssue(DrsIssue):
     """
     Generic class for the DRS parsing issues.
     """
-    column: int|None = None
+    column: int | None = None
     """the column of faulty characters."""
 
     @abstractmethod
@@ -148,10 +158,13 @@ class Space(ParsingIssue):
     Note: `column` is `None`.
     """
     kind: Literal[IssueKind.SPACE] = IssueKind.SPACE
+
     def accept(self, visitor: ParsingIssueVisitor) -> Any:
         return visitor.visit_space_issue(self)
+
     def __str__(self):
         return "expression is surrounded by white space[s]"
+
     def __repr__(self) -> str:
         return self.__str__()
 
@@ -164,10 +177,13 @@ class Unparsable(ParsingIssue):
     expected_drs_type: DrsType
     """The expected DRS type of the expression (directory, file name or dataset id)."""
     kind: Literal[IssueKind.UNPARSABLE] = IssueKind.UNPARSABLE
+
     def accept(self, visitor: ParsingIssueVisitor) -> Any:
         return visitor.visit_unparsable_issue(self)
+
     def __str__(self):
         return "unable to parse this expression"
+
     def __repr__(self) -> str:
         return self.__str__()
 
@@ -177,10 +193,13 @@ class ExtraSeparator(ParsingIssue):
     Represents a problem of multiple separator occurrences in the DRS expression.
     """
     kind: Literal[IssueKind.EXTRA_SEPARATOR] = IssueKind.EXTRA_SEPARATOR
+
     def accept(self, visitor: ParsingIssueVisitor) -> Any:
         return visitor.visit_extra_separator_issue(self)
+
     def __str__(self):
         return f"extra separator(s) at column {self.column}"
+
     def __repr__(self) -> str:
         return self.__str__()
 
@@ -190,10 +209,13 @@ class ExtraChar(ParsingIssue):
     Represents a problem of extra characters at the end of the DRS expression.
     """
     kind: Literal[IssueKind.EXTRA_CHAR] = IssueKind.EXTRA_CHAR
+
     def accept(self, visitor: ParsingIssueVisitor) -> Any:
         return visitor.visit_extra_char_issue(self)
+
     def __str__(self):
         return f"extra character(s) at column {self.column}"
+
     def __repr__(self) -> str:
         return self.__str__()
 
@@ -203,10 +225,13 @@ class BlankTerm(ParsingIssue):
     Represents a problem of blank term in the DRS expression (i.e., space[s] surrounded by separators).
     """
     kind: Literal[IssueKind.BLANK_TERM] = IssueKind.BLANK_TERM
+
     def accept(self, visitor: ParsingIssueVisitor) -> Any:
         return visitor.visit_blank_term_issue(self)
+
     def __str__(self):
         return f"blank term at column {self.column}"
+
     def __repr__(self) -> str:
         return self.__str__()
 
@@ -235,8 +260,10 @@ class FileNameExtensionIssue(ComplianceIssue):
     expected_extension: str
     """The expected file name extension."""
     kind: Literal[IssueKind.FILE_NAME] = IssueKind.FILE_NAME
+
     def accept(self, visitor: ComplianceIssueVisitor) -> Any:
         return visitor.visit_filename_extension_issue(self)
+
     def __str__(self):
         return f"filename extension missing or not compliant with '{self.expected_extension}'"
 
@@ -275,10 +302,14 @@ class InvalidTerm(TermIssue, GenerationIssue):
     collection_id_or_constant_value: str
     """The collection id or the constant part of a DRS specification."""
     kind: Literal[IssueKind.INVALID_TERM] = IssueKind.INVALID_TERM
-    def accept(self, visitor: ComplianceIssueVisitor|GenerationIssueVisitor) -> Any:
+
+    def accept(self, visitor: ComplianceIssueVisitor | GenerationIssueVisitor) -> Any:
         return visitor.visit_invalid_term_issue(self)
+
     def __str__(self):
-        return f"term '{self.term}' not compliant with {self.collection_id_or_constant_value} at position {self.term_position}"
+        return f"term '{self.term}' not compliant with {self.collection_id_or_constant_value} at " + \
+               f"position {self.term_position}"
+
     def __repr__(self) -> str:
         return self.__str__()
 
@@ -290,16 +321,19 @@ class ExtraTerm(TermIssue):
     (`collection_id` is `None`) or it has been invalidated by an optional collection part
     of the DRS specification (`collection_id` is set).
     """
-    collection_id: str|None
+    collection_id: str | None
     """The optional collection id or `None`."""
     kind: Literal[IssueKind.EXTRA_TERM] = IssueKind.EXTRA_TERM
+
     def accept(self, visitor: ComplianceIssueVisitor) -> Any:
         return visitor.visit_extra_term_issue(self)
+
     def __str__(self):
         repr = f"extra term {self.term}"
         if self.collection_id:
             repr += f" invalidated by the optional collection {self.collection_id}"
         return repr + f" at position {self.term_position}"
+
     def __repr__(self) -> str:
         return self.__str__()
 
@@ -313,10 +347,13 @@ class MissingTerm(ComplianceIssue, GenerationIssue):
     collection_position: int
     """The collection part position (not the column of the characters)."""
     kind: Literal[IssueKind.MISSING_TERM] = IssueKind.MISSING_TERM
-    def accept(self, visitor: ComplianceIssueVisitor|GenerationIssueVisitor) -> Any:
+
+    def accept(self, visitor: ComplianceIssueVisitor | GenerationIssueVisitor) -> Any:
         return visitor.visit_missing_term_issue(self)
+
     def __str__(self):
         return f'missing term for {self.collection_id} at position {self.collection_position}'
+
     def __repr__(self) -> str:
         return self.__str__()
 
@@ -332,6 +369,7 @@ class TooManyTermCollection(GenerationIssue):
     terms: list[str]
     """The faulty terms."""
     kind: Literal[IssueKind.TOO_MANY] = IssueKind.TOO_MANY
+
     def accept(self, visitor: GenerationIssueVisitor) -> Any:
         return visitor.visit_too_many_terms_collection_issue(self)
 
@@ -339,6 +377,7 @@ class TooManyTermCollection(GenerationIssue):
         terms_str = ", ".join(term for term in self.terms)
         result = f'collection {self.collection_id} has more than one term ({terms_str})'
         return result
+
     def __repr__(self) -> str:
         return self.__str__()
 
@@ -354,13 +393,16 @@ class ConflictingCollections(GenerationIssue):
     terms: list[str]
     """The shared terms."""
     kind: Literal[IssueKind.CONFLICT] = IssueKind.CONFLICT
+
     def accept(self, visitor: GenerationIssueVisitor) -> Any:
         return visitor.visit_conflicting_collections_issue(self)
+
     def __str__(self):
         collection_ids_str = ", ".join(collection_id for collection_id in self.collection_ids)
         terms_str = ", ".join(term for term in self.terms)
         result = f"collections {collection_ids_str} are competing for the same term(s) {terms_str}"
         return result
+
     def __repr__(self) -> str:
         return self.__str__()
 
@@ -375,22 +417,25 @@ class AssignedTerm(GenerationIssue):
     term: str
     """The term."""
     kind: Literal[IssueKind.ASSIGNED] = IssueKind.ASSIGNED
+
     def accept(self, visitor: GenerationIssueVisitor) -> Any:
         return visitor.visit_assign_term_issue(self)
+
     def __str__(self):
         result = f"assign term {self.term} for collection {self.collection_id}"
         return result
+
     def __repr__(self) -> str:
         return self.__str__()
 
 
-GenerationError =  Annotated[AssignedTerm | ConflictingCollections |  InvalidTerm | MissingTerm | \
+GenerationError = Annotated[AssignedTerm | ConflictingCollections | InvalidTerm | MissingTerm |
                             TooManyTermCollection, Field(discriminator='kind')]
 GenerationWarning = Annotated[AssignedTerm | MissingTerm, Field(discriminator='kind')]
 
-ValidationError = Annotated[BlankTerm | ExtraChar | ExtraSeparator | ExtraTerm | \
-                           FileNameExtensionIssue | InvalidTerm | MissingTerm | Space | Unparsable,
-                           Field(discriminator='kind')]
+ValidationError = Annotated[BlankTerm | ExtraChar | ExtraSeparator | ExtraTerm |
+                            FileNameExtensionIssue | InvalidTerm | MissingTerm | Space | Unparsable,
+                            Field(discriminator='kind')]
 ValidationWarning = Annotated[ExtraSeparator | MissingTerm | Space, Field(discriminator='kind')]
 
 
@@ -411,19 +456,19 @@ class DrsReport(BaseModel):
     warnings: list
     """A list of DRS issues that are considered as warnings."""
 
-    @computed_field # type: ignore
+    @computed_field  # type: ignore
     @property
     def nb_errors(self) -> int:
         """The number of errors."""
         return len(self.errors) if self.errors else 0
 
-    @computed_field # type: ignore
+    @computed_field  # type: ignore
     @property
     def nb_warnings(self) -> int:
         """The number of warnings."""
         return len(self.warnings) if self.warnings else 0
 
-    @computed_field # type: ignore
+    @computed_field  # type: ignore
     @property
     def validated(self) -> bool:
         """The correctness of the result of the DRS application."""
@@ -469,7 +514,7 @@ class DrsGenerationReport(DrsReport):
     INVALID_TAG: ClassVar[str] = '[INVALID]'
     """Tag used in the DRS generated expression to replace a invalid term."""
 
-    given_mapping_or_bag_of_terms: Mapping|Iterable
+    given_mapping_or_bag_of_terms: Mapping | Iterable
     """The mapping or the bag of terms given."""
 
     mapping_used: Mapping