Merge pull request CadQuery#569 from RubenRubens/boolean

Boolean operation syntactic sugar

cadquery/cq.py

@@ -2975,6 +2975,25 @@ def union(
 
         return self.newObject([r])
 
+    def __or__(self, toUnion: Union["Workplane", Solid, Compound]) -> "Workplane":
+        """
+        Syntactic sugar for union.
+        Notice that `r = a | b` is equivalent to `r = a.union(b)` and `r = a + b`.
+
+        Example::
+            Box = Workplane("XY").box(1, 1, 1, centered=(False, False, False))
+            Sphere = Workplane("XY").sphere(1)
+            result = Box | Sphere
+        """
+        return self.union(toUnion)
+
+    def __add__(self, toUnion: Union["Workplane", Solid, Compound]) -> "Workplane":
+        """
+        Syntactic sugar for union.
+        Notice that `r = a + b` is equivalent to `r = a.union(b)` and `r = a | b`.
+        """
+        return self.union(toUnion)
+
     def cut(
         self, toCut: Union["Workplane", Solid, Compound], clean: bool = True
     ) -> "Workplane":
@@ -3010,6 +3029,19 @@ def cut(
 
         return self.newObject([newS])
 
+    def __sub__(self, toUnion: Union["Workplane", Solid, Compound]) -> "Workplane":
+        """
+        Syntactic sugar for cut.
+        Notice that `r = a - b` is equivalent to `r = a.cut(b)`.
+
+        Example::
+
+            Box = Workplane("XY").box(1, 1, 1, centered=(False, False, False))
+            Sphere = Workplane("XY").sphere(1)
+            result = Box - Sphere
+        """
+        return self.cut(toUnion)
+
     def intersect(
         self, toIntersect: Union["Workplane", Solid, Compound], clean: bool = True
     ) -> "Workplane":
@@ -3045,6 +3077,19 @@ def intersect(
 
         return self.newObject([newS])
 
+    def __and__(self, toUnion: Union["Workplane", Solid, Compound]) -> "Workplane":
+        """
+        Syntactic sugar for intersect.
+        Notice that `r = a & b` is equivalent to `r = a.intersect(b)`.
+
+        Example::
+
+            Box = Workplane("XY").box(1, 1, 1, centered=(False, False, False))
+            Sphere = Workplane("XY").sphere(1)
+            result = Box & Sphere
+        """
+        return self.intersect(toUnion)
+
     def cutBlind(
         self, distanceToCut: float, clean: bool = True, taper: Optional[float] = None
     ) -> "Workplane":

doc/classreference.rst

@@ -80,6 +80,7 @@ Class Details
 .. automodule:: cadquery
    :show-inheritance: 
    :members:
+   :special-members:
 
 .. autoclass:: cadquery.occ_impl.shapes.Mixin1D
    :show-inheritance: 

tests/test_cadquery.py

@@ -1368,6 +1368,10 @@ def testCut(self):
         with self.assertRaises(ValueError):
             currentS.cut(toCut.faces().val())
 
+        # Test syntactic sugar [__sub__ method]
+        sugar = currentS - toCut.val()
+        self.assertEqual(resS.faces().size(), sugar.faces().size())
+
     def testIntersect(self):
         """
         Tests the intersect function.
@@ -1395,6 +1399,10 @@ def testIntersect(self):
         with self.assertRaises(ValueError):
             b1.intersect(b2.faces().val())
 
+        # Test syntactic sugar [__mul__ method]
+        sugar = b1 & b2
+        self.assertEqual(resS.val().Volume(), sugar.val().Volume())
+
     def testBoundingBox(self):
         """
         Tests the boudingbox center of a model
@@ -2340,6 +2348,13 @@ def testUnions(self):
         with self.assertRaises(ValueError):
             resS.union(toUnion.faces().val())
 
+        # Test syntactic sugar [__add__ method]
+        sugar1 = currentS | toUnion
+        sugar2 = currentS + toUnion
+
+        self.assertEqual(resS.faces().size(), sugar1.faces().size())
+        self.assertEqual(resS.faces().size(), sugar2.faces().size())
+
     def testCombine(self):
         s = Workplane(Plane.XY())
         objects1 = s.rect(2.0, 2.0).extrude(0.5).faces(">Z").rect(1.0, 1.0).extrude(0.5)