ENH: Add subinterfaces.

Add support for creating sub-interfaces by subclassing from an interface.

A sub interface inherits all the interface members of its parents, and may add
new interface items. It can also override parent members with new signatures,
provided that any implementation of the child interface is also a valid
implementation of the parent interface.

Author: Scott Sanderson

interface/functional.py

@@ -46,3 +46,16 @@ def sliding_window(iterable, n):
     for item in it:
         items.append(item)
         yield tuple(items)
+
+
+def merge(dicts):
+    dicts = list(dicts)
+    if len(dicts) == 0:
+        return {}
+    elif len(dicts) == 1:
+        return dicts[0]
+    else:
+        out = dicts[0].copy()
+        for other in dicts[1:]:
+            out.update(other)
+        return out

interface/interface.py

@@ -6,7 +6,7 @@
 from .compat import raise_from, with_metaclass
 from .default import default, warn_if_defaults_use_non_interface_members
 from .formatting import bulleted_list
-from .functional import complement, keyfilter, valfilter
+from .functional import complement, keyfilter, merge, valfilter
 from .typecheck import compatible
 from .typed_signature import TypedSignature
 from .utils import is_a, unique
@@ -21,8 +21,22 @@ class InvalidImplementation(TypeError):
     """
 
 
+class InvalidSubInterface(TypeError):
+    """
+    Raised when on attempt to define a subclass of an interface that's not
+    compatible with the parent definition.
+    """
+
+
 CLASS_ATTRIBUTE_WHITELIST = frozenset(
-    ["__doc__", "__module__", "__name__", "__qualname__", "__weakref__"]
+    [
+        "__doc__",
+        "__module__",
+        "__name__",
+        "__qualname__",
+        "__weakref__",
+        "_INTERFACE_IGNORE_MEMBERS",
+    ]
 )
 
 is_interface_field_name = complement(CLASS_ATTRIBUTE_WHITELIST.__contains__)
@@ -72,6 +86,14 @@ def _conflicting_defaults(typename, conflicts):
     return InvalidImplementation(message)
 
 
+def _merge_parent_signatures(bases):
+    return merge(filter(None, (getattr(b, "_signatures") for b in bases)))
+
+
+def _merge_parent_defaults(bases):
+    return merge(filter(None, (getattr(b, "_defaults") for b in bases)))
+
+
 class InterfaceMeta(type):
     """
     Metaclass for interfaces.
@@ -80,22 +102,43 @@ class InterfaceMeta(type):
     """
 
     def __new__(mcls, name, bases, clsdict):
-        signatures = {}
-        defaults = {}
-        for k, v in keyfilter(is_interface_field_name, clsdict).items():
+        signatures = _merge_parent_signatures(bases)
+        defaults = _merge_parent_defaults(bases)
+        ignored = clsdict.get("_INTERFACE_IGNORE_MEMBERS", set())
+
+        for field, v in keyfilter(is_interface_field_name, clsdict).items():
+            if field in ignored:
+                continue
+
             try:
-                signatures[k] = TypedSignature(v)
+                signature = TypedSignature(v)
             except TypeError as e:
                 errmsg = (
                     "Couldn't parse signature for field "
                     "{iface_name}.{fieldname} of type {attrtype}.".format(
-                        iface_name=name, fieldname=k, attrtype=getname(type(v)),
+                        iface_name=name, fieldname=field, attrtype=getname(type(v)),
                     )
                 )
                 raise_from(TypeError(errmsg), e)
 
+            # If we already have a signature for this field from a parent, then
+            # our new signature must be a subtype of the parent signature, so
+            # that any valid call to the new signature must also be a valid
+            # call to the parent signature.
+            if field in signatures and not compatible(signature, signatures[field]):
+                conflicted = signatures[field]
+                raise InvalidSubInterface(
+                    "\nInterface field {new}.{field} conflicts with inherited field of "
+                    "the same name.\n"
+                    "  - {field}{new_sig} != {field}{old_sig}".format(
+                        new=name, field=field, new_sig=signature, old_sig=conflicted,
+                    )
+                )
+            else:
+                signatures[field] = signature
+
             if isinstance(v, default):
-                defaults[k] = v
+                defaults[field] = v
 
         warn_if_defaults_use_non_interface_members(
             name, defaults, set(signatures.keys())
@@ -139,7 +182,7 @@ def _diff_signatures(self, type_):
             if not issubclass(impl_sig.type, iface_sig.type):
                 mistyped[name] = impl_sig.type
 
-            if not compatible(impl_sig.signature, iface_sig.signature):
+            if not compatible(impl_sig, iface_sig):
                 mismatched[name] = impl_sig
 
         return missing, mistyped, mismatched
@@ -258,6 +301,9 @@ def _format_mismatched_methods(self, mismatched):
         )
 
 
+empty_set = frozenset([])
+
+
 class Interface(with_metaclass(InterfaceMeta)):
     """
     Base class for interface definitions.
