Merge branch 'rc/5.5.0' of https://github.com/neo4j-contrib/neomodel into rc/5.5.0

Author: mariusconjeaud

doc/source/advanced_query_operations.rst

@@ -72,9 +72,9 @@ Here is a full example::
     await Coffee.nodes.fetch_relations("suppliers")
         .intermediate_transform(
             {
-                "coffee": "coffee",
-                "suppliers": NodeNameResolver("suppliers"),
-                "r": RelationNameResolver("suppliers"),
+                "coffee": {"source": "coffee"},
+                "suppliers": {"source": NodeNameResolver("suppliers")},
+                "r": {"source": RelationNameResolver("suppliers")},
                 "coffee": {"source": "coffee", "include_in_return": True}, # Only coffee will be returned
                 "suppliers": {"source": NodeNameResolver("suppliers")},
                 "r": {"source": RelationNameResolver("suppliers")},
@@ -146,3 +146,15 @@ In some cases though, it is not possible to set explicit aliases, for example wh
 .. note:: 
 
     When using the resolvers in combination with a traversal as in the example above, it will resolve the variable name of the last element in the traversal - the Species node for NodeNameResolver, and Coffee--Species relationship for RelationshipNameResolver.
+
+Another example is to reference the root node itself::
+
+    subquery = await Coffee.nodes.subquery(
+        Coffee.nodes.traverse_relations(suppliers="suppliers")
+        .intermediate_transform(
+            {"suppliers": {"source": "suppliers"}}, ordering=["suppliers.delivery_cost"]
+        )
+        .annotate(supps=Last(Collect("suppliers"))),
+        ["supps"],
+        [NodeNameResolver("self")], # This is the root Coffee node
+    )

doc/source/getting_started.rst

@@ -261,10 +261,10 @@ Retrieving additional relations
 .. note::
 
    You can fetch one or more relations within the same call
-   to `.fetch_relations()` and you can mix optional and non-optional
+   to `.traverse()` and you can mix optional and non-optional
    relations, like::
 
-    Person.nodes.fetch_relations('city__country', Optional('country')).all()
+    Person.nodes.traverse('city__country', Path(value='country', optional=True)).all()
 
 .. note::
 
@@ -368,12 +368,12 @@ The example below will show you how you can mix and match query operations, as d
     full_nodeset = (
         await Student.nodes.filter(name__istartswith="m", lives_in__name="Eiffel Tower") # Combine filters
         .order_by("name")
-        .fetch_relations(
+        .traverse(
             "parents",
-            Optional("children__preferred_course"),
-        ) # Combine fetch_relations
+            Path(value="children__preferred_course", optional=True)
+        ) # Combine traversals
         .subquery(
-            Student.nodes.fetch_relations("courses") # Root variable student will be auto-injected here
+            Student.nodes.traverse("courses") # Root variable student will be auto-injected here
             .intermediate_transform(
                 {"rel": RelationNameResolver("courses")},
                 ordering=[

doc/source/traversal.rst

@@ -6,7 +6,9 @@ Path traversal
 
 Neo4j is about traversing the graph, which means leveraging nodes and relations between them. This section will show you how to traverse the graph using neomodel.
 
-We will cover two methods : `traverse_relations` and `fetch_relations`. Those two methods are *mutually exclusive*, so you cannot chain them.
+For this, the method to use is `traverse`.
+
+Note that until version 6, two other methods are available, but deprecated : `traverse_relations` and `fetch_relations`. Those two methods are *mutually exclusive*, so you cannot chain them.
 
 For the examples in this section, we will be using the following model::
 
@@ -27,6 +29,59 @@ For the examples in this section, we will be using the following model::
 Traverse relations
 ------------------
 
+The `traverse` allows you to define multiple, multi-hop traversals, optionally returning traversed elements.
+
+For example, to find all `Coffee` nodes that have a supplier, and retrieve the country of that supplier, you can do::
+
+    Coffee.nodes.traverse("suppliers__country").all()
+
+This will generate a Cypher MATCH clause which traverses `Coffee<--Supplier-->Country`, and by default will return all traversed nodes and relationships.
+
+This method allows you to define a more complex `Path` object, giving you more control over the traversal.
+
+You can specify which elements to return, like::
+
+    # Return only the traversed nodes, not the relationships
+    Coffee.nodes.traverse(Path(value="suppliers__country", include_rels_in_return=False))
+
+    # Return only the traversed relationships, not the nodes
+    Coffee.nodes.traverse(Path(value="suppliers__country", include_nodes_in_return=False))
+
+You can specify that your traversal should be optional, like::
+
+    # Return only the traversed nodes, not the relationships
+    Coffee.nodes.traverse(Path(value="suppliers__country", optional=True))
+
+You can also alias the path, so that you can reference it later in the query, like::
+
+    Coffee.nodes.traverse(Path(value="suppliers__country", alias="supplier_country"))
+
+The `Country` nodes matched will be made available for the rest of the query, with the variable name `country`. Note that this aliasing is optional. See :ref:`Advanced query operations` for examples of how to use this aliasing.
+
+.. note::
+
+    The `traverse` method can be used to traverse multiple paths, like::
+
+        Coffee.nodes.traverse('suppliers__country', 'pub__city').all()
+
+    This will generate a Cypher MATCH clause that traverses both paths `Coffee<--Supplier-->Country` and `Coffee<--Pub-->City`.
+
+.. note::
+
+    When using `include_rels_in_return=True` (default), any relationship that you traverse using this method **MUST have a model defined**, even if only the default StructuredRel, like::
+        
+        class Person(StructuredNode):
+            country = RelationshipTo(Country, 'IS_FROM', model=StructuredRel)
+
+    Otherwise, neomodel will not be able to determine which relationship model to resolve into, and will fail.
+
+Traverse relations (deprecated)
+-------------------------------
+
+.. deprecated:: 5.5.0
+
+    This method is set to disappear in version 6, use `traverse` instead.
+
 The `traverse_relations` method allows you to filter on the existence of more complex traversals. For example, to find all `Coffee` nodes that have a supplier, and retrieve the country of that supplier, you can do::
 
     Coffee.nodes.traverse_relations(country='suppliers__country').all()
@@ -43,8 +98,12 @@ The `Country` nodes matched will be made available for the rest of the query, wi
 
     This will generate a Cypher MATCH clause that enforces the existence of at least one path like `Coffee<--Supplier-->Country` and `Coffee<--Pub-->City`.
 
-Fetch relations
----------------
+Fetch relations (deprecated)
+----------------------------
+
+.. deprecated:: 5.5.0
+
+    This method is set to disappear in version 6, use `traverse` instead.
 
 The syntax for `fetch_relations` is similar to `traverse_relations`, except that the generated Cypher will return all traversed objects (nodes and relations)::
 
@@ -59,8 +118,12 @@ The syntax for `fetch_relations` is similar to `traverse_relations`, except that
 
     Otherwise, neomodel will not be able to determine which relationship model to resolve into, and will fail.
 
-Optional match
---------------
+Optional match (deprecated)
+---------------------------
+
+.. deprecated:: 5.5.50
+
+    This method is set to disappear in version 6, use `traverse` instead.
 
 With both `traverse_relations` and `fetch_relations`, you can force the use of an ``OPTIONAL MATCH`` statement using the following syntax::
 

neomodel/async_/match.py

@@ -1,6 +1,7 @@
 import inspect
 import re
 import string
+import warnings
 from dataclasses import dataclass
 from typing import Any, AsyncIterator
 from typing import Optional as TOptional
@@ -576,9 +577,9 @@ def _additional_return(self, name: str) -> None:
             self._ast.additional_return.append(name)
 
     def build_traversal_from_path(
-        self, relation: dict, source_class: Any
+        self, relation: "Path", source_class: Any
     ) -> Tuple[str, Any]:
-        path: str = relation["path"]
+        path: str = relation.value
         stmt: str = ""
         source_class_iterator = source_class
         parts = re.split(path_split_regex, path)
@@ -606,27 +607,27 @@ def build_traversal_from_path(
                     if self._subquery_namespace:
                         # Don't include label in identifier if we are in a subquery
                         lhs_ident = lhs_name
-                elif relation["include_in_return"]:
+                elif relation.include_nodes_in_return:
                     self._additional_return(lhs_name)
             else:
                 lhs_ident = stmt
 
             already_present = part in subgraph
             rel_ident = self.create_relation_identifier()
             rhs_label = relationship.definition["node_class"].__label__
-            if relation.get("relation_filtering"):
+            if relation.relation_filtering:
                 rhs_name = rel_ident
                 rhs_ident = f":{rhs_label}"
             else:
-                if index + 1 == len(parts) and "alias" in relation:
+                if index + 1 == len(parts) and relation.alias:
                     # If an alias is defined, use it to store the last hop in the path
-                    rhs_name = relation["alias"]
+                    rhs_name = relation.alias
                 else:
                     rhs_name = f"{rhs_label.lower()}_{rel_iterator}"
                     rhs_name = self.create_node_identifier(rhs_name, rel_iterator)
                 rhs_ident = f"{rhs_name}:{rhs_label}"
 
-            if relation["include_in_return"] and not already_present:
+            if relation.include_nodes_in_return and not already_present:
                 self._additional_return(rhs_name)
 
             if not already_present:
@@ -640,11 +641,11 @@ def build_traversal_from_path(
                 existing_rhs_name = subgraph[part][
                     (
                         "rel_variable_name"
-                        if relation.get("relation_filtering")
+                        if relation.relation_filtering
                         else "variable_name"
                     )
                 ]
-            if relation["include_in_return"] and not already_present:
+            if relation.include_rels_in_return and not already_present:
                 self._additional_return(rel_ident)
             stmt = _rel_helper(
                 lhs=lhs_ident,
@@ -657,7 +658,7 @@ def build_traversal_from_path(
             subgraph = subgraph[part]["children"]
 
         if not already_present:
-            if relation.get("optional"):
+            if relation.optional:
                 self._ast.optional_match.append(stmt)
             else:
                 self._ast.match.append(stmt)
@@ -745,11 +746,10 @@ def _parse_path(
         is_optional_relation = False
         if not result:
             ident, target_class = self.build_traversal_from_path(
-                {
-                    "path": path,
-                    "include_in_return": True,
-                    "relation_filtering": is_rel_filter,
-                },
+                Path(
+                    value=path,
+                    relation_filtering=is_rel_filter,
+                ),
                 source_class,
             )
         else:
@@ -906,8 +906,8 @@ def lookup_query_variable(
         # (declared using fetch|traverse_relations)
         is_optional_relation = False
         for relation in self.node_set.relations_to_fetch:
-            if relation["path"] == path:
-                is_optional_relation = relation.get("optional", False)
+            if relation.value == path:
+                is_optional_relation = relation.optional
                 break
 
         subgraph = subgraph[traversals[0]]
@@ -1219,6 +1219,18 @@ class Optional:  # type: ignore[no-redef]
     relation: str
 
 
+@dataclass
+class Path:
+    """Path traversal definition."""
+
+    value: str
+    optional: bool = False
+    include_nodes_in_return: bool = True
+    include_rels_in_return: bool = True
+    relation_filtering: bool = False
+    alias: TOptional[str] = None
+
+
 @dataclass
 class RelationNameResolver:
     """Helper to refer to a relation variable name.
@@ -1386,7 +1398,7 @@ def __init__(self, source: Any) -> None:
         self.must_match: dict = {}
         self.dont_match: dict = {}
 
-        self.relations_to_fetch: list = []
+        self.relations_to_fetch: list[Path] = []
         self._extra_results: list = []
         self._subqueries: list[Subquery] = []
         self._intermediate_transforms: list = []
@@ -1547,30 +1559,47 @@ def order_by(self, *props: Any) -> "AsyncBaseSet":
         return self
 
     def _register_relation_to_fetch(
-        self,
-        relation_def: Any,
-        alias: TOptional[str] = None,
-        include_in_return: bool = True,
-    ) -> dict:
-        if isinstance(relation_def, Optional):
-            item = {"path": relation_def.relation, "optional": True}
+        self, relation_def: Any, alias: TOptional[str] = None
+    ) -> "Path":
+        if isinstance(relation_def, Path):
+            item = relation_def
         else:
-            item = {"path": relation_def}
-        item["include_in_return"] = include_in_return
-
+            item = Path(
+                value=relation_def,
+            )
         if alias:
-            item["alias"] = alias
+            item.alias = alias
         return item
 
     def unique_variables(self, *pathes: tuple[str, ...]) -> "AsyncNodeSet":
         """Generate unique variable names for the given pathes."""
         self._unique_variables = pathes
         return self
 
+    def traverse(
+        self, *pathes: tuple[str, ...], **aliased_pathes: dict
+    ) -> "AsyncNodeSet":
+        """Specify a set of pathes to traverse."""
+        relations = []
+        for path in pathes:
+            relations.append(self._register_relation_to_fetch(path))
+        for alias, aliased_path in aliased_pathes.items():
+            relations.append(
+                self._register_relation_to_fetch(aliased_path, alias=alias)
+            )
+        self.relations_to_fetch = relations
+        return self
+
     def fetch_relations(self, *relation_names: tuple[str, ...]) -> "AsyncNodeSet":
         """Specify a set of relations to traverse and return."""
+        warnings.warn(
+            "fetch_relations() will be deprecated in version 6, use traverse() instead.",
+            DeprecationWarning,
+        )
         relations = []
         for relation_name in relation_names:
+            if isinstance(relation_name, Optional):
+                relation_name = Path(value=relation_name.relation, optional=True)
             relations.append(self._register_relation_to_fetch(relation_name))
         self.relations_to_fetch = relations
         return self
@@ -1579,15 +1608,30 @@ def traverse_relations(
         self, *relation_names: tuple[str, ...], **aliased_relation_names: dict
     ) -> "AsyncNodeSet":
         """Specify a set of relations to traverse only."""
+
+        warnings.warn(
+            "traverse_relations() will be deprecated in version 6, use traverse() instead.",
+            DeprecationWarning,
+        )
+
+        def convert_to_path(input: Union[str, Optional]) -> Path:
+            if isinstance(input, Optional):
+                path = Path(value=input.relation, optional=True)
+            else:
+                path = Path(value=input)
+            path.include_nodes_in_return = False
+            path.include_rels_in_return = False
+            return path
+
         relations = []
         for relation_name in relation_names:
             relations.append(
-                self._register_relation_to_fetch(relation_name, include_in_return=False)
+                self._register_relation_to_fetch(convert_to_path(relation_name))
             )
         for alias, relation_def in aliased_relation_names.items():
             relations.append(
                 self._register_relation_to_fetch(
-                    relation_def, alias, include_in_return=False
+                    convert_to_path(relation_def), alias=alias
                 )
             )
 
@@ -1660,7 +1704,8 @@ async def resolve_subgraph(self) -> list:
         """
         if (
             self.relations_to_fetch
-            and not self.relations_to_fetch[0]["include_in_return"]
+            and not self.relations_to_fetch[0].include_nodes_in_return
+            and not self.relations_to_fetch[0].include_rels_in_return
         ):
             raise NotImplementedError(
                 "You cannot use traverse_relations() with resolve_subgraph(), use fetch_relations() instead."