Merge pull request #4 from ssanderson/provide-default-impls

ENH: Add support for default implementations.

Author: Scott Sanderson

interface/__init__.py

@@ -1,7 +1,9 @@
-from .interface import implements, IncompleteImplementation, Interface
+from .interface import implements, InvalidImplementation, Interface
+from .default import default
 
 __all__ = [
-    'IncompleteImplementation',
+    'default',
+    'InvalidImplementation',
     'Interface',
     'implements',
 ]

interface/default.py

@@ -0,0 +1,96 @@
+import dis
+import warnings
+
+from .compat import PY3
+from .formatting import bulleted_list
+from .functional import keysorted, sliding_window
+
+
+class default(object):
+    """Default implementation of a function in terms of interface methods.
+    """
+    def __init__(self, implementation):
+        self.implementation = implementation
+
+    def __repr__(self):
+        return "{}({})".format(type(self).__name__, self.implementation)
+
+
+class DefaultUsesNonInterfaceMembers(UserWarning):
+    pass
+
+
+if PY3:  # pragma: nocover-py2
+    _DEFAULT_USES_NON_INTERFACE_MEMBER_TEMPLATE = (
+        "Default implementation of {iface}.{method} uses non-interface attributes.\n\n"
+        "The following attributes may be accessed but are not part of "
+        "the interface:\n"
+        "{non_members}\n\n"
+        "Consider changing the implementation of {method} or making these attributes"
+        " part of {iface}."
+    )
+
+    def warn_if_defaults_use_non_interface_members(interface_name,
+                                                   defaults,
+                                                   members):
+        """Warn if an interface default uses non-interface members of self.
+        """
+        for method_name, attrs in non_member_attributes(defaults, members):
+            warnings.warn(_DEFAULT_USES_NON_INTERFACE_MEMBER_TEMPLATE.format(
+                iface=interface_name,
+                method=method_name,
+                non_members=bulleted_list(attrs),
+            ))
+
+    def non_member_attributes(defaults, members):
+        from .typed_signature import TypedSignature
+
+        for default_name, default in keysorted(defaults):
+            impl = default.implementation
+
+            if isinstance(impl, staticmethod):
+                # staticmethods can't use attributes of the interface.
+                continue
+
+            self_name = TypedSignature(impl).first_argument_name
+            if self_name is None:
+                # No parameters.
+                # TODO: This is probably a bug in the interface, since a method
+                # with no parameters that's not a staticmethod probably can't
+                # be called in any natural way.
+                continue
+
+            used = accessed_attributes_of_local(impl, self_name)
+            non_interface_usages = used - members
+
+            if non_interface_usages:
+                yield default_name, sorted(non_interface_usages)
+
+    def accessed_attributes_of_local(f, local_name):
+        """
+        Get a list of attributes of ``local_name`` accessed by ``f``.
+
+        The analysis performed by this function is conservative, meaning that
+        it's not guaranteed to find **all** attributes used.
+        """
+        used = set()
+        # Find sequences of the form: LOAD_FAST(local_name), LOAD_ATTR(<name>).
+        # This will find all usages of the form ``local_name.<name>``.
+        #
+        # It will **NOT** find usages in which ``local_name`` is aliased to
+        # another name.
+        for first, second in sliding_window(dis.get_instructions(f), 2):
+            if first.opname == 'LOAD_FAST' and first.argval == local_name:
+                if second.opname in ('LOAD_ATTR', 'STORE_ATTR'):
+                    used.add(second.argval)
+        return used
+
+else:  # pragma: nocover-py3
+    def warn_if_defaults_use_non_interface_members(*args, **kwargs):
+        pass
+
+    def non_member_warnings(*args, **kwargs):
+        return iter(())
+
+    def accessed_attributes_of_local(*args, **kwargs):
+        return set()

interface/formatting.py

@@ -0,0 +1,6 @@
+"""String formatting utilities.
+"""
+
+
+def bulleted_list(items):
+    return "\n".join(map("  - {}".format, items))

interface/functional.py

