updated text and added deprecation warning

Author: Jojain

cadquery/cq.py

@@ -51,7 +51,7 @@
 
 from .occ_impl.exporters.svg import getSVG, exportSVG
 
-from .utils import deprecate_kwarg, deprecate
+from .utils import deprecate_kwarg, deprecate, deprecate_kwarg_name
 
 from .selectors import (
     Selector,
@@ -2394,6 +2394,8 @@ def each(
         self: T,
         callback: Callable[[CQObject], Shape],
         useLocalCoordinates: bool = False,
+        combine: Union[bool, str] = True,
+        clean: bool = True,
     ) -> T:
         """
         Runs the provided function on each value in the stack, and collects the return values into
@@ -2404,6 +2406,9 @@ def each(
         :param callBackFunction: the function to call for each item on the current stack.
         :param useLocalCoordinates: should  values be converted from local coordinates first?
         :type useLocalCoordinates: boolean
+        :param boolean or string combine: True to combine the resulting solid with parent solids if found, "cut" to remove the resulting solid from the parent solids if found.
+        :param boolean clean: call :py:meth:`clean` afterwards to have a clean shape
+
 
         The callback function must accept one argument, which is the item on the stack, and return
         one object, which is collected. If the function returns None, nothing is added to the stack.
@@ -2439,7 +2444,6 @@ def each(
             if isinstance(r, Wire):
                 if not r.forConstruction:
                     self._addPendingWire(r)
-
             results.append(r)
 
         return self.newObject(results)
@@ -2448,6 +2452,7 @@ def eachpoint(
         self: T,
         callback: Callable[[Location], Shape],
         useLocalCoordinates: bool = False,
+        combine: Union[bool, str] = False,
     ) -> T:
         """
         Same as each(), except each item on the stack is converted into a point before it
@@ -2457,6 +2462,8 @@ def eachpoint(
 
         :param useLocalCoordinates: should points be in local or global coordinates
         :type useLocalCoordinates: boolean
+        :param boolean or string combine: True to combine the resulting solid with parent solids if found, "cut" to remove the resulting solid from the parent solids if found.
+
 
         The resulting object has a point on the stack for each object on the original stack.
         Vertices and points remain a point.  Faces, Wires, Solids, Edges, and Shells are converted
@@ -2492,6 +2499,10 @@ def eachpoint(
             if isinstance(r, Wire) and not r.forConstruction:
                 self._addPendingWire(r)
 
+        if combine:
+            compound = Compound.makeCompound(res)
+            res = [self._combineWithBase(compound, combine).val()]
+
         return self.newObject(res)
 
     def rect(
@@ -3001,7 +3012,7 @@ def twistExtrude(
     def extrude(
         self: T,
         until: Union[float, Literal["next", "last"], Face],
-        combine: bool = True,
+        combine: Union[bool,str] = True,
         clean: bool = True,
         both: bool = False,
         taper: Optional[float] = None,
@@ -3015,7 +3026,7 @@ def extrude(
           to the normal of the plane. The string "next" extrudes until the next face orthogonal to
           the wire normal. "last" extrudes to the last face. If a object of type Face is passed then
           the extrusion will extend until this face.
-        :param boolean combine: True to combine the resulting solid with parent solids if found. (Cannot be set to False when `until` is not set as a float)
+        :param boolean or string combine: True to combine the resulting solid with parent solids if found, "cut" to remove the resulting solid from the parent solids if found.
         :param boolean clean: call :py:meth:`clean` afterwards to have a clean shape
         :param boolean both: extrude in both directions symmetrically
         :param float taper: angle for optional tapered extrusion
@@ -3038,7 +3049,7 @@ def extrude(
             elif until == "last":
                 faceIndex = -1
 
-            r = self._extrude(distance=None, both=both, taper=taper, upToFace=faceIndex)
+            r = self._extrude(None, both=both, taper=taper, upToFace=faceIndex)
 
         elif isinstance(until, Face) and combine:
             r = self._extrude(None, both=both, taper=taper, upToFace=until)
@@ -3192,12 +3203,11 @@ def _combineWithBase(
         :return: a new object that represents the result of combining the base object with obj,
            or obj if one could not be found
         """
-
         if isinstance(combine_mode, str) and combine_mode == "cut":
             newS = self._cutFromBase(obj)
         elif isinstance(combine_mode, bool) and combine_mode:
             newS = self._fuseWithBase(obj)
-        elif not combine_mode:
+        else:
             newS = self.newObject([obj])
 
         return newS
@@ -3226,9 +3236,8 @@ def _cutFromBase(self: T, obj: Shape) -> T:
         :return: a new object that represents the result of combining the base object with obj,
            or obj if one could not be found
         """
-        baseSolid = self._findType(
-            (Solid, Compound), searchStack=True, searchParents=True
-        )
+        baseSolid = self._findType((Solid, Compound), True, True)
+
         r = obj
         if baseSolid is not None:
             r = baseSolid.cut(obj)
@@ -4119,14 +4128,15 @@ def clean(self: T) -> T:
 
         return self.newObject(cleanObjects)
 
+    @deprecate_kwarg_name("cut", "combine='cut'")
     def text(
         self: T,
         txt: str,
         fontsize: float,
         distance: float,
         cut: bool = True,
         combine: bool = False,
-        clean: bool = True,
+        clean: Union[bool, str] = True,
         font: str = "Arial",
         fontPath: Optional[str] = None,
         kind: Literal["regular", "bold", "italic"] = "regular",
@@ -4141,7 +4151,7 @@ def text(
         :param distance: the distance to extrude or cut, normal to the workplane plane
         :type distance: float, negative means opposite the normal direction
         :param cut: True to cut the resulting solid from the parent solids if found
-        :param combine: True to combine the resulting solid with parent solids if found
+        :param boolean or string combine: True to combine the resulting solid with parent solids if found, "cut" to remove the resulting solid from the parent solids if found.
         :param clean: call :py:meth:`clean` afterwards to have a clean shape
         :param font: font name
         :param fontPath: path to font file
@@ -4186,15 +4196,10 @@ def text(
             position=self.plane,
         )
 
-        combine_mode:Union[bool, str]
         if cut:
-            combine_mode = "cut"
-        elif combine:
-            combine_mode = True
-        else:
-            combine_mode = False
+            combine = "cut"
 
-        newS = self._combineWithBase(r, combine_mode)
+        newS = self._combineWithBase(r, combine)
 
         if clean:
             newS = newS.clean()

cadquery/utils.py

@@ -36,3 +36,25 @@ def wrapped(*args, **kwargs):
             return f(*args, **kwargs)
 
         return wrapped
+
+class deprecate_kwarg_name:
+    def __init__(self, name, new_name):
+
+        self.name = name
+        self.new_name = new_name
+
+    def __call__(self, f):
+        @wraps(f)
+        def wrapped(*args, **kwargs):
+
+            f_sig_params = signature(f).parameters
+
+            if f_sig_params[self.name]:
+                warn(
+                    f"Kwarg <{self.name}> will be removed. Plase use <{self.new_name}>",
+                    FutureWarning,
+                )
+
+            return f(*args, **kwargs)
+
+        return wrapped

tests/test_cadquery.py

@@ -3524,6 +3524,11 @@ def testExtrude(self):
         with self.assertRaises(ValueError):
             Workplane().rect(2, 2).rect(1, 1).extrude(2, taper=4)
 
+        # Test extrude with combine="cut"
+        box = Workplane().box(5,5,5)
+        r = box.faces(">Z").workplane(invert=True).circle(0.5).extrude(4, combine="cut")
+        self.assertGreater(box.val().Volume(), r.val().Volume())
+
     def testTaperedExtrudeCutBlind(self):
 
         h = 1.0
@@ -5093,6 +5098,16 @@ def testEachpoint(self):
         for v in r1.vals():
             self.assertTupleAlmostEquals(v.Center().toTuple(), (0, 0, 0), 6)
 
+        # test eachpoint with combine = True
+        box = Workplane().box(2, 1, 1).val()
+        ref = Workplane().box(5, 5, 5)
+        r = ref.vertices().eachpoint(lambda loc: box.moved(loc), combine=True)
+        self.assertGreater(r.val().Volume(), ref.val().Volume())
+
+        # test eachpoint with combine = "cut"
+        r = ref.vertices().eachpoint(lambda loc: box.moved(loc), combine="cut")
+        self.assertGreater(ref.val().Volume(), r.val().Volume())
+
     def testSketch(self):
 
         r1 = (