biocypher 0.8.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(

biocypher/output/write/_batch_writer.py

@@ -1,3 +1,5 @@
+"""Abstract base class for all batch writers."""
+
 import glob
 import os
 import re
@@ -16,30 +18,37 @@ from biocypher.output.write._writer import _Writer
 
 
 class _BatchWriter(_Writer, ABC):
-    """Abstract batch writer class"""
+    """Abstract batch writer class."""
 
     @abstractmethod
     def _quote_string(self, value: str) -> str:
-        """Abstract method to quote a string. Escaping is handled by the database-specific writer."""
-        raise NotImplementedError(
-            "Database writer must override '_quote_string'",
-        )
+        """Quote a string.
+
+        Escaping is handled by the database-specific writer.
+        """
+        msg = "Database writer must override '_quote_string'"
+        logger.error(msg)
+        raise NotImplementedError(msg)
 
     @abstractmethod
     def _get_default_import_call_bin_prefix(self):
-        """Abstract method to provide the default string for the import call bin prefix.
+        """Provide the default string for the import call bin prefix.
 
         Returns
         -------
             str: The database-specific string for the path to the import call bin prefix
 
         """
-        raise NotImplementedError("Database writer must override '_get_default_import_call_bin_prefix'")
+        msg = "Database writer must override '_get_default_import_call_bin_prefix'"
+        logger.error(msg)
+        raise NotImplementedError(msg)
 
     @abstractmethod
     def _write_array_string(self, string_list):
-        """Abstract method to write the string representation of an array into a .csv file.
-        Different databases require different formats of array to optimize import speed.
+        """Write the string representation of an array into a .csv file.
+
+        Different databases require different formats of array to optimize
+        import speed.
 
         Args:
         ----
@@ -50,50 +59,65 @@ class _BatchWriter(_Writer, ABC):
             str: The database-specific string representation of an array
 
         """
-        raise NotImplementedError("Database writer must override '_write_array_string'")
+        msg = "Database writer must override '_write_array_string'"
+        logger.error(msg)
+        raise NotImplementedError(msg)
 
     @abstractmethod
     def _write_node_headers(self):
-        """Abstract method that takes care of importing properties of a graph entity that is represented
-        as a node as per the definition in the `schema_config.yaml`
+        """Write header files for nodes.
+
+        Write header files (node properties) for nodes as per the
+        definition in the `schema_config.yaml`.
 
         Returns
         -------
             bool: The return value. True for success, False otherwise.
 
         """
-        raise NotImplementedError("Database writer must override '_write_node_headers'")
+        msg = "Database writer must override '_write_node_headers'"
+        logger.error(msg)
+        raise NotImplementedError(msg)
 
     @abstractmethod
     def _write_edge_headers(self):
-        """Abstract method to write a database import-file for a graph entity that is represented
-        as an edge as per the definition in the `schema_config.yaml`,
-        containing only the header for this type of edge.
+        """Write a database import-file for an edge.
+
+        Write a database import-file for an edge as per the definition in
+        the `schema_config.yaml`, containing only the header for this type
+        of edge.
 
         Returns
         -------
             bool: The return value. True for success, False otherwise.
 
         """
-        raise NotImplementedError("Database writer must override '_write_edge_headers'")
+        msg = "Database writer must override '_write_edge_headers'"
+        logger.error(msg)
+        raise NotImplementedError(msg)
 
     @abstractmethod
     def _construct_import_call(self) -> str:
-        """Function to construct the import call detailing folder and
-        individual node and edge headers and data files, as well as
-        delimiters and database name. Built after all data has been
-        processed to ensure that nodes are called before any edges.
+        """Construct the import call.
+
+        Construct the import call detailing folder and individual node and
+        edge headers and data files, as well as delimiters and database name.
+        Built after all data has been processed to ensure that nodes are
+        called before any edges.
 
         Returns
         -------
             str: A bash command for csv import.
 
         """
-        raise NotImplementedError("Database writer must override '_construct_import_call'")
+        msg = "Database writer must override '_construct_import_call'"
+        logger.error(msg)
+        raise NotImplementedError(msg)
 
     @abstractmethod
     def _get_import_script_name(self) -> str:
-        """Returns the name of the import script.
+        """Return the name of the import script.
+
         The name will be chosen based on the used database.
 
         Returns
@@ -101,7 +125,9 @@ class _BatchWriter(_Writer, ABC):
             str: The name of the import script (ending in .sh)
 
         """
-        raise NotImplementedError("Database writer must override '_get_import_script_name'")
+        msg = "Database writer must override '_get_import_script_name'"
+        logger.error(msg)
+        raise NotImplementedError(msg)
 
     def __init__(
         self,
@@ -122,11 +148,14 @@ class _BatchWriter(_Writer, ABC):
         db_password: str = None,
         db_host: str = None,
         db_port: str = None,
-        rdf_format: str = None,
+        file_format: str = None,
         rdf_namespaces: dict = {},
         labels_order: str = "Ascending",
+        **kwargs,
     ):
-        """Abtract parent class for writing node and edge representations to disk
+        """Write node and edge representations to disk.
+
+        Abstract parent class for writing node and edge representations to disk
         using the format specified by each database type. The database-specific
         functions are implemented by the respective child-classes. This abstract
         class contains all methods expected by a bach writer instance, some of
@@ -180,7 +209,8 @@ class _BatchWriter(_Writer, ABC):
                 call.
 
             wipe:
-                Whether to force import (removing existing DB content). (Specific to Neo4j.)
+                Whether to force import (removing existing DB content).
+                    (Specific to Neo4j.)
 
             strict_mode:
                 Whether to enforce source, version, and license properties.
@@ -204,7 +234,7 @@ class _BatchWriter(_Writer, ABC):
             db_port:
                 The database port.
 
-            rdf_format:
+            file_format:
                 The format of RDF.
 
             rdf_namespaces:
@@ -226,7 +256,7 @@ class _BatchWriter(_Writer, ABC):
         self.db_password = db_password
         self.db_host = db_host or "localhost"
         self.db_port = db_port
-        self.rdf_format = rdf_format
+        self.file_format = file_format
         self.rdf_namespaces = rdf_namespaces
 
         self.delim, self.escaped_delim = self._process_delimiter(delimiter)
@@ -277,8 +307,16 @@ class _BatchWriter(_Writer, ABC):
             return self._import_call_file_prefix
 
     def _process_delimiter(self, delimiter: str) -> str:
-        """Return escaped characters in case of receiving their string
-        representation (e.g. tab for '\t').
+        """Process a delimited to escape correctly.
+
+        Args:
+        ----
+            delimiter (str): The delimiter to process.
+
+        Returns:
+        -------
+            tuple: The delimiter and its escaped representation.
+
         """
         if delimiter == "\\t":
             return "\t", "\\t"
@@ -287,7 +325,7 @@ class _BatchWriter(_Writer, ABC):
             return delimiter, delimiter
 
     def write_nodes(self, nodes, batch_size: int = int(1e6), force: bool = False):
-        """Wrapper for writing nodes and their headers.
+        """Write nodes and their headers.
 
         Args:
         ----
@@ -325,7 +363,7 @@ class _BatchWriter(_Writer, ABC):
         edges: list | GeneratorType,
         batch_size: int = int(1e6),
     ) -> bool:
-        """Wrapper for writing edges and their headers.
+        """Write edges and their headers.
 
         Args:
         ----
@@ -387,12 +425,13 @@ class _BatchWriter(_Writer, ABC):
         return True
 
     def _write_node_data(self, nodes, batch_size, force: bool = False):
-        """Writes biocypher nodes to CSV conforming to the headers created
-        with `_write_node_headers()`, and is actually required to be run
-        before calling `_write_node_headers()` to set the
-        :py:attr:`self.node_property_dict` for passing the node properties
-        to the instance. Expects list or generator of nodes from the
-        :py:class:`BioCypherNode` class.
+        """Write biocypher nodes to CSV.
+
+        Conforms to the headers created with `_write_node_headers()`, and
+        is actually required to be run before calling `_write_node_headers()`
+        to set the :py:attr:`self.node_property_dict` for passing the node
+        properties to the instance. Expects list or generator of nodes from
+        the :py:class:`BioCypherNode` class.
 
         Args:
         ----
@@ -571,7 +610,9 @@ class _BatchWriter(_Writer, ABC):
         prop_dict: dict,
         labels: str,
     ):
-        """This function takes one list of biocypher nodes and writes them
+        """Write a list of biocypher nodes to a CSV file.
+
+        This function takes one list of biocypher nodes and writes them
         to a Neo4j admin import compatible CSV file.
 
         Args:
@@ -655,7 +696,9 @@ class _BatchWriter(_Writer, ABC):
         return True
 
     def _write_edge_data(self, edges, batch_size):
-        """Writes biocypher edges to CSV conforming to the headers created
+        """Write biocypher edges to CSV.
+
+        Writes biocypher edges to CSV conforming to the headers created
         with `_write_edge_headers()`, and is actually required to be run
         before calling `_write_node_headers()` to set the
         :py:attr:`self.edge_property_dict` for passing the edge
@@ -804,7 +847,9 @@ class _BatchWriter(_Writer, ABC):
         label: str,
         prop_dict: dict,
     ):
-        """This function takes one list of biocypher edges and writes them
+        """Write a list of biocypher edges to a CSV file.
+
+        This function takes one list of biocypher edges and writes them
         to a Neo4j admin import compatible CSV file.
 
         Args:
@@ -923,7 +968,7 @@ class _BatchWriter(_Writer, ABC):
         return True
 
     def _write_next_part(self, label: str, lines: list):
-        """This function writes a list of strings to a new part file.
+        """Write a list of strings to a new part file.
 
         Args:
         ----
@@ -975,9 +1020,10 @@ class _BatchWriter(_Writer, ABC):
             self.parts[label].append(part)
 
     def get_import_call(self) -> str:
-        """Function to return the import call detailing folder and
-        individual node and edge headers and data files, as well as
-        delimiters and database name.
+        """Eeturn the import call.
+
+        Return the import call detailing folder and individual node and
+        edge headers and data files, as well as delimiters and database name.
 
         Returns
         -------
@@ -987,7 +1033,9 @@ class _BatchWriter(_Writer, ABC):
         return self._construct_import_call()
 
     def write_import_call(self) -> str:
-        """Function to write the import call detailing folder and
+        """Write the import call.
+
+        Function to write the import call detailing folder and
         individual node and edge headers and data files, as well as
         delimiters and database name, to the export folder as txt.
 
@@ -1006,9 +1054,10 @@ class _BatchWriter(_Writer, ABC):
 
 
 def parse_label(label: str) -> str:
-    """Check if the label is compliant with Neo4j naming conventions,
-    https://neo4j.com/docs/cypher-manual/current/syntax/naming/, and if not,
-    remove non-compliant characters.
+    """Check if the label is compliant with Neo4j naming conventions.
+
+    Check against https://neo4j.com/docs/cypher-manual/current/syntax/naming/,
+    and if not compliant, remove non-compliant characters.
 
     Args:
     ----