biocypher 0.7.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

biocypher/_translate.py

@@ -1,10 +1,11 @@
-"""
-BioCypher 'translation' module. Responsible for translating between the raw
-input data and the BioCypherNode and BioCypherEdge objects.
+"""BioCypher 'translation' module.
+
+Responsible for translating between the raw input data and the
+BioCypherNode and BioCypherEdge objects.
 """
 
 from collections.abc import Generator, Iterable
-from typing import Any, Optional, Union
+from typing import Any
 
 from more_itertools import peekable
 
@@ -19,21 +20,23 @@ __all__ = ["Translator"]
 
 
 class Translator:
-    """
-    Class responsible for exacting the translation process that is configured in
-    the schema_config.yaml file. Creates a mapping dictionary from that file,
-    and, given nodes and edges, translates them into BioCypherNodes and
-    BioCypherEdges. During this process, can also filter the properties of the
-    entities if the schema_config.yaml file specifies a property whitelist or
-    blacklist.
+    """Class responsible for exacting the translation process.
+
+    Translation is configured in the schema_config.yaml file. Creates a mapping
+    dictionary from that file, and, given nodes and edges, translates them into
+    BioCypherNodes and BioCypherEdges. During this process, can also filter the
+    properties of the entities if the schema_config.yaml file specifies a property
+    whitelist or blacklist.
 
     Provides utility functions for translating between input and output labels
     and cypher queries.
     """
 
     def __init__(self, ontology: "Ontology", strict_mode: bool = False):
-        """
+        """Initialise the translator.
+
         Args:
+        ----
             leaves:
                 Dictionary detailing the leaves of the hierarchy
                 tree representing the structure of the graph; the leaves are
@@ -43,8 +46,8 @@ class Translator:
             strict_mode:
                 If True, the translator will raise an error if input data do not
                 carry source, licence, and version information.
-        """
 
+        """
         self.ontology = ontology
         self.strict_mode = strict_mode
 
@@ -59,11 +62,7 @@ class Translator:
 
     def translate_entities(self, entities):
         entities = peekable(entities)
-        if (
-            isinstance(entities.peek(), BioCypherNode)
-            or isinstance(entities.peek(), BioCypherEdge)
-            or isinstance(entities.peek(), BioCypherRelAsNode)
-        ):
+        if isinstance(entities.peek(), BioCypherEdge | BioCypherNode | BioCypherRelAsNode):
             translated_entities = entities
         elif len(entities.peek()) < 4:
             translated_entities = self.translate_nodes(entities)
@@ -75,19 +74,20 @@ class Translator:
         self,
         node_tuples: Iterable,
     ) -> Generator[BioCypherNode, None, None]:
-        """
-        Translates input node representation to a representation that
-        conforms to the schema of the given BioCypher graph. For now
-        requires explicit statement of node type on pass.
+        """Translate input node representation.
+
+        Translate the node tuples to a representation that conforms to the
+        schema of the given BioCypher graph. For now requires explicit
+        statement of node type on pass.
 
         Args:
+        ----
             node_tuples (list of tuples): collection of tuples
                 representing individual nodes by their unique id and a type
                 that is translated from the original database notation to
                 the corresponding BioCypher notation.
 
         """
-
         self._log_begin_translate(node_tuples, "nodes")
 
         for _id, _type, _props in node_tuples:
@@ -101,10 +101,12 @@ class Translator:
 
                 for prop in required_props:
                     if prop not in _props:
-                        raise ValueError(
+                        msg = (
                             f"Property `{prop}` missing from node {_id}. "
-                            "Strict mode is enabled, so this is not allowed."
+                            "Strict mode is enabled, so this is not allowed.",
                         )
+                        logger.error(msg)
+                        raise ValueError(msg)
 
             # find the node in leaves that represents ontology node type
             _ontology_class = self._get_ontology_mapping(_type)
@@ -129,10 +131,11 @@ class Translator:
         self._log_finish_translate("nodes")
 
     def _get_preferred_id(self, _bl_type: str) -> str:
-        """
-        Returns the preferred id for the given Biolink type.
-        """
+        """Return the preferred id for the given Biolink type.
 
