Merge pull request #1007 from compas-dev/where-api

Add support for kwargs to where filters

Author: tomvanmele

CHANGELOG.md

@@ -39,6 +39,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Changed `planarity` to optional requirement on all platforms.
 * Changed `numba` to optional requirement on all platforms.
 * Changed raw github content path for `compas.get`.
+* Changed `compas.datastructures.Graph.nodes_where` to accept conditions as kwargs.
+* Changed `compas.datastructures.Graph.edges_where` to accept conditions as kwargs.
+* Changed `compas.datastructures.Halfedge.vertices_where` to accept conditions as kwargs.
+* Changed `compas.datastructures.Halfedge.edges_where` to accept conditions as kwargs.
+* Changed `compas.datastructures.Halfedge.faces_where` to accept conditions as kwargs.
+* Changed `compas.datastructures.Halfface.vertices_where` to accept conditions as kwargs.
+* Changed `compas.datastructures.Halfface.edges_where` to accept conditions as kwargs.
+* Changed `compas.datastructures.Halfface.faces_where` to accept conditions as kwargs.
+* Changed `compas.datastructures.Halfface.cells_where` to accept conditions as kwargs.
 * Fixed `compas_blender.artists.VolMeshArtist.draw` and `compas_blender.artists.VolMeshArtist.draw_cells`.
 * Fixed `compas_ghpython.artists.VolMeshArtist.draw` and `compas_ghpython.artists.VolMeshArtist.draw_cells`.
 * Fixed `compas_rhino.artists.VolMeshArtist.draw` and `compas_rhino.artists.VolMeshArtist.draw_cells`.

src/compas/datastructures/graph/graph.py

@@ -622,12 +622,12 @@ def nodes(self, data=False):
             else:
                 yield key, self.node_attributes(key)
 
-    def nodes_where(self, conditions, data=False):
+    def nodes_where(self, conditions=None, data=False, **kwargs):
         """Get nodes for which a certain condition or set of conditions is true.
 
         Parameters
         ----------
-        conditions : dict
+        conditions : dict, optional
             A set of conditions in the form of key-value pairs.
             The keys should be attribute names. The values can be attribute
             values or ranges of attribute values in the form of min/max pairs.
@@ -641,6 +641,9 @@ def nodes_where(self, conditions, data=False):
             If `data` is True, the next node and its attributes.
 
         """
+        conditions = conditions or {}
+        conditions.update(kwargs)
+
         for key, attr in self.nodes(True):
             is_match = True
 
@@ -740,17 +743,19 @@ def edges(self, data=False):
                 else:
                     yield u, v
 
-    def edges_where(self, conditions, data=False):
+    def edges_where(self, conditions=None, data=False, **kwargs):
         """Get edges for which a certain condition or set of conditions is true.
 
         Parameters
         ----------
-        conditions : dict
+        conditions : dict, optional
             A set of conditions in the form of key-value pairs.
             The keys should be attribute names. The values can be attribute
             values or ranges of attribute values in the form of min/max pairs.
         data : bool, optional
             If True, yield the edge attributes in addition to the edge identifiers.
+        **kwargs : dict[str, Any], optional
+            Additional conditions provided as named function arguments.
 
         Yields
         ------
@@ -759,6 +764,9 @@ def edges_where(self, conditions, data=False):
             If `data` is True, the next edge identifier and its attributes as a ((u, v), attr) tuple.
 
         """
+        conditions = conditions or {}
+        conditions.update(kwargs)
+
         for key in self.edges():
             is_match = True
 

src/compas/datastructures/halfedge/halfedge.py

@@ -620,17 +620,19 @@ def edges(self, data=False):
                 else:
                     yield key, self.edge_attributes(key)
 
-    def vertices_where(self, conditions, data=False):
+    def vertices_where(self, conditions=None, data=False, **kwargs):
         """Get vertices for which a certain condition or set of conditions is true.
 
         Parameters
         ----------
-        conditions : dict
+        conditions : dict, optional
             A set of conditions in the form of key-value pairs.
             The keys should be attribute names. The values can be attribute
             values or ranges of attribute values in the form of min/max pairs.
         data : bool, optional
             If True, yield the vertex attributes in addition to the vertex identifiers.
+        **kwargs : dict[str, Any], optional
+            Additional conditions provided as named function arguments.
 
         Yields
         ------
@@ -639,6 +641,9 @@ def vertices_where(self, conditions, data=False):
             If `data` is True, the next vertex and its attributes.
 
         """
