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              |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+

2 files changed, 44 insertions, 7 deletions

diff --git a/docs/README.rst b/docs/README.rst
index 6fbd5f8..0364a81 100644
--- a/docs/README.rst
+++ b/docs/README.rst
@@ -863,7 +863,8 @@ Adaptation
 
 Interfaces can be called to perform adaptation.
 
-The semantics are based on those of the PEP 246 ``adapt`` function.
+The semantics are based on those of the  :pep:`246` ``adapt``
+function.
 
 If an object cannot be adapted, then a ``TypeError`` is raised:
 
@@ -897,7 +898,13 @@ If an object already implements the interface, then it will be returned:
   >>> I(obj) is obj
   True
 
-If an object implements ``__conform__``, then it will be used:
+:pep:`246` outlines a requirement:
+
+    When the object knows about the [interface], and either considers
+    itself compliant, or knows how to wrap itself suitably.
+
+This is handled with ``__conform__``. If an object implements
+``__conform__``, then it will be used:
 
 .. doctest::
 
@@ -936,21 +943,27 @@ Adapter hooks (see ``__adapt__``) will also be used, if present:
   >>> class I(zope.interface.Interface):
   ...     pass
 
-Interfaces implement the PEP 246 ``__adapt__`` method.
+Interfaces implement the :pep:`246` ``__adapt__`` method to satisfy
+the requirement:
+
+    When the [interface] knows about the object, and either the object
+    already complies or the [interface] knows how to suitably wrap the
+    object.
 
-This method is normally not called directly. It is called by the PEP
-246 adapt framework and by the interface ``__call__`` operator.
+This method is normally not called directly. It is called by the
+:pep:`246` adapt framework and by the interface ``__call__`` operator.
 
 The ``adapt`` method is responsible for adapting an object to the
 reciever.
 
-The default version returns ``None``:
+The default version returns ``None`` (because by default no interface
+"knows how to suitably wrap the object"):
 
 .. doctest::
 
   >>> I.__adapt__(0)
 
-unless the object given provides the interface:
+unless the object given provides the interface ("the object already complies"):
 
 .. doctest::
 
@@ -989,6 +1002,28 @@ Hooks can be uninstalled by removing them from the list:
   >>> I.__adapt__(0)
 
 
+It is possible to replace or customize the ``__adapt___``
+functionality for particular interfaces.
+
+.. doctest::
+
+   >>> class ICustomAdapt(zope.interface.Interface):
+   ...     @zope.interface.interfacemethod
+   ...     def __adapt__(self, obj):
+   ...          if isinstance(obj, str):
+   ...              return obj
+   ...          return super(type(ICustomAdapt), self).__adapt__(obj)
+
+   >>> @zope.interface.implementer(ICustomAdapt)
+   ... class CustomAdapt(object):
+   ...    pass
+   >>> ICustomAdapt('a string')
+   'a string'
+   >>> ICustomAdapt(CustomAdapt())
+   <CustomAdapt object at ...>
+
+.. seealso:: :func:`zope.interface.interfacemethod`
+
 .. [#create] The main reason we subclass ``Interface`` is to cause the
              Python class statement to create an interface, rather
              than a class.
diff --git a/docs/api/declarations.rst b/docs/api/declarations.rst
index 955d246..fa265e7 100644
--- a/docs/api/declarations.rst
+++ b/docs/api/declarations.rst
@@ -36,6 +36,8 @@ To declare an interface itself, extend the ``Interface`` base class.
 
    .. documented in README.rst
 
+.. autofunction:: interfacemethod
+
 Declaring The Interfaces of Objects
 ===================================