+        If the preferred id is not specified in the schema_config.yaml file,
+        return "id".
+        """
         return (
             self.ontology.mapping.extended_schema[_bl_type]["preferred_id"]
             if "preferred_id" in self.ontology.mapping.extended_schema.get(_bl_type, {})
@@ -140,10 +143,11 @@ class Translator:
         )
 
     def _filter_props(self, bl_type: str, props: dict) -> dict:
-        """
-        Filters properties for those specified in schema_config if any.
-        """
+        """Filter properties for those specified in schema_config if any.
 
+        If the properties are not specified in the schema_config.yaml file,
+        return the original properties.
+        """
         filter_props = self.ontology.mapping.extended_schema[bl_type].get("properties", {})
 
         # strict mode: add required properties (only if there is a whitelist)
@@ -179,14 +183,15 @@ class Translator:
     def translate_edges(
         self,
         edge_tuples: Iterable,
-    ) -> Generator[Union[BioCypherEdge, BioCypherRelAsNode], None, None]:
-        """
-        Translates input edge representation to a representation that
-        conforms to the schema of the given BioCypher graph. For now
-        requires explicit statement of edge type on pass.
+    ) -> Generator[BioCypherEdge | BioCypherRelAsNode, None, None]:
+        """Translate input edge representation.
 
-        Args:
+        Translate the edge tuples to a representation that conforms to the
+        schema of the given BioCypher graph. For now requires explicit
+        statement of edge type on pass.
 
+        Args:
+        ----
             edge_tuples (list of tuples):
 
                 collection of tuples representing source and target of
@@ -194,8 +199,8 @@ class Translator:
                 of interaction in the original database notation, which
                 is translated to BioCypher notation using the `leaves`.
                 Can optionally possess its own ID.
-        """
 
+        """
         self._log_begin_translate(edge_tuples, "edges")
 
         # legacy: deal with 4-tuples (no edge id)
@@ -208,18 +213,22 @@ class Translator:
             # check for strict mode requirements
             if self.strict_mode:
                 if "source" not in _props:
-                    raise ValueError(
-                        f"Edge {_id if _id else (_src, _tar)} does not have a `source` property.",
+                    msg = (
+                        f"Edge {_id if _id else (_src, _tar)} does not have a `source` property."
                         " This is required in strict mode.",
                     )
+                    logger.error(msg)
+                    raise ValueError(msg)
                 if "licence" not in _props:
-                    raise ValueError(
-                        f"Edge {_id if _id else (_src, _tar)} does not have a `licence` property.",
+                    msg = (
+                        f"Edge {_id if _id else (_src, _tar)} does not have a `licence` property."
                         " This is required in strict mode.",
                     )
+                    logger.error(msg)
+                    raise ValueError(msg)
 
             # match the input label (_type) to
-            # a Biolink label from schema_config
+            # an ontology label from schema_config
             bl_type = self._get_ontology_mapping(_type)
 
             if bl_type:
@@ -295,12 +304,12 @@ class Translator:
         self._log_finish_translate("edges")
 
     def _record_no_type(self, _type: Any, what: Any) -> None:
-        """
-        Records the type of a node or edge that is not represented in the
-        schema_config.
-        """
+        """Record the type of a non-represented node or edge.
 
-        logger.debug(f"No ontology type defined for `{_type}`: {what}")
+        In case of an entity that is not represented in the schema_config,
+        record the type and the entity.
+        """
+        logger.error(f"No ontology type defined for `{_type}`: {what}")
 
         if self.notype.get(_type, None):
             self.notype[_type] += 1
@@ -309,11 +318,11 @@ class Translator:
             self.notype[_type] = 1
 
     def get_missing_biolink_types(self) -> dict:
-        """
-        Returns a dictionary of types that were not represented in the
-        schema_config.
-        """
+        """Return a dictionary of non-represented types.
 