@@ -3,6 +3,8 @@
 ----------
 Functional programming utilities.
 """
+from collections import deque
+from operator import itemgetter
 from .compat import viewkeys
 
 
@@ -16,6 +18,10 @@ def keyfilter(f, d):
     return {k: v for k, v in d.items() if f(k)}
 
 
+def keysorted(d):
+    return sorted(d.items(), key=itemgetter(0))
+
+
 def valfilter(f, d):
     return {k: v for k, v in d.items() if f(v)}
 
@@ -25,3 +31,19 @@ def dzip(left, right):
         k: (left.get(k), right.get(k))
         for k in viewkeys(left) & viewkeys(right)
     }
+
+
+def sliding_window(iterable, n):
+    it = iter(iterable)
+    items = deque(maxlen=n)
+    try:
+        for i in range(n):
+            items.append(next(it))
+    except StopIteration:
+        return
+
+    yield tuple(items)
+
+    for item in it:
+        items.append(item)
+        yield tuple(items)

interface/interface.py

@@ -2,14 +2,15 @@
 interface
 ---------
 """
-from functools import wraps
-import inspect
+from collections import defaultdict
 from operator import attrgetter, itemgetter
 from textwrap import dedent
 from weakref import WeakKeyDictionary
 
 from .compat import raise_from, with_metaclass
-from .functional import complement, keyfilter
+from .default import default, warn_if_defaults_use_non_interface_members
+from .formatting import bulleted_list
+from .functional import complement, keyfilter, valfilter
 from .typecheck import compatible
 from .typed_signature import TypedSignature
 from .utils import is_a, unique
@@ -18,7 +19,7 @@
 getname = attrgetter('__name__')
 
 
-class IncompleteImplementation(TypeError):
+class InvalidImplementation(TypeError):
     """
     Raised when a class intending to implement an interface fails to do so.
     """
@@ -47,6 +48,37 @@ def static_get_type_attr(t, name):
     raise AttributeError(name)
 
 
+def _conflicting_defaults(typename, conflicts):
+    """Format an error message for conflicting default implementations.
+
+    Parameters
+    ----------
+    typename : str
+        Name of the type for which we're producing an error.
+    conflicts : dict[str -> list[Interface]]
+        Map from strings to interfaces providing a default with that name.
+
+    Returns
+    -------
+    message : str
+        User-facing error message.
+    """
+    message = "\nclass {C} received conflicting default implementations:".format(
+        C=typename,
+    )
+    for attrname, interfaces in conflicts.items():
+        message += dedent(
+            """
+
+            The following interfaces provided default implementations for {attr!r}:
+            {interfaces}"""
+        ).format(
+            attr=attrname,
+            interfaces=bulleted_list(sorted(map(getname, interfaces))),
+        )
+    return InvalidImplementation(message)
+
+
 class InterfaceMeta(type):
     """
     Metaclass for interfaces.
@@ -55,6 +87,7 @@ class InterfaceMeta(type):
     """
     def __new__(mcls, name, bases, clsdict):
         signatures = {}
+        defaults = {}
         for k, v in keyfilter(is_interface_field_name, clsdict).items():
             try:
                 signatures[k] = TypedSignature(v)
@@ -69,7 +102,17 @@ def __new__(mcls, name, bases, clsdict):
                 )
                 raise_from(TypeError(errmsg), e)
 
+            if isinstance(v, default):
+                defaults[k] = v
+
+        warn_if_defaults_use_non_interface_members(
+            name,
+            defaults,
+            set(signatures.keys())
+        )
+
         clsdict['_signatures'] = signatures
+        clsdict['_defaults'] = defaults
         return super(InterfaceMeta, mcls).__new__(mcls, name, bases, clsdict)
 
     def _diff_signatures(self, type_):
