Merge branch 'master' into cut_kw_arg

Author: adam-urbanczyk

cadquery/occ_impl/geom.py

@@ -582,6 +582,9 @@ def __eq__(self, other):
     def __ne__(self, other):
         return not self.__eq__(other)
 
+    def __repr__(self):
+        return f"Plane(origin={str(self.origin.toTuple())}, xDir={str(self.xDir.toTuple())}, normal={str(self.zDir.toTuple())})"
+
     @property
     def origin(self) -> Vector:
         return self._origin

cadquery/occ_impl/shapes.py

@@ -17,13 +17,13 @@
 
 from io import BytesIO
 
-from multimethod import multimethod
-
 from vtkmodules.vtkCommonDataModel import vtkPolyData
 from vtkmodules.vtkFiltersCore import vtkTriangleFilter, vtkPolyDataNormals
 
 from .geom import Vector, BoundBox, Plane, Location, Matrix
 
+from ..utils import cqmultimethod as multimethod
+
 import OCP.TopAbs as ta  # Tolopolgy type enum
 import OCP.GeomAbs as ga  # Geometry type enum
 

conda/meta.yaml

@@ -15,7 +15,7 @@ requirements:
     - setuptools
   run:
     - python {{ environ.get('PYTHON_VERSION') }}
-    - ocp 7.5.2
+    - ocp 7.5.3
     - hdf5 1.10.6 *1114
     - pyparsing >=2.1.9
     - ezdxf

doc/primer.rst

@@ -352,6 +352,19 @@ If you want to cast an OCCT object into a Direct API one you can just pass it as
 .. note::
   You can cast into the direct API the types found `here <https://dev.opencascade.org/doc/refman/html/class_topo_d_s___shape.html>`_
 
+Multimethods
+------------
+
+CadQuery uses `Multimethod <https://coady.github.io/multimethod/>`_ to allow a call to a method to
+be dispatched depending on the types of the arguments. An example is :meth:`~cadquery.Sketch.arc`,
+where ``a_sketch.arc((1, 2), (2, 3))`` would be dispatched to one method but ``a_sketch.arc((1, 2),
+(2, 3), (3, 4))`` would be dispatched to a different method. For multimethods to work, you should
+not use keyword arguments to specify positional parameters. For example, you **should not** write
+``a_sketch.arc(p1=(1, 2), p2=(2, 3), p3=(3, 4))``, instead you should use the previous example.
+Note CadQuery makes an attempt to fall back on the first registered multimethod in the event of a
+dispatch error, but it is still best practise to not use keyword arguments to specify positional
+arguments in CadQuery.
+
 An Introspective Example
 ------------------------
 

tests/test_cadquery.py

@@ -5279,3 +5279,10 @@ def test_MergeTags(self):
         a = a.union(b)
         a = a.workplaneFromTagged("zface").circle(0.2)
         assert a.edges("%CIRCLE").val().Center().toTuple() == approx((0, 0, 0.5))
+
+    def test_plane_repr(self):
+        wp = Workplane("XY")
+        assert (
+            repr(wp.plane)
+            == "Plane(origin=(0.0, 0.0, 0.0), xDir=(1.0, 0.0, 0.0), normal=(0.0, 0.0, 1.0))"
+        )

tests/test_utils.py

@@ -0,0 +1,27 @@
+from cadquery.utils import cqmultimethod as multimethod
+
+from pytest import raises
+
+
+def test_multimethod():
+    class A:
+        @multimethod
+        def f(self, a: int, c: str = "s"):
+            return 1
+
+        @f.register
+        def f(self, a: int, b: int, c: str = "b"):
+            return 2
+
+    assert A().f(0, "s") == 1
+    assert A().f(0, c="s") == 1
+    assert A().f(0) == 1
+
+    assert A().f(0, 1, c="s") == 2
+    assert A().f(0, 1, "s") == 2
+    assert A().f(0, 1) == 2
+
+    assert A().f(a=0, c="s") == 1
+
+    with raises(TypeError):
+        A().f(a=0, b=1, c="s")