+        The dictionary contains the type as the key and the number of
+        occurrences as the value.
+        """
         return self.notype
 
     @staticmethod
@@ -327,12 +336,10 @@ class Translator:
         logger.debug(f"Finished translating {what} to BioCypher.")
 
     def _update_ontology_types(self):
-        """
-        Creates a dictionary to translate from input labels to ontology labels.
+        """Create a dictionary to translate from input to ontology labels.
 
         If multiple input labels, creates mapping for each.
         """
-
         self._ontology_mapping = {}
 
         for key, value in self.ontology.mapping.extended_schema.items():
@@ -351,47 +358,45 @@ class Translator:
             else:
                 self._add_translation_mappings(labels, key)
 
-    def _get_ontology_mapping(self, label: str) -> Optional[str]:
-        """
+    def _get_ontology_mapping(self, label: str) -> str | None:
+        """Find the ontology class for the given input type.
+
         For each given input type ("input_label" or "label_in_input"), find the
         corresponding ontology class in the leaves dictionary (from the
         `schema_config.yam`).
 
         Args:
+        ----
             label:
                 The input type to find (`input_label` or `label_in_input` in
                 `schema_config.yaml`).
-        """
 
+        """
+        # FIXME does not seem like a necessary function.
         # commented out until behaviour of _update_bl_types is fixed
         return self._ontology_mapping.get(label, None)
 
     def translate_term(self, term):
-        """
-        Translate a single term.
-        """
-
+        """Translate a single term."""
         return self.mappings.get(term, None)
 
     def reverse_translate_term(self, term):
-        """
-        Reverse translate a single term.
-        """
-
+        """Reverse translate a single term."""
         return self.reverse_mappings.get(term, None)
 
     def translate(self, query):
-        """
-        Translate a cypher query. Only translates labels as of now.
+        """Translate a cypher query.
+
+        Only translates labels as of now.
         """
         for key in self.mappings:
             query = query.replace(":" + key, ":" + self.mappings[key])
         return query
 
     def reverse_translate(self, query):
-        """
-        Reverse translate a cypher query. Only translates labels as of
-        now.
+        """Reverse translate a cypher query.
+
+        Only translates labels as of now.
         """
         for key in self.reverse_mappings:
             a = ":" + key + ")"
@@ -399,12 +404,14 @@ class Translator:
             # TODO this conditional probably does not cover all cases
             if a in query or b in query:
                 if isinstance(self.reverse_mappings[key], list):
-                    raise NotImplementedError(
+                    msg = (
                         "Reverse translation of multiple inputs not "
                         "implemented yet. Many-to-one mappings are "
                         "not reversible. "
                         f"({key} -> {self.reverse_mappings[key]})",
                     )
+                    logger.error(msg)
+                    raise NotImplementedError(msg)
                 else:
                     query = query.replace(
                         a,
@@ -413,10 +420,10 @@ class Translator:
         return query
 
     def _add_translation_mappings(self, original_name, biocypher_name):
-        """
-        Add translation mappings for a label and name. We use here the
-        PascalCase version of the BioCypher name, since sentence case is
-        not useful for Cypher queries.
+        """Add translation mappings for a label and name.
+
+        We use here the PascalCase version of the BioCypher name, since
+        sentence case is not useful for Cypher queries.
         """
         if isinstance(original_name, list):
             for on in original_name:
@@ -444,9 +451,7 @@ class Translator:
 
     @staticmethod
     def name_sentence_to_pascal(name: str) -> str:
-        """
-        Converts a name in sentence case to pascal case.
-        """
+        """Convert a name in sentence case to pascal case."""
         # split on dots if dot is present
         if "." in name:
             return ".".join(