Merge branch 'rc/6.1.0' into housekeeping/more-type-hinting

Author: mariusconjeaud

Changelog

@@ -1,3 +1,7 @@
+Version 6.1.0 2026-01
+* Add new exists operator in filter()
+* Add allow_reload to config to allow node redefinition in hot reload environments for development purposes
+
 Version 6.0.1 2025-12
 * Make async iterator fully async, like : async for node in MyNodeClass.nodes
 * Add thresholding to semantic indexes. Thanks to @greengori11a

doc/source/extending.rst

@@ -51,6 +51,52 @@ labels, the `__optional_labels__` property must be defined as a list of strings:
 
 .. note:: The size of the node class mapping grows exponentially with optional labels. Use with some caution.
 
+.. _allowing_class_reloading:
+
+Allowing Class Reloading
+-------------------------
+By default, neomodel prevents class redefinition to ensure the integrity of the node-class registry.
+However, in development environments with hot-reloading (like Streamlit or Django's development server),
+this behavior can be problematic as classes get redefined on every code change.
+
+To support hot-reload workflows, you can enable the ``allow_reload`` global config parameter:
+
+.. code-block:: python
+
+    from neomodel import config
+    config.ALLOW_RELOAD = True
+
+Or using the modern config API:
+
+.. code-block:: python
+
+    from neomodel.config import get_config
+    get_config().allow_reload = True
+
+When ``allow_reload`` is enabled:
+
+* Class redefinitions will issue a ``UserWarning`` instead of raising ``NodeClassAlreadyDefined``
+* The class registry will be updated with the new definition
+* This works for both standard classes and database-specific classes (with ``__target_databases__``)
+
+.. warning:: Only enable ``allow_reload`` in development environments. In production, the default behavior of raising ``NodeClassAlreadyDefined`` helps catch unintentional class redefinitions that could lead to subtle bugs.
+
+Example with Streamlit:
+
+.. code-block:: python
+
+    import streamlit as st
+    from neomodel import StructuredNode, StringProperty, config
+
+    config.DATABASE_URL = 'bolt://neo4j:neo4j@localhost:7687'
+    config.ALLOW_RELOAD = True  # Allows Streamlit page reloads
+
+    class User(StructuredNode):
+        name = StringProperty(unique_index=True)
+        email = StringProperty()
+
+    st.write("User model loaded successfully")
+
 
 Mixins
 ------
@@ -173,7 +219,9 @@ This automatic class resolution however, requires a bit of caution:
 
 2. Since the only way to resolve objects at runtime is this mapping of a set of labels to a class, then
    this mapping **must** be guaranteed to be unique. Therefore, if for any reason a class gets **redefined**, then
-   exception ``neomodel.exceptions.ClassAlreadyDefined`` will be raised.
+   exception ``neomodel.exceptions.NodeClassAlreadyDefined`` will be raised.
+        * This behavior can be overridden in development environments by setting ``__allow_reload__ = True`` on the class,
+          which will issue a warning instead of raising an exception. See the section on :ref:`allowing_class_reloading` for more details.
         * Given the above class hierarchy, suppose that an attempt was made to redefine one of the existing classes in
           the local scope of some function ::
 
@@ -199,10 +247,10 @@ This automatic class resolution however, requires a bit of caution:
           ``{"BasePerson", "PilotPerson"}`` to ``PilotPerson`` **in the global scope** with a mapping of the same
           set of labels but towards the class defined within the **local scope** of ``some_function``.
 
-3. Two classes with different names but the same __label__ override will also result in a ``ClassAlreadyDefined`` exception.
-   This can be avoided under certain circumstances, as explained in the next section on 'Database specific labels'. 
+3. Two classes with different names but the same __label__ override will also result in a ``NodeClassAlreadyDefined`` exception.
+   This can be avoided under certain circumstances, as explained in the next section on 'Database specific labels'.
 
-Both ``ModelDefinitionMismatch`` and ``ClassAlreadyDefined`` produce an error message that returns the labels of the
+Both ``ModelDefinitionMismatch`` and ``NodeClassAlreadyDefined`` produce an error message that returns the labels of the
 node that created the problem (either the `Node` returned from the database or the class that was attempted to be
 redefined) as well as the state of the current *node-class registry*. These two pieces of information can be used to
 debug the model mismatch further.
@@ -231,7 +279,7 @@ based on the database it was fetched from ::
     db.set_connection("bolt://neo4j:password@localhost:7687/db_one")
     patients = db.cypher_query("MATCH (n:Patient) RETURN n", resolve_objects=True) --> instance of PatientOne
 
-The following will result in a ``ClassAlreadyDefined`` exception, because when retrieving from ``db_one``,
+The following will result in a ``NodeClassAlreadyDefined`` exception, because when retrieving from ``db_one``,
 neomodel would not be able to decide which model to parse into ::
     class GeneralPatient(AsyncStructuredNode):
         __label__ = "Patient"

neomodel/_version.py

@@ -1 +1 @@
-__version__ = "6.0.1"
+__version__ = "6.1.0"

neomodel/async_/match.py

@@ -16,7 +16,7 @@
 from neomodel.properties import AliasProperty, ArrayProperty, Property
 from neomodel.semantic_filters import FulltextFilter, VectorFilter
 from neomodel.typing import Subquery, Transformation
-from neomodel.util import RelationshipDirection
+from neomodel.util import RelationshipDirection, deprecated
 
 CYPHER_ACTIONS_WITH_SIDE_EFFECT_EXPR = re.compile(r"(?i:MERGE|CREATE|DELETE|DETACH)")
 
@@ -162,6 +162,7 @@ def _rel_merge_helper(
 _SPECIAL_OPERATOR_ISNULL = "IS NULL"
 _SPECIAL_OPERATOR_ISNOTNULL = "IS NOT NULL"
 _SPECIAL_OPERATOR_REGEX = "=~"
+_SPECIAL_OPERATOR_EXISTS = "EXISTS"
 
 _UNARY_OPERATORS = (_SPECIAL_OPERATOR_ISNULL, _SPECIAL_OPERATOR_ISNOTNULL)
 
@@ -198,6 +199,7 @@ def _rel_merge_helper(
     "isnull": _SPECIAL_OPERATOR_ISNULL,
     "regex": _SPECIAL_OPERATOR_REGEX,
     "exact": "=",
+    "exists": "EXISTS",
 }
 # add all regex operators
 OPERATOR_TABLE.update(_REGEX_OPERATOR_TABLE)
@@ -243,6 +245,13 @@ def _handle_special_operators(
             raise ValueError(f"Value must be a bool for isnull operation on {key}")
         operator = "IS NULL" if value else "IS NOT NULL"
         deflated_value = None
+    elif operator == _SPECIAL_OPERATOR_EXISTS:
+        if not isinstance(value, bool):
+            raise ValueError(f"Value must be a bool for exists operation on {key}")
+        operator = (
+            f"NOT {_SPECIAL_OPERATOR_EXISTS}" if not value else _SPECIAL_OPERATOR_EXISTS
+        )
+        deflated_value = value
     elif operator in _REGEX_OPERATOR_TABLE.values():
         deflated_value = property_obj.deflate(value)
         if not isinstance(deflated_value, str):
@@ -309,6 +318,7 @@ def _process_filter_key(
         prop,
     ) = _initialize_filter_args_variables(cls, key)
 
+    hop_name = None
     for part in re.split(path_split_regex, key):
         defined_props = current_class.defined_properties(rels=True)
         # update defined props dictionary with relationship properties if
@@ -322,6 +332,7 @@ def _process_filter_key(
                 defined_props[part].lookup_node_class()
                 current_class = defined_props[part].definition["node_class"]
                 current_rel_model = defined_props[part].definition["model"]
+                hop_name = part
         elif part in OPERATOR_TABLE:
             operator = OPERATOR_TABLE[part]
             prop, _ = prop.rsplit("__", 1)
@@ -334,7 +345,11 @@ def _process_filter_key(
 
     if leaf_prop is None:
         raise ValueError(f"Badly formed filter, no property found in {key}")
-    if is_rel_property and current_rel_model:
+
+    if hop_name == leaf_prop:
+        # Path ended on a hop, not a property
+        property_obj = None
+    elif is_rel_property and current_rel_model:
         property_obj = getattr(current_rel_model, leaf_prop)
     else:
         property_obj = getattr(current_class, leaf_prop)
@@ -391,6 +406,71 @@ def process_has_args(
     return match, dont_match
 
 
+def generate_traversal_from_path(
+    relation: "Path",
+    source_class: Any,
+    create_ids: bool = False,
+    node_id_generator=None,
+    rel_id_generator=None,
+    namespace: str | None = None,
+):
+    """
+    Generator function to construct a cypher traversal from the given path.
+    """
+    path: str = relation.value
+    stmt: str = ""
+    source_class_iterator = source_class
+    parts = re.split(path_split_regex, path)
+    rel_iterator: str = ""
+    for index, part in enumerate(parts):
+        relationship = getattr(source_class_iterator, part)
+        if rel_iterator:
+            rel_iterator += "__"
+        rel_iterator += part
+        # build source
+        if "node_class" not in relationship.definition:
+            relationship.lookup_node_class()
+        lhs_name = None
+        if not stmt:
+            lhs_label = source_class_iterator.__label__
+            lhs_name = lhs_label.lower()
+            if create_ids and not namespace:
+                lhs_ident = f"{lhs_name}:{lhs_label}"
+            else:
+                lhs_ident = lhs_name
+        else:
+            lhs_ident = stmt
+
+        rel_ident = None
+        rhs_name = None
+        rhs_label = relationship.definition["node_class"].__label__
+        if create_ids:
+            rel_ident = rel_id_generator()
+            if relation.relation_filtering:
+                rhs_name = rel_ident
+                rhs_ident = f":{rhs_label}"
+            else:
+                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
+                else:
+                    rhs_name = f"{rhs_label.lower()}_{rel_iterator}"
+                    rhs_name = node_id_generator(rhs_name, rel_iterator)
+                rhs_ident = f"{rhs_name}:{rhs_label}"
+        else:
+            rhs_ident = f":{rhs_label}"
+
+        stmt = _rel_helper(
+            lhs=lhs_ident,
+            rhs=rhs_ident,
+            ident=rel_ident,
+            direction=relationship.definition["direction"],
+            relation_type=relationship.definition["relation_type"],
+        )
+        yield stmt, lhs_name, rhs_name, rel_ident, part, source_class_iterator
+        source_class_iterator = relationship.definition["node_class"]
+
+
 class QueryAST:
     match: list[str]
     optional_match: list[str]
@@ -659,54 +739,27 @@ def _additional_return(self, name: str) -> None:
     def build_traversal_from_path(
         self, relation: "Path", source_class: Any
     ) -> tuple[str, Any]:
-        path: str = relation.value
-        stmt: str = ""
-        source_class_iterator = source_class
-        parts = re.split(path_split_regex, path)
         subgraph = self._ast.subgraph
-        rel_iterator: str = ""
-        already_present = False
-        existing_rhs_name = ""
-        for index, part in enumerate(parts):
+        generator = generate_traversal_from_path(
+            relation,
+            source_class,
+            True,
+            self.create_node_identifier,
+            self.create_relation_identifier,
+            self._subquery_namespace,
+        )
+        for index, items in enumerate(generator):
+            stmt, lhs_name, rhs_name, rel_ident, part, source_class_iterator = items
             relationship = getattr(source_class_iterator, part)
-            if rel_iterator:
-                rel_iterator += "__"
-            rel_iterator += part
-            # build source
-            if "node_class" not in relationship.definition:
-                relationship.lookup_node_class()
-            if not stmt:
-                lhs_label = source_class_iterator.__label__
-                lhs_name = lhs_label.lower()
-                lhs_ident = f"{lhs_name}:{lhs_label}"
-                if not index:
-                    # This is the first one, we make sure that 'return'
-                    # contains the primary node so _contains() works
-                    # as usual
-                    self._ast.return_clause = lhs_name
-                    if self._subquery_namespace:
-                        # Don't include label in identifier if we are in a subquery
-                        lhs_ident = lhs_name
-                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.relation_filtering:
-                rhs_name = rel_ident
-                rhs_ident = f":{rhs_label}"
-            else:
-                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
-                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 not index:
+                # This is the first one, we make sure that 'return'
+                # contains the primary node so _contains() works
+                # as usual
+                self._ast.return_clause = lhs_name
+                self._additional_return(lhs_name)
 
+            already_present = part in subgraph
             if relation.include_nodes_in_return and not already_present:
                 self._additional_return(rhs_name)
 
@@ -727,14 +780,6 @@ def build_traversal_from_path(
                 ]
             if relation.include_rels_in_return and not already_present:
                 self._additional_return(rel_ident)
-            stmt = _rel_helper(
-                lhs=lhs_ident,
-                rhs=rhs_ident,
-                ident=rel_ident,
-                direction=relationship.definition["direction"],
-                relation_type=relationship.definition["relation_type"],
-            )
-            source_class_iterator = relationship.definition["node_class"]
             subgraph = subgraph[part]["children"]
 
         if not already_present:
@@ -842,6 +887,11 @@ def _finalize_filter_statement(
         if operator in _UNARY_OPERATORS:
             # unary operators do not have a parameter
             statement = f"{ident}.{prop} {operator}"
+        elif _SPECIAL_OPERATOR_EXISTS in operator:
+            statement = list(
+                generate_traversal_from_path(Path(prop), self.node_set.source)
+            )[-1][0]
+            statement = f"{'NOT ' if not val else ''}EXISTS {{ {statement} }}"
         else:
             place_holder = self._register_place_holder(ident + "_" + prop)
             if operator == _SPECIAL_OPERATOR_ARRAY_IN:
@@ -864,21 +914,22 @@ def _build_filter_statements(
         source_class: type[AsyncStructuredNode],
     ) -> None:
         for prop, op_and_val in filters.items():
-            is_rel_filter = "|" in prop
-            target_class = source_class
-            is_optional_relation = False
-            if "__" in prop or is_rel_filter:
-                (
-                    ident,
-                    prop,
-                    target_class,
-                    is_optional_relation,
-                ) = self._parse_path(source_class, prop)
             operator, val = op_and_val
-            if not is_rel_filter:
-                prop = target_class.defined_properties(rels=False)[
-                    prop
-                ].get_db_property_name(prop)
+            is_optional_relation = False
+            if _SPECIAL_OPERATOR_EXISTS not in operator:
+                is_rel_filter = "|" in prop
+                target_class = source_class
+                if "__" in prop or is_rel_filter:
+                    (
+                        ident,
+                        prop,
+                        target_class,
+                        is_optional_relation,
+                    ) = self._parse_path(source_class, prop)
+                if not is_rel_filter:
+                    prop = target_class.defined_properties(rels=False)[
+                        prop
+                    ].get_db_property_name(prop)
             statement = self._finalize_filter_statement(operator, ident, prop, val)
             target.append((statement, is_optional_relation))
 
@@ -1715,6 +1766,9 @@ def exclude(self, *args: Any, **kwargs: Any) -> Self:
             self.q_filters = Q(self.q_filters & ~Q(*args, **kwargs))
         return self
 
+    @deprecated(
+        "This method is deprecated and set to be removed in a future release. Please use .filter(has_rel__exists=True) instead."
+    )
     def has(self, **kwargs: Any) -> Self:
         must_match, dont_match = process_has_args(self.source_class, kwargs)
         self.must_match.update(must_match)