Merge pull request #2 from BrainAnnex/dev

Dev 4.2.0

Author: BrainAnnex

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "neoaccess"
-version = "4.1.0"
+version = "4.2.0"
 authors = [
   { name = "Julian West BrainAnnex.org" },
 ]
@@ -21,7 +21,7 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
-  "neo4j==4.3.9",
+  "neo4j==4.4.11",
   "numpy~=1.22.4",
   "pandas~=1.4.3",
 ]

requirements.txt

@@ -1,4 +1,4 @@
-neo4j==4.3.9
+neo4j==4.4.11
 numpy==1.22.4
 pandas==1.4.3
 

src/neoaccess/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "4.1.0"
+__version__ = "4.2.0"
 
 from .neoaccess import NeoAccess

src/neoaccess/cypher_utils.py

@@ -201,7 +201,7 @@ def assert_valid_internal_id(cls, internal_id: int) -> None:
         :return:            None
         """
         assert type(internal_id) == int, \
-            f"assert_valid_internal_id(): Neo4j internal ID's MUST be integers; the value passed was {type(internal_id)}"
+            f"assert_valid_internal_id(): Neo4j internal ID's MUST be integers; the value passed ({internal_id}) was {type(internal_id)}"
 
         # Note that 0 is a valid Neo4j ID (apparently inconsistently assigned, on occasion, by the database)
         assert internal_id >= 0, \

src/neoaccess/neoaccess.py

@@ -315,13 +315,15 @@ def query(self, q: str, data_binding=None, single_row=False, single_cell="", sin
 
 
 
-    def query_extended(self, q: str, params = None, flatten = False, fields_to_exclude = None) -> [dict]:
+    def query_extended(self, q: str, data_binding = None, flatten = False, fields_to_exclude = None) -> [dict]:
         """
-        Extended version of query(), meant to extract additional info for queries that return Graph Data Types,
+        Extended version of query(), meant to extract additional info
+        for queries that return Graph Data Types,
         i.e. nodes, relationships or paths,
         such as "MATCH (n) RETURN n", or "MATCH (n1)-[r]->(n2) RETURN r"
 
-        For example, useful in scenarios where nodes were returned, and their Neo4j internal IDs and/or labels are desired
+        For example, useful in scenarios where nodes were returned,
+        and their Neo4j internal IDs and/or labels are desired
         (in addition to all the properties and their values)
 
         Unless the flatten flag is True, individual records are kept as separate lists.
@@ -334,7 +336,7 @@ def query_extended(self, q: str, params = None, flatten = False, fields_to_exclu
             Try running with flatten=True "MATCH (b:boat), (c:car) RETURN b, c" on data like "CREATE (b:boat), (c1:car1), (c2:car2)"
 
         :param q:       A Cypher query
-        :param params:  An optional Cypher dictionary
+        :param data_binding:  An optional Cypher dictionary
                             EXAMPLE, assuming that the cypher string contains the substring "$age":
                                         {'age': 20}
         :param flatten: Flag indicating whether the Graph Data Types need to remain clustered by record,
@@ -345,20 +347,20 @@ def query_extended(self, q: str, params = None, flatten = False, fields_to_exclu
         :return:        A (possibly empty) list of dictionaries, if flatten is True,
                         or a list of list, if flatten is False.
                         Each item in the lists is a dictionary, with details that will depend on which Graph Data Types
-                                    were returned in the Cypher query.
-                                    EXAMPLE of individual items - for a returned NODE
-                                        {'gender': 'M', 'age': 20, 'internal_id': 123, 'neo4j_labels': ['patient']}
-                                    EXAMPLE of individual items - for a returned RELATIONSHIP
-                                        {'price': 7500, 'internal_id': 2,
-                                         'neo4j_start_node': <Node id=11 labels=frozenset() properties={}>,
-                                         'neo4j_end_node': <Node id=14 labels=frozenset() properties={}>,
-                                         'neo4j_type': 'bought_by'}]
+                                were returned in the Cypher query.
+                                EXAMPLE of *individual items* - for a returned NODE
+                                    {'gender': 'M', 'age': 20, 'internal_id': 123, 'neo4j_labels': ['patient']}
+                                EXAMPLE of *individual items* - for a returned RELATIONSHIP
+                                    {'price': 7500, 'internal_id': 2,
+                                     'neo4j_start_node': <Node id=11 labels=frozenset() properties={}>,
+                                     'neo4j_end_node': <Node id=14 labels=frozenset() properties={}>,
+                                     'neo4j_type': 'bought_by'}]
         """
         # Start a new session, use it, and then immediately close it
         with self.driver.session() as new_session:
-            result = new_session.run(q, params)
+            result = new_session.run(q, data_binding)
             if self.profiling:
-                print("-- query_extended() PROFILING ----------\n", q, "\n", params)
+                print("-- query_extended() PROFILING ----------\n", q, "\n", data_binding)
 
             # Note: A neo4j.Result iterable object (printing it, shows an object of type "neo4j.work.result.Result")
             #       See https://neo4j.com/docs/api/python-driver/current/api.html#neo4j.Result
@@ -836,8 +838,6 @@ def get_node_internal_id(self, match: dict) -> int:
         (node, where, data_binding) = CypherUtils.unpack_match(match_structure, include_dummy=False)
 
         q = f"MATCH {node} {CypherUtils.prepare_where(where)} RETURN id(n) AS INTERNAL_ID"
-        print(q)
-        print(data_binding)
         self.debug_query_print(q, data_binding, "get_node_internal_id")
 
         result = self.query(q, data_binding, single_column="INTERNAL_ID")
@@ -879,11 +879,12 @@ def ________CREATE_NODES________(DIVIDER):
 
     def create_node(self, labels, properties=None) -> int:
         """
