Merge pull request #1 from ssanderson/allow-compatible-extensions

ENH: Add support for interface extensions.

Author: Scott Sanderson

interface/functional.py

@@ -0,0 +1,19 @@
+"""
+functional
+----------
+Functional programming utilities.
+"""
+
+
+def complement(f):
+    def not_f(*args, **kwargs):
+        return not f(*args, **kwargs)
+    return not_f
+
+
+def valfilter(f, d):
+    return {k: v for k, v in d.items() if f(v)}
+
+
+def dzip(left, right):
+    return {k: (left.get(k), right.get(k)) for k in left.keys() & right.keys()}

interface/interface.py

@@ -8,6 +8,7 @@
 from textwrap import dedent
 from weakref import WeakKeyDictionary
 
+from .typecheck import compatible
 from .utils import is_a, unique
 
 first = itemgetter(0)
@@ -20,15 +21,6 @@ class IncompleteImplementation(TypeError):
     """
 
 
-def compatible(meth_sig, iface_sig):
-    """
-    Check if ``method``'s signature is compatible with ``signature``.
-    """
-    # TODO: Allow method to provide defaults and optional extensions to
-    # ``signature``.
-    return meth_sig == iface_sig
-
-
 class InterfaceMeta(type):
     """
     Metaclass for interfaces.
@@ -70,9 +62,9 @@ def _diff_signatures(self, type_):
             except AttributeError:
                 missing.append(name)
                 continue
-            f_sig = inspect.signature(f)
-            if not compatible(f_sig, iface_sig):
-                mismatched[name] = f_sig
+            impl_sig = inspect.signature(f)
+            if not compatible(impl_sig, iface_sig):
+                mismatched[name] = impl_sig
         return missing, mismatched
 
     def verify(self, type_):
@@ -120,10 +112,11 @@ def _invalid_implementation(self, t, missing, mismatched):
             )
 
         if mismatched:
-            message += (
-                "\n\nThe following methods of {I} were implemented with invalid"
-                " signatures:\n"
-                "{mismatched_methods}"
+            message += dedent(
+                """
+
+                The following methods of {I} were implemented with invalid signatures:
+                {mismatched_methods}"""
             ).format(
                 I=getname(self),
                 mismatched_methods=self._format_mismatched_methods(mismatched),

interface/tests/test_typecheck.py

@@ -0,0 +1,115 @@
+from inspect import signature
+
+from ..typecheck import compatible
+
+
+def test_compatible_when_equal():
+
+    @signature
+    def foo(a, b, c):  # pragma: nocover
+        pass
+
+    assert compatible(foo, foo)
+
+    @signature
+    def bar():  # pragma: nocover
+        pass
+
+    assert compatible(bar, bar)
+
+
+def test_allow_new_params_with_defaults():
+
+    @signature
+    def iface(a, b, c):  # pragma: nocover
+        pass
+
+    @signature
+    def impl(a, b, c, d=3, e=5, *, f=5):  # pragma: nocover
+        pass
+
+    assert compatible(impl, iface)
+    assert not compatible(iface, impl)
+
+
+def test_allow_reorder_kwonlys():
+
+    @signature
+    def foo(a, b, c, *, d, e, f):  # pragma: nocover
+        pass
+
+    @signature
+    def bar(a, b, c, *, f, d, e):  # pragma: nocover
+        pass
+
+    assert compatible(foo, bar)
+    assert compatible(bar, foo)
+
+
+def test_allow_default_changes():
+
+    @signature
+    def foo(a, b, c=3, *, d=1, e, f):  # pragma: nocover
+        pass
+
+    @signature
+    def bar(a, b, c=5, *, f, e, d=12):  # pragma: nocover
+        pass
+
+    assert compatible(foo, bar)
+    assert compatible(bar, foo)
+
+
+def test_disallow_new_or_missing_positionals():
+
+    @signature
+    def foo(a, b):  # pragma: nocover
+        pass
+
+    @signature
+    def bar(a):  # pragma: nocover
+        pass
+
+    assert not compatible(foo, bar)
+    assert not compatible(bar, foo)
+
+
+def test_disallow_remove_defaults():
+
+    @signature
+    def iface(a, b=3):  # pragma: nocover
+        pass
+
+    @signature
+    def impl(a, b):  # pragma: nocover
+        pass
+
+    assert not compatible(impl, iface)
+
+
+def test_disallow_reorder_positionals():
+
+    @signature
+    def foo(a, b):  # pragma: nocover
+        pass
+
+    @signature
+    def bar(b, a):  # pragma: nocover
+        pass
+
+    assert not compatible(foo, bar)
+    assert not compatible(bar, foo)
+
+
+def test_disallow_kwonly_to_positional():
+
+    @signature
+    def foo(a, *, b):  # pragma: nocover
+        pass
+
+    @signature
+    def bar(a, b):  # pragma: nocover
+        pass
+
+    assert not compatible(foo, bar)
+    assert not compatible(bar, foo)

interface/tests/test_utils.py

@@ -0,0 +1,12 @@
+import pytest
+
+from ..utils import is_a, unique
+
+
+def test_unique():
+    assert list(unique(iter([1, 3, 1, 2, 3]))) == [1, 3, 2]
+
+
+def test_is_a():
+    assert is_a(int)(5)
+    assert not is_a(str)(5)

interface/typecheck.py

@@ -0,0 +1,96 @@
+"""
+Utilities for typed interfaces.
+"""
+from inspect import Parameter
+from itertools import dropwhile, starmap, takewhile, zip_longest
+from operator import contains
+
+from .functional import complement, dzip, valfilter
+
+
+def compatible(impl_sig, iface_sig):
+    """
+    Check whether ``impl_sig`` is compatible with ``iface_sig``.
+
+    In general, an implementation is compatible with an interface if any valid
+    way of passing parameters to the interface method is also valid for the
+    implementation.
+
+    The following differences are allowed between an implementation and its
+    interface:
+
+    1. An implementation may add new arguments to an interface iff:
+       a. All new arguments have default values.
+       b. All new arguments accepted positionally (i.e. all non-keyword-only
+          arguments) occur after any arguments declared by the interface.
+       c. Keyword-only arguments may be reordered by the implementation.
+
+    2. For type-annotated interfaces, type annotations my differ as follows:
+       a. Arguments to implementations of an interface may be annotated with
+          a **superclass** of the type specified by the interface.
+       b. The return type of an implementation may be annotated with a
+          **subclass** of the type specified by the interface.
+    """
+    return all([
+        positionals_compatible(
+            takewhile(is_positional, impl_sig.parameters.values()),
+            takewhile(is_positional, iface_sig.parameters.values()),
+        ),
+        keywords_compatible(
+            valfilter(complement(is_positional), impl_sig.parameters),
+            valfilter(complement(is_positional), iface_sig.parameters),
+        ),
+    ])
+
+
+_POSITIONALS = frozenset([
+    Parameter.POSITIONAL_ONLY,
+    Parameter.POSITIONAL_OR_KEYWORD,
+])
+
+
+def is_positional(arg):
+    return arg.kind in _POSITIONALS
+
+
+def has_default(arg):
+    """
+    Does ``arg`` provide a default?
+    """
+    return arg.default is not Parameter.empty
+
+
+def params_compatible(impl, iface):
+
+    if impl is None:
+        return False
+
+    if iface is None:
+        return has_default(impl)
+
+    return (
+        impl.name == iface.name and
+        impl.kind == iface.kind and
+        has_default(impl) == has_default(iface) and
+        annotations_compatible(impl, iface)
+    )
+
+
+def positionals_compatible(impl_positionals, iface_positionals):
+    return all(
+        starmap(params_compatible, zip_longest(impl_positionals, iface_positionals))
+    )
+
+
+def keywords_compatible(impl_keywords, iface_keywords):
+    return all(
+        starmap(params_compatible, dzip(impl_keywords, iface_keywords).values())
+    )
+
+
+def annotations_compatible(impl, iface):
+    """
+    Check whether the type annotations of an implementation are compatible with
+    the annotations of the interface it implements.
+    """
+    return impl.annotation == iface.annotation

interface/utils.py

@@ -0,0 +1,31 @@
+"""
+Miscellaneous utilities.
+"""
+
+
+def unique(g):
+    """
+    Yield values yielded by ``g``, removing any duplicates.
+
+    Example
+    -------
+    >>> list(unique(iter([1, 3, 1, 2, 3])))
+    [1, 3, 2]
+    """
+    yielded = set()
+    for value in g:
+        if value not in yielded:
+            yield value
+            yielded.add(value)
+
+
+def is_a(t):
+    """
+    Partially-applied, flipped isinstance.
+
+    >>> is_a(int)(5)
+    True
+    >>> is_a(str)(5)
+    False
+    """
+    return lambda v: isinstance(v, t)

setup.py

@@ -19,6 +19,11 @@ def extras_require():
         ],
     }
 
+def install_requires():
+    if sys.version_info[:2] < (3, 5):
+        return ["typing>=3.5.2"]
+    return []
+
 
 setup(
     name='interface',
@@ -39,5 +44,6 @@ def extras_require():
         'Topic :: Software Development :: Pre-processors',
     ],
     url='https://github.com/ssanderson/interface',
+    install_requires=install_requires(),
     extras_require=extras_require(),
 )

tox.ini

@@ -2,11 +2,15 @@
 envlist=py{34,35}
 skip_missing_interpreters=true
 
+[pep8]
+max-line-length = 90
+
 [testenv]
 commands=
     pip install -e .[test]
     py.test --cov-fail-under 100
 
 [pytest]
+pep8maxlinelength = 90
 addopts = --pep8 --cov interface --cov-report term-missing --cov-report html
 testpaths = interface