+        conditions = conditions or {}
+        conditions.update(kwargs)
+
         for key, attr in self.vertices(True):
             is_match = True
 
@@ -721,17 +726,19 @@ def vertices_where_predicate(self, predicate, data=False):
                 else:
                     yield key
 
-    def edges_where(self, conditions, data=False):
+    def edges_where(self, conditions=None, data=False, **kwargs):
         """Get edges for which a certain condition or set of conditions is true.
 
         Parameters
         ----------
-        conditions : dict
+        conditions : dict, optional
             A set of conditions in the form of key-value pairs.
             The keys should be attribute names. The values can be attribute
             values or ranges of attribute values in the form of min/max pairs.
         data : bool, optional
             If True, yield the edge attributes in addition to the edge identifiers.
+        **kwargs : dict[str, Any], optional
+            Additional conditions provided as named function arguments.
 
         Yields
         ------
@@ -740,6 +747,9 @@ def edges_where(self, conditions, data=False):
             If `data` is True, the next edge as a (u, v, data) tuple.
 
         """
+        conditions = conditions or {}
+        conditions.update(kwargs)
+
         for key in self.edges():
             is_match = True
 
@@ -803,17 +813,19 @@ def edges_where_predicate(self, predicate, data=False):
                 else:
                     yield key
 
-    def faces_where(self, conditions, data=False):
+    def faces_where(self, conditions=None, data=False, **kwargs):
         """Get faces for which a certain condition or set of conditions is true.
 
         Parameters
         ----------
-        conditions : dict
+        conditions : dict, optional
             A set of conditions in the form of key-value pairs.
             The keys should be attribute names. The values can be attribute
             values or ranges of attribute values in the form of min/max pairs.
         data : bool, optional
             If True, yield the face attributes in addition to face identifiers.
+        **kwargs : dict[str, Any], optional
+            Additional conditions provided as named function arguments.
 
         Yields
         ------
@@ -822,6 +834,9 @@ def faces_where(self, conditions, data=False):
             If `data` is True, the next face and its attributes.
 
         """
+        conditions = conditions or {}
+        conditions.update(kwargs)
+
         for fkey in self.faces():
             is_match = True
 

src/compas/datastructures/halfface/halfface.py

@@ -715,18 +715,19 @@ def cells(self, data=False):
             else:
                 yield cell, self.cell_attributes(cell)
 
-    def vertices_where(self, conditions, data=False):
+    def vertices_where(self, conditions=None, data=False, **kwargs):
         """Get vertices for which a certain condition or set of conditions is true.
 
         Parameters
         ----------
-        conditions : dict
+        conditions : dict, optional
             A set of conditions in the form of key-value pairs.
             The keys should be attribute names. The values can be attribute
             values or ranges of attribute values in the form of min/max pairs.
         data : bool, optional
-            Yield the vertices and their data attributes.
-            Default is ``False``.
+            If True, yield the vertex attributes in addition to the identifiers.
+        **kwargs : dict[str, Any], optional
+            Additional conditions provided as named function arguments.
 
         Yields
         ------
@@ -735,6 +736,9 @@ def vertices_where(self, conditions, data=False):
             If `data` is True, the next vertex and its attributes.
 
         """
+        conditions = conditions or {}
+        conditions.update(kwargs)
+
         for key, attr in self.vertices(True):
             is_match = True
 
@@ -793,11 +797,10 @@ def vertices_where_predicate(self, predicate, data=False):
         Parameters
         ----------
         predicate : callable
-            The condition you want to evaluate. The callable takes 2 parameters:
-            ``key``, ``attr`` and should return ``True`` or ``False``.
+            The condition you want to evaluate.
+            The callable takes 2 parameters: the vertex identifier and the vertex attributes, and should return True or False.
         data : bool, optional
-            Yield the vertices and their data attributes.
-            Default is ``False``.
+            If True, yield the vertex attributes in addition to the identifiers.
 
         Yields
         ------
@@ -813,18 +816,19 @@ def vertices_where_predicate(self, predicate, data=False):
                 else:
                     yield key
 
