Handle kwargs+multimethods in a backward compatibile way (#923)

* CQ-specific multimethod

* Use cqmultimethod in cq.Shape

* Imports cleanup

* cqmultimethod test

* doc/primer: added multimethod section

Co-authored-by: Marcus Boyd <[email protected]>

Author: adam-urbanczyk

cadquery/cq.py

@@ -45,18 +45,15 @@
     Face,
     Solid,
     Compound,
-    sortWiresByBuildOrder,
     wiresToFaces,
 )
 
 from .occ_impl.exporters.svg import getSVG, exportSVG
 
-from .utils import deprecate_kwarg, deprecate
+from .utils import deprecate
 
 from .selectors import (
     Selector,
-    PerpendicularDirSelector,
-    NearestToPointSelector,
     StringSyntaxSelector,
 )
 

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
 

cadquery/utils.py

@@ -2,6 +2,8 @@
 from inspect import signature
 from warnings import warn
 
+from multimethod import multimethod, DispatchError
+
 
 class deprecate_kwarg:
     def __init__(self, name, new_value):
@@ -36,3 +38,12 @@ def wrapped(*args, **kwargs):
             return f(*args, **kwargs)
 
         return wrapped
+
+
+class cqmultimethod(multimethod):
+    def __call__(self, *args, **kwargs):
+
+        try:
+            return super().__call__(*args, **kwargs)
+        except DispatchError:
+            return next(iter(self.values()))(*args, **kwargs)

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_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")