Let interface 'subclasses' override __adapt__.issue3

Cooperate with InterfaceClass to ensure there is no performance penalty for this. Fixes #3

+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| Benchmark                                                   | bench_master38 | bench_issue3                 | bench_issue3_opt             |
+=============================================================+================+==============================+==============================+
| call interface (provides; deep)                             | 369 ns         | 454 ns: 1.23x slower (+23%)  | not significant              |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (provides; wide)                             | 373 ns         | 457 ns: 1.22x slower (+22%)  | 365 ns: 1.02x faster (-2%)   |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (no alternate, no conform, not provided)     | 671 ns         | 760 ns: 1.13x slower (+13%)  | 636 ns: 1.06x faster (-5%)   |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (alternate, no conform, not provided)        | 395 ns         | 494 ns: 1.25x slower (+25%)  | not significant              |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (no alternate, valid conform, not provided)  | 250 ns         | not significant              | 227 ns: 1.10x faster (-9%)   |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (alternate, invalid conform, not provided)   | 348 ns         | 424 ns: 1.22x slower (+22%)  | not significant              |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+

1 files changed, 29 insertions, 0 deletions

diff --git a/src/zope/interface/interfaces.py b/src/zope/interface/interfaces.py
index c0ece6a..6321d0c 100644
--- a/src/zope/interface/interfaces.py
+++ b/src/zope/interface/interfaces.py
@@ -518,6 +518,35 @@ class IInterfaceDeclaration(Interface):
         .. seealso:: `zope.interface.invariant`
         """
 
+    def interfacemethod(method):
+        """
+        A decorator that transforms a method specification into an
+        implementation method.
+
+        This is used to override methods of ``Interface`` or provide new methods.
+        Definitions using this decorator will not appear in :meth:`IInterface.names()`.
+        It is possible to have an implementation method and a method specification
+        of the same name.
+
+        For example::
+
+           class IRange(Interface):
+                @interfacemethod
+                def __adapt__(self, obj):
+                    if isinstance(obj, range):
+                       # Return the builtin ``range`` as-is
+                       return obj
+                    return super(type(IRange), self).__adapt__(obj)
+
+        You can use ``super`` to call the parent class functionality. Note that
+        the zero-argument version (``super().__adapt__``) works on Python 3.6 and above, but
+        prior to that the two-argument version must be used, and the class must be explicitly
+        passed as the first argument.
+
+        .. versionadded:: 5.1.0
+        .. seealso:: `zope.interface.interfacemethod`
+        """
+
     ###
     # Querying interfaces
     ###