python - Python API 设计中的重载(或替代方案)

Question

我有一个大型现有程序库，目前有一个 .NET 绑定(bind)，我正在考虑编写一个 Python 绑定(bind)。现有的 API 广泛使用基于签名的重载。所以，我收集了大量的静态函数，例如:

Circle(p1, p2, p3) -- Creates a circle through three points
Circle(p, r)       -- Creates a circle with given center point and radius
Circle(c1, c2, c3) -- Creates a circle tangent to three curves

在某些情况下，必须以不同的方式使用相同的输入，因此基于签名的重载不起作用，我必须改用不同的函数名称。例如

BezierCurve(p1,p2,p3,p4) -- Bezier curve using given points as control points
BezierCurveThroughPoints(p1,p2,p3,p4) -- Bezier curve passing through given points

我想这第二种技术(使用不同的函数名称)可以在 Python API 的任何地方使用。所以，我会

CircleThroughThreePoints(p1, p2, p3)
CircleCenterRadius(p, r)
CircleTangentThreeCurves(c1, c2, c3)

但是这些名称看起来冗长得令人不快(我不喜欢缩写)，发明所有这些名称将是一个相当大的挑战，因为这个库有成千上万的函数。

低优先级:
努力(就我而言)——我不在乎是否必须编写大量代码。
性能

高优先级:
调用者易于使用/理解(许多人将是编程新手)。
我很容易写出好的文档。
简单——避免在调用者代码中使用高级概念。

我敢肯定我不是第一个希望在 Python 中进行基于签名的重载的人。人们通常使用哪些变通办法？

Answer 1

一种选择是在构造函数中独占关键字参数，并包含确定应该使用什么的逻辑:

class Circle(object):
    def __init__(self, points=(), radius=None, curves=()):
        if radius and len(points) == 1:
            center_point = points[0]
            # Create from radius/center point
        elif curves and len(curves) == 3:
            # create from curves
        elif points and len(points) == 3:
            # create from points
        else:
            raise ValueError("Must provide a tuple of three points, a point and a radius, or a tuple of three curves)

您还可以使用类方法来简化 API 用户的操作:

class Circle(object):
    def __init__(self, points=(), radius=None, curves=()):
         # same as above

    @classmethod
    def from_points(p1, p2, p3):
        return cls(points=(p1, p2, p3))

    @classmethod
    def from_point_and_radius(cls, point, radius):
        return cls(points=(point,), radius=radius)

    @classmethod
    def from_curves(cls, c1, c2, c3):
        return cls(curves=(c1, c2, c3))

用法:

c = Circle.from_points(p1, p2, p3)
c = Circle.from_point_and_radius(p1, r)
c = Circle.from_curves(c1, c2, c3)