@@ -129,9 +172,20 @@ def verify(self, type_):
         -------
         None
         """
-        missing, mistyped, mismatched = self._diff_signatures(type_)
+        raw_missing, mistyped, mismatched = self._diff_signatures(type_)
+
+        # See if we have defaults for missing methods.
+        missing = []
+        defaults_to_use = {}
+        for name in raw_missing:
+            try:
+                defaults_to_use[name] = self._defaults[name].implementation
+            except KeyError:
+                missing.append(name)
+
         if not any((missing, mistyped, mismatched)):
-            return
+            return defaults_to_use
+
         raise self._invalid_implementation(type_, missing, mistyped, mismatched)
 
     def _invalid_implementation(self, t, missing, mistyped, mismatched):
@@ -176,7 +230,7 @@ def _invalid_implementation(self, t, missing, mistyped, mismatched):
                 I=getname(self),
                 mismatched_methods=self._format_mismatched_methods(mismatched),
             )
-        return IncompleteImplementation(message)
+        return InvalidImplementation(message)
 
     def _format_missing_methods(self, missing):
         return "\n".join(sorted([
@@ -231,18 +285,31 @@ def __new__(mcls, name, bases, clsdict, interfaces=empty_set):
             return newtype
 
         errors = []
-        for iface in newtype.interfaces():
+        default_impls = {}
+        default_providers = defaultdict(list)
+        for iface in sorted(newtype.interfaces(), key=getname):
             try:
-                iface.verify(newtype)
-            except IncompleteImplementation as e:
+                defaults_from_iface = iface.verify(newtype)
+                for name, impl in defaults_from_iface.items():
+                    default_impls[name] = impl
+                    default_providers[name].append(iface)
+            except InvalidImplementation as e:
                 errors.append(e)
 
+        # The list of providers for `name`, if there's more than one.
+        duplicate_defaults = valfilter(lambda ifaces: len(ifaces) > 1, default_providers)
+        if duplicate_defaults:
+            errors.append(_conflicting_defaults(newtype.__name__, duplicate_defaults))
+        else:
+            for name, impl in default_impls.items():
+                setattr(newtype, name, impl)
+
         if not errors:
             return newtype
         elif len(errors) == 1:
             raise errors[0]
         else:
-            raise IncompleteImplementation("\n\n".join(map(str, errors)))
+            raise InvalidImplementation("\n".join(map(str, errors)))
 
     def __init__(mcls, name, bases, clsdict, interfaces=empty_set):
         mcls._interfaces = interfaces
@@ -308,7 +375,7 @@ def implements(*interfaces):
         ordered_ifaces = tuple(sorted(interfaces, key=getname))
         iface_names = list(map(getname, ordered_ifaces))
 
-        name = "Implements{I}".format(I="_".join(iface_names))
+        name = "Implements{}".format("_".join(iface_names))
         doc = dedent(
             """\
             Implementation of {interfaces}.
@@ -336,5 +403,6 @@ def implements(*interfaces):
         return result
     return implements
 
+
 implements = _make_implements()
 del _make_implements

interface/tests/test_functional.py

@@ -0,0 +1,41 @@
+from functools import total_ordering
+
+import pytest
+
+from ..functional import keysorted, sliding_window
+
+
+def test_sliding_window():
+    assert list(sliding_window([], 2)) == []
+    assert list(sliding_window([1, 2, 3], 2)) == [(1, 2), (2, 3)]
+    assert list(sliding_window([1, 2, 3, 4], 2)) == [(1, 2), (2, 3), (3, 4)]
+    assert list(sliding_window([1, 2, 3, 4], 3)) == [(1, 2, 3), (2, 3, 4)]
+
+
+def test_keysorted():
+
+    @total_ordering
+    class Unorderable(object):
+
+        def __init__(self, obj):
+            self.obj = obj
+
+        def __eq__(self, other):
+            raise AssertionError("Can't compare this.")
+
+        __ne__ = __lt__ = __eq__
+
+    with pytest.raises(AssertionError):
+        sorted([Unorderable(0), Unorderable(0)])
+
+    d = {'c': Unorderable(3), 'b': Unorderable(2), 'a': Unorderable(1)}
+    items = keysorted(d)
+
+    assert items[0][0] == 'a'
+    assert items[0][1].obj == 1
+
+    assert items[1][0] == 'b'
+    assert items[1][1].obj == 2
+
+    assert items[2][0] == 'c'
+    assert items[2][1].obj == 3