diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/README.rst | 49 | ||||
| -rw-r--r-- | docs/api/declarations.rst | 2 |
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 =================================== |