-    def edges_where(self, conditions, data=False):
+    def edges_where(self, conditions=None, data=False, **kwargs):
         """Get edges for which a certain condition or set of conditions is true.
 
         Parameters
         ----------
-        conditions : dict
+        conditions : dict, optional
             A set of conditions in the form of key-value pairs.
             The keys should be attribute names. The values can be attribute
             values or ranges of attribute values in the form of min/max pairs.
         data : bool, optional
-            Yield the edges and their data attributes.
-            Default is ``False``.
+            If True, yield the edge attributes in addition to the identifiers.
+        **kwargs : dict[str, Any], optional
+            Additional conditions provided as named function arguments.
 
         Yields
         ------
@@ -833,6 +837,9 @@ def edges_where(self, conditions, data=False):
             If `data` is True, the next edge as a (u, v, data) tuple.
 
         """
+        conditions = conditions or {}
+        conditions.update(kwargs)
+
         for key in self.edges():
             is_match = True
 
@@ -875,11 +882,10 @@ def edges_where_predicate(self, predicate, data=False):
         Parameters
         ----------
         predicate : callable
-            The condition you want to evaluate. The callable takes 3 parameters:
-            ``u``, ``v``, ``attr`` and should return ``True`` or ``False``.
+            The condition you want to evaluate.
+            The callable takes 2 parameters: the edge identifier and the edge attributes, and should return True or False.
         data : bool, optional
-            Yield the vertices and their data attributes.
-            Default is ``False``.
+            If True, yield the edge attributes in addition to the identifiers.
 
         Yields
         ------
@@ -895,18 +901,19 @@ def edges_where_predicate(self, predicate, data=False):
                 else:
                     yield key
 
-    def faces_where(self, conditions, data=False):
+    def faces_where(self, conditions=None, data=False, **kwargs):
         """Get faces for which a certain condition or set of conditions is true.
 
         Parameters
         ----------
-        conditions : dict
+        conditions : dict, optional
             A set of conditions in the form of key-value pairs.
             The keys should be attribute names. The values can be attribute
             values or ranges of attribute values in the form of min/max pairs.
         data : bool, optional
-            Yield the faces and their data attributes.
-            Default is ``False``.
+            If True, yield the face attributes in addition to the identifiers.
+        **kwargs : dict[str, Any], optional
+            Additional conditions provided as named function arguments.
 
         Yields
         ------
@@ -915,6 +922,9 @@ def faces_where(self, conditions, data=False):
             If `data` is True, the next face and its attributes.
 
         """
+        conditions = conditions or {}
+        conditions.update(kwargs)
+
         for fkey in self.faces():
             is_match = True
 
@@ -957,11 +967,10 @@ def faces_where_predicate(self, predicate, data=False):
         Parameters
         ----------
         predicate : callable
-            The condition you want to evaluate. The callable takes 2 parameters:
-            ``key``, ``attr`` and should return ``True`` or ``False``.
+            The condition you want to evaluate.
+            The callable takes 2 parameters: the face identifier and the the face attributes, and should return True or False.
         data : bool, optional
-            Yield the faces and their data attributes.
-            Default is ``False``.
+            If True, yield the face attributes in addition to the identifiers.
 
         Yields
         ------
@@ -977,18 +986,19 @@ def faces_where_predicate(self, predicate, data=False):
                 else:
                     yield fkey
 
-    def cells_where(self, conditions, data=False):
+    def cells_where(self, conditions=None, data=False, **kwargs):
         """Get cells for which a certain condition or set of conditions is true.
 
         Parameters
         ----------
-        conditions : dict
+        conditions : dict, optional
             A set of conditions in the form of key-value pairs.
             The keys should be attribute names. The values can be attribute
             values or ranges of attribute values in the form of min/max pairs.
         data : bool, optional
-            Yield the cells and their data attributes.
-            Default is ``False``.
+            If True, yield the cell attributes in addition to the identifiers.
+        **kwargs : dict[str, Any], optional
+            Additional conditions provided as named function arguments.
 
         Yields
         ------
@@ -997,6 +1007,9 @@ def cells_where(self, conditions, data=False):
             If `data` is True, the next cell and its attributes.
 
         """
+        conditions = conditions or {}
+        conditions.update(kwargs)
+
         for ckey in self.cells():
             is_match = True
 
@@ -1039,11 +1052,10 @@ def cells_where_predicate(self, predicate, data=False):
         Parameters
         ----------
         predicate : callable
-            The condition you want to evaluate. The callable takes 2 parameters:
-            ``key``, ``attr`` and should return ``True`` or ``False``.
+            The condition you want to evaluate.
+            The callable takes 2 parameters: the cell identifier and the cell attributes, and should return True or False.
         data : bool, optional
-            Yield the cells and their data attributes.
-            Default is ``False``.
+            If True, yield the cell attributes in addition to the identifiers.
 
         Yields
         ------