-        Create a new node with the given label(s) and with the attributes/values specified in the properties dictionary.
+        Create a new node with the given label(s),
+        and with the attributes/values specified in the properties dictionary.
         Return the Neo4j internal ID of the node just created.
 
         :param labels:      A string, or list/tuple of strings, specifying Neo4j labels (ok to have blank spaces)
-        :param properties:  An optional (possibly empty or None) dictionary of properties to set for the new node.
+        :param properties:  OPTIONAL (possibly empty or None) dictionary of properties to set for the new node.
                                 EXAMPLE: {'age': 22, 'gender': 'F'}
 
         :return:            An integer with the Neo4j internal ID of the node just created
@@ -1030,7 +1031,7 @@ def create_attached_node(self, labels, properties = None,
     def create_node_with_links(self, labels, properties=None, links=None, merge=False) -> int:
         """
         Create a new node, with the given labels and optional properties,
-        and make it a parent of all the EXISTING nodes that are specified
+        and link it up to all the EXISTING nodes that are specified
         in the (possibly empty) list of link nodes, identified by their Neo4j internal ID's.
 
         The list of link nodes also contains the names to give to each link,
@@ -1729,14 +1730,14 @@ def add_links(self, match_from: Union[int, dict], match_to: Union[int, dict], re
 
     def add_links_fast(self, match_from: int, match_to: int, rel_name:str) -> int:
         """
-        Experimental first method optimized for speed.  Only internal database ID are used
+        Method optimized for speed.  Only internal database ID are used.
 
         Add a links (aka graph edges/relationships), with the specified rel_name,
         originating in the node identified by match_from,
         and terminating in the node identified by match_to
 
-        :param match_from:  An integer with a Neo4j node id
-        :param match_to:    An integer with a Neo4j node id
+        :param match_from:  An integer with an internal Neo4j node id
+        :param match_to:    An integer with an internal Neo4j node id
         :param rel_name:    The name to give to the new relationship between the 2 specified nodes.  Blanks allowed
 
         :return:            The number of links added.  If none got added, or in case of error, an Exception is raised
@@ -2131,20 +2132,21 @@ def count_links(self, match: Union[int, dict], rel_name: str, rel_dir="OUT", nei
 
 
 
-    def get_parents_and_children(self, node_id: int) -> ():
+    def get_parents_and_children(self, internal_id: int) -> ():
         """
         Fetch all the nodes connected to the given one by INbound relationships to it (its "parents"),
         as well as by OUTbound relationships to it (its "children")
+        TODO: allow specifying a relationship name to follow
 
-        :param node_id: An integer with a Neo4j internal node ID
-        :return:        A dictionary with 2 keys: 'parent_list' and 'child_list'
-                        The values are lists of dictionaries with 3 keys: "internal_id", "label", "rel"
-                            EXAMPLE of individual items in either parent_list or child_list:
-                            {'internal_id': 163, 'labels': ['Subject'], 'rel': 'HAS_TREATMENT'}
+        :param internal_id: An integer with a Neo4j internal node ID
+        :return:            A dictionary with 2 keys: 'parent_list' and 'child_list'
+                                The values are lists of dictionaries with 3 keys: "internal_id", "label", "rel"
+                                EXAMPLE of individual items in either parent_list or child_list:
+                                {'internal_id': 163, 'labels': ['Subject'], 'rel': 'HAS_TREATMENT'}
         """
 
         # Fetch the parents
-        cypher = f"MATCH (parent)-[inbound]->(n) WHERE id(n) = {node_id} " \
+        cypher = f"MATCH (parent)-[inbound]->(n) WHERE id(n) = {internal_id} " \
                  "RETURN id(parent) AS internal_id, labels(parent) AS labels, type(inbound) AS rel"
 
         parent_list = self.query(cypher)
@@ -2154,7 +2156,7 @@ def get_parents_and_children(self, node_id: int) -> ():
 
 
         # Fetch the children
-        cypher = f"MATCH (n)-[outbound]->(child) WHERE id(n) = {node_id} " \
+        cypher = f"MATCH (n)-[outbound]->(child) WHERE id(n) = {internal_id} " \
                  "RETURN id(child) AS internal_id, labels(child) AS labels, type(outbound) AS rel"
 
         child_list = self.query(cypher)
@@ -2167,6 +2169,56 @@ def get_parents_and_children(self, node_id: int) -> ():
 
 
 
+    def get_siblings(self, internal_id: int, rel_name: str, rel_dir="OUT") -> [int]:
+        """
+        Return the data of all the "sibling" nodes of the given one.
+        "Siblings" is meant as "sharing a link (by default outbound) of the specified name,
+        to a common other node".
+
+        EXAMPLE: 2 nodes, "French" and "German",
+                 each with a outbound link named "subcategory_of" to a third node,
+                 will be considered "siblings" under rel_name="subcategory_of" and rel_dir="OUT
+
+        :param internal_id: Integer with the internal database ID of the node of interest
+        :param rel_name:    The name of the relationship used to establish a "siblings" connection
+        :param rel_dir:     Either "OUT" (default) or "IN".  The link direction expected from the
+                                start node to its "parents" - and then IN REVERSE to the parent's children
+        :return:            A list of dictionaries, with one element for each "sibling";
+                                each element contains the 'internal_id' and 'neo4j_labels' keys,
+                                plus whatever attributes are stored on that node.
+                                EXAMPLE of single element:
+                                {'name': 'French', 'internal_id': 123, 'neo4j_labels': ['Categories']}
+        """
+        CypherUtils.assert_valid_internal_id(internal_id)
+
+        assert type(rel_name) == str, \
+            f"get_siblings(): argument `rel_name` must be a string; " \
+            f"the given value ({rel_name}) is of type {type(rel_name)}"
+
+        # Follow the links with the specified name, in the indicated direction from the given link,
+        # and then in the reverse direction
+        if rel_dir == "OUT":
+            q = f"""
+                MATCH (n) - [:{rel_name}] -> (parent) <- [:{rel_name}] - (sibling)
+                WHERE id(n) = $internal_id
+                RETURN sibling
+                """
+        elif rel_dir == "IN":
+            q = f"""
+                MATCH (n) <- [:{rel_name}] - (parent) - [:{rel_name}] -> (sibling)
+                WHERE id(n) = $internal_id
+                RETURN sibling
+                """
+        else:
+            raise Exception(f"get_siblings(): unknown value for the `rel_dir` argument ({rel_dir}); "
+                            f"allowed values are 'IN' and 'OUT'")
+
+        result = self.query_extended(q, data_binding={"internal_id": internal_id}, flatten=True)
+        return result
+
+
+
+
 
     #####################################################################################################
 
@@ -2206,9 +2258,9 @@ def get_label_properties(self, label:str) -> list:
             RETURN DISTINCT propertyName 
             ORDER BY propertyName
             """
-        params = {'label': label}
+        data_binding = {'label': label}
 
-        return [res['propertyName'] for res in self.query(q, params)]
+        return [res['propertyName'] for res in self.query(q, data_binding)]
 
 
 
@@ -3044,4 +3096,4 @@ def _debug_local(self) -> str:
 
         :return:
         """
-        return "remote"
+        return "local"

tests/test_neoaccess.py

@@ -38,7 +38,7 @@ def test_construction():
     obj1 = neo_access.NeoAccess(url, debug=False)       # Rely on default username/pass
 
     assert obj1.debug is False
-    assert obj1.version() == "4.3.9"    # Test the version of the Neo4j driver (this ought to match the value in requirements.txt)
+    assert obj1.version() == "4.4.11"    # Test the version of the Neo4j driver (this ought to match the value in requirements.txt)
 
 
     # Another way of instantiating the class
@@ -641,6 +641,94 @@ def test_get_parents_and_children(db):
 
 
 
+def test_get_siblings(db):
+    db.empty_dbase()
+
+    # Create "French" and "German" nodes, as subcategory of "Language"
+    q = '''
+        CREATE (c1 :Categories {name: "French"})-[:subcategory_of]->(p :Categories {name: "Language"})<-[:subcategory_of]-
+               (c2 :Categories {name: "German"})
+        RETURN id(c1) AS french_id, id(c2) AS german_id, id(p) AS language_id
+        '''
+    create_result = db.query(q, single_row=True)
+
+    (french_id, german_id, language_id) = list( map(create_result.get, ["french_id", "german_id", "language_id"]) )
+
+
+    # Get all the sibling categories of a given language
+
+    with pytest.raises(Exception):
+        db.get_siblings(internal_id=french_id, rel_name=666, rel_dir="OUT") # rel_name isn't a string
+
+    with pytest.raises(Exception):
+        db.get_siblings(internal_id="Do I look like an ID?", rel_name="subcategory_of", rel_dir="OUT")
+
+    with pytest.raises(Exception):
+        db.get_siblings(internal_id=french_id, rel_name="subcategory_of", rel_dir="Is it IN or OUT")
+
+    # The single sibling of "French" is "German"
+    result = db.get_siblings(internal_id=french_id, rel_name="subcategory_of", rel_dir="OUT")
+    assert result == [{'name': 'German', 'internal_id': german_id, 'neo4j_labels': ['Categories']}]
+
+    # Conversely, the single sibling of "German" is "French"
+    result = db.get_siblings(internal_id=german_id, rel_name="subcategory_of", rel_dir="OUT")
+    assert result == [{'name': 'French', 'internal_id': french_id, 'neo4j_labels': ['Categories']}]
+
+    # But attempting to follow the links in the opposite directions will yield no results
+    result = db.get_siblings(internal_id=german_id, rel_name="subcategory_of", rel_dir="IN")    # "wrong" direction
+    assert result == []
+
+    # Add a 3rd language category, "Italian", as a subcategory of the "Language" node
+    italian_id = db.create_attached_node(labels="Categories", properties={"name": "Italian"},
+                                         attached_to=language_id, rel_name="subcategory_of")
+
+    # Now, "French" will have 2 siblings instead of 1
+    result = db.get_siblings(internal_id=french_id, rel_name="subcategory_of", rel_dir="OUT")
+    expected = [{'name': 'Italian', 'internal_id': italian_id, 'neo4j_labels': ['Categories']},
+                {'name': 'German', 'internal_id': german_id, 'neo4j_labels': ['Categories']}]
+    assert compare_recordsets(result, expected)
+
+    # "Italian" will also have 2 siblings
+    result = db.get_siblings(internal_id=italian_id, rel_name="subcategory_of", rel_dir="OUT")
+    expected = [{'name': 'French', 'internal_id': french_id, 'neo4j_labels': ['Categories']},
+                {'name': 'German', 'internal_id': german_id, 'neo4j_labels': ['Categories']}]
+    assert compare_recordsets(result, expected)
+
+    # Add a node that is a "parent" of "French" and "Italian" thru a different relationship
+    db.create_attached_node(labels="Language Family", properties={"name": "Romance"},
+                            attached_to=[french_id, italian_id], rel_name="contains")
+
+    # Now, "French" will also have a sibling thru the "contains" relationship
+    result = db.get_siblings(internal_id=french_id, rel_name="contains", rel_dir="IN")
+    expected = [{'name': 'Italian', 'internal_id': italian_id, 'neo4j_labels': ['Categories']}]
+    assert compare_recordsets(result, expected)
+
+    # Likewise for the "Italian" node
+    result = db.get_siblings(internal_id=italian_id, rel_name="contains", rel_dir="IN")
+    expected = [{'name': 'French', 'internal_id': french_id, 'neo4j_labels': ['Categories']}]
+    assert compare_recordsets(result, expected)
+
+    # "Italian" still has 2 siblings thru the other relationship "subcategory_of"
+    result = db.get_siblings(internal_id=italian_id, rel_name="subcategory_of", rel_dir="OUT")
+    expected = [{'name': 'French', 'internal_id': french_id, 'neo4j_labels': ['Categories']},
+                {'name': 'German', 'internal_id': german_id, 'neo4j_labels': ['Categories']}]
+    assert compare_recordsets(result, expected)
+
+    # Add an unattached node
+    brazilian_id = db.create_node(labels="Categories", properties={"name": "Brazilian"})
+    result = db.get_siblings(internal_id=brazilian_id, rel_name="subcategory_of", rel_dir="OUT")
+    assert result == []     # No siblings
+
+    # After connecting the "Brazilian" node to the "Language" node, it has 3 siblings
+    db.add_links_fast(match_from=brazilian_id, match_to=language_id, rel_name="subcategory_of")
+    result = db.get_siblings(internal_id=brazilian_id, rel_name="subcategory_of", rel_dir="OUT")
+    expected = [{'name': 'French', 'internal_id': french_id, 'neo4j_labels': ['Categories']},
+                {'name': 'German', 'internal_id': german_id, 'neo4j_labels': ['Categories']},
+                {'name': 'Italian', 'internal_id': italian_id, 'neo4j_labels': ['Categories']}]
+    assert compare_recordsets(result, expected)
+
+
+
 
 ###  ~ CREATE NODES ~