InterfaceMeta

interface_meta 提供了一种便捷的方式，以强制方法签名和一致文档的方式暴露可扩展的API。

• 文档: 见下文（完整文档将稍后提供）。
• 源代码: https://github.com/matthewwardrop/interface_meta
• 错误报告: https://github.com/matthewwardrop/interface_meta/issues

概述

此库是从omniduct库提取出来的（经过一些修改），该库也主要由作者编写，其中它是可扩展插件架构的核心。它侧重于创建良好文档的可扩展插件系统所需的功能，其中子类化操作足以注册插件并确保符合父API。因此，此库具有以下特性

• 接口的所有子类都必须符合父API。
• 分层运行时属性存在和方法签名检查。方法可以添加额外的可选参数，但其他方面必须符合父类API（父类本身也可能扩展了接口的API）。
• 子类定义时间钩子（例如，将子类注册到插件库中等）。
• 子类中方法可选要求：在替换接口中的方法时，显式地使用override装饰器装饰方法，以更清晰地说明类是在引入新方法还是在替换接口API的一部分。
• 生成清晰的文档字符串，将基本接口文档与任何下游扩展和特性结合起来。
• 支持从其他方法文档字符串中提取方法特性的文档，在子类实现是在内部方法完成的情况下。
• 与标准库中的ABCMeta兼容。

示例代码

from abc import abstractmethod, abstractproperty
from interface_meta import InterfaceMeta, override, quirk_docs

class MyInterface(metaclass=InterfaceMeta):
    """
    An example interface.
    """

    INTERFACE_EXPLICIT_OVERRIDES = True
    INTERFACE_RAISE_ON_VIOLATION = False
    INTERFACE_SKIPPED_NAMES = {'__init__'}

    def __init__(self):
        """
        MyInterface constructor.
        """
        pass

    @abstractproperty
    def name(self):
        """
        The name of this interface.
        """
        pass

    @quirk_docs(method='_do_stuff')
    def do_stuff(self, a, b, c=1):
        """
        Do things with the parameters.
        """
        return self._do_stuff(a, b, c)

    @abstractmethod
    def _do_stuff(self, a, b, c):
        pass

class MyImplementation(MyInterface):
    """
    This implementation of the example interface works nicely.
    """

    @quirk_docs(method='_init', mro=False)
    def __init__(self, a):
        """
        MyImplementation constructor.
        """
        self._init(a)

    def _init(self, a):
        """
        In this instance, we do nothing with a.
        """
        pass

    @property
    @override
    def name(self):
        return "Peter"

    @override
    def _do_stuff(self, a, b, c):
        """
        In this implementation, we sum the parameters.
        """
        return a + b + c

运行help(MyImplementation)可揭示文档的生成方式

class MyImplementation(MyInterface)
 |  This implementation of the example interface works nicely.
 |
 |  Method resolution order:
 |      MyImplementation
 |      MyInterface
 |      builtins.object
 |
 |  Methods defined here:
 |
 |  __init__(self, a)
 |      MyImplementation constructor.
 |
 |      In this instance, we do nothing with a.
 |
 |  do_stuff(self, a, b, c=1)
 |      Do things with the parameters.
 |
 |      MyImplementation Quirks:
 |          In this implementation, we sum the parameters.
 ...

相关项目和已有技术

该库发布在一个竞争激烈的空间中，作者希望认可其他人已经做的一些优秀工作。与其他库的主要区别通常在于，这些其他库更侧重于抽象接口定义和合规性，而较少关注文档和插件注册工作。尽管这项工作与这些项目重叠，但作者认为其方法足够不同，值得成为一个独立的库。

• pure_interface
• python-interface

python-interface强调确保各种接口的实现严格遵循接口关联的方法和属性，并在违反时引发有用的错误。

相比之下，这个库侧重于功能上符合父类，允许子类的方法包括额外的参数。它还侧重于确保将这些方法签名中特性的文档正确地组合到该方法的最终文档中。