@@ -313,6 +359,10 @@ def delete(self, key):
     :func:`implements`
     """
 
+    # Don't consider these members part of the interface definition for
+    # children of `Interface`.
+    _INTERFACE_IGNORE_MEMBERS = {"__new__", "from_class"}
+
     def __new__(cls, *args, **kwargs):
         raise TypeError("Can't instantiate interface %s" % getname(cls))
 
@@ -349,7 +399,10 @@ def from_class(cls, existing_class, subset=None, name=None):
         )
 
 
-empty_set = frozenset([])
+# Signature requirements are inherited, so make sure the base interface doesn't
+# require any methods of children.
+assert Interface._signatures == {}
+assert Interface._defaults == {}
 
 
 class ImplementsMeta(type):

interface/tests/_py3_typecheck_tests.py

@@ -1,14 +1,13 @@
-from inspect import signature
-
 from ..typecheck import compatible
+from ..typed_signature import TypedSignature
 
 
 def test_allow_new_params_with_defaults_with_kwonly():
-    @signature
+    @TypedSignature
     def iface(a, b, c):  # pragma: nocover
         pass
 
-    @signature
+    @TypedSignature
     def impl(a, b, c, d=3, e=5, *, f=5):  # pragma: nocover
         pass
 
@@ -17,11 +16,11 @@ def impl(a, b, c, d=3, e=5, *, f=5):  # pragma: nocover
 
 
 def test_allow_reorder_kwonlys():
-    @signature
+    @TypedSignature
     def foo(a, b, c, *, d, e, f):  # pragma: nocover
         pass
 
-    @signature
+    @TypedSignature
     def bar(a, b, c, *, f, d, e):  # pragma: nocover
         pass
 
@@ -30,11 +29,11 @@ def bar(a, b, c, *, f, d, e):  # pragma: nocover
 
 
 def test_allow_default_changes():
-    @signature
+    @TypedSignature
     def foo(a, b, c=3, *, d=1, e, f):  # pragma: nocover
         pass
 
-    @signature
+    @TypedSignature
     def bar(a, b, c=5, *, f, e, d=12):  # pragma: nocover
         pass
 
@@ -43,11 +42,11 @@ def bar(a, b, c=5, *, f, e, d=12):  # pragma: nocover
 
 
 def test_disallow_kwonly_to_positional():
-    @signature
+    @TypedSignature
     def foo(a, *, b):  # pragma: nocover
         pass
 
-    @signature
+    @TypedSignature
     def bar(a, b):  # pragma: nocover
         pass
 

interface/tests/test_interface.py

@@ -890,3 +890,110 @@ class BadImpl failed to implement interface HasMagicMethodsInterface:
           - __getitem__(self, key)"""
     )
     assert actual_message == expected_message
+
+
+def test_interface_subclass():
+    class A(Interface):  # pragma: nocover
+        def method_a(self):
+            pass
+
+    class AandB(A):  # pragma: nocover
+        def method_b(self):
+            pass
+
+    with pytest.raises(InvalidImplementation) as exc:
+
+        class JustA(implements(AandB)):  # pragma: nocover
+            def method_a(self):
+                pass
+
+    actual_message = str(exc.value)
+    expected_message = dedent(
+        """
+        class JustA failed to implement interface AandB:
+
+        The following methods of AandB were not implemented:
+          - method_b(self)"""
+    )
+    assert actual_message == expected_message
+
+    with pytest.raises(InvalidImplementation) as exc:
+
+        class JustB(implements(AandB)):  # pragma: nocover
+            def method_b(self):
+                pass
+
+    actual_message = str(exc.value)
+    expected_message = dedent(
+        """
+        class JustB failed to implement interface AandB:
+
+        The following methods of AandB were not implemented:
+          - method_a(self)"""
+    )
+    assert actual_message == expected_message
+
+    class Both(implements(AandB)):  # pragma: nocover
+        def method_a(self):
+            pass
+
+        def method_b(self):
+            pass
+
+
+def test_subclass_conflict_with_different_parents():
+    class A(Interface):  # pragma: nocover
+        def method_a(self):
+            pass
+
+    class B(A):  # pragma: nocover
+        def method_b(self):
+            pass
+
+    with pytest.raises(TypeError) as exc:
+
+        class C1(A):  # pragma: nocover
+            def method_a(self, x):
+                pass
+
+    actual_message = str(exc.value)
+    expected_message = dedent(
+        """
+        Interface field C1.method_a conflicts with inherited field of the same name.
+          - method_a(self, x) != method_a(self)"""
+    )
+    assert actual_message == expected_message
+
+    with pytest.raises(TypeError) as exc:
+
+        class C2(A):  # pragma: nocover
+            def method_b(self, y, z=None):
+                pass
+
+    actual_message = str(exc.value)
+    expected_message = dedent(
+        """
+        Interface field C2.method_b conflicts with inherited field of the same name.
+          - method_b(self, y, z=None) != method_b(self)"""
+    )
+    assert actual_message == expected_message
+
+
+def test_subclass_allow_compatible_extension():
+    class A(Interface):  # pragma: nocover
+        def method_a(self, x):
+            pass
+
+    class B(A):  # pragma: nocover
+        def method_b(self, y):
+            pass
+
+    # Any implementation of C1 is also a valid implementation of A and B, so this is fine.
+    class C1(B):  # pragma: nocover
+        def method_a(self, x, y=3):
+            pass
+
+    # Same here.
+    class C2(B):  # pragma: nocover
+        def method_b(self, y, z=None):
+            pass