Merge pull request #7 from BrainAnnex/dev

New version: 4.4.2

Author: BrainAnnex

src/neoaccess/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "4.4.1"
+__version__ = "4.4.2"
 
 from .neoaccess import NeoAccess

src/neoaccess/cypher_utils.py

@@ -104,7 +104,12 @@ def __init__(self, internal_id=None,
 
 
 
-    def __str__(self):
+    def __str__(self) -> str:
+        """
+        Return a description of this object
+
+        :return:
+        """
         return f"RAW match structure (object of class NodeSpecs):\n" \
                 f"    internal_id: {self.internal_id}" \
                 f"    labels: {self.labels}" \
@@ -191,11 +196,13 @@ def __init__(self, node_specs, dummy_node_name_if_missing=None):
 
         """
         IMPORTANT:  By our convention -
-                if internal_id is provided, all other conditions are DISREGARDED;
-                if it's missing, an implicit AND operation applies to all the specified conditions
+                1) if internal_id is provided, all other conditions are DISREGARDED;
+                2) if it's missing, an implicit "AND" operation applies to all the specified conditions
+                
+                TODO: maybe ditch (1) and give an option to what boolean to use in (2)
         """
-        if node_specs.internal_id is not None:     # If an internal node ID is specified, it over-rides all the other conditions
-                                        # CAUTION: internal_id might be 0 ; that's a valid Neo4j node ID
+        if node_specs.internal_id is not None:  # If an internal node ID is specified, it over-rides all the other conditions
+                                                # CAUTION: internal_id might be 0 ; that's a valid Neo4j node ID
             cypher_match = f"({dummy_node_name})"
             cypher_where = f"id({dummy_node_name}) = {node_specs.internal_id}"
             self.node = cypher_match
@@ -290,7 +297,11 @@ def __init__(self, node_specs, dummy_node_name_if_missing=None):
 
 
 
-    def __str__(self):
+    def __str__(self) -> str:
+        """
+        Return a description of this object
+        :return:
+        """
         return f"CYPHER-PROCESSED match structure (object of class CypherMatch):\n" \
                f"    node: {self.node}" \
                f"    where: {self.where}" \
@@ -336,7 +347,12 @@ def unpack_match(self) -> list:
 
 
     def extract_where_clause(self) -> str:
-        # TODO: new method to test.  Cleanup the WHERE clause, and prefix the "WHERE" keyword as needed
+        """
+        Cleanup the WHERE clause, and prefix the "WHERE" keyword as needed
+
+        TODO: new method to test
+        :return:
+        """
         return CypherUtils.prepare_where([self.where])
 
 
@@ -371,6 +387,8 @@ def process_match_structure(cls, handle: Union[int, NodeSpecs], dummy_node_name=
         Accept either a valid internal database node ID, or a "NodeSpecs" object (a "raw match"),
         and turn it into a "CypherMatch" object (a "processed match")
 
+        Note: no database operation is performed
+
         :param handle:          Either an integer with a valid internal database ID,
                                     or an object of type NodeSpecs
         :param dummy_node_name: A string that will be used inside a Cypher query, to refer to nodes
@@ -491,6 +509,8 @@ def valid_internal_id(cls, internal_id: int) -> bool:
         :param internal_id: An alleged internal database ID
         :return:            True if internal_id is a valid internal database ID, or False otherwise
         """
+        # TODO: put the actual logic here, instead of in assert_valid_internal_id()
+        # TODO: provide a method by the same name in NeoCore
         try:
             cls.assert_valid_internal_id(internal_id)
             return True
@@ -503,7 +523,7 @@ def valid_internal_id(cls, internal_id: int) -> bool:
     def prepare_labels(cls, labels :Union[str, List[str], Tuple[str]]) -> str:
         """
         Turn the given string, or list/tuple of strings - representing one or more Neo4j labels - into a string
-        suitable for inclusion in a Cypher query.
+        suitable for inclusion into a Cypher query.
         Blanks ARE allowed in the names.
         EXAMPLES:
             "" or None          both give rise to    ""