Port the documentation examples to Python 3

7 files changed, 188 insertions, 161 deletions

diff --git a/docs/README.rst b/docs/README.rst
index e54b692..4e83c4a 100644
--- a/docs/README.rst
+++ b/docs/README.rst
@@ -64,7 +64,7 @@ and even its module:
 .. doctest::
 
   >>> IFoo.__module__
-  '__builtin__'
+  'builtins'
 
 The interface defined two attributes:
 
@@ -175,13 +175,13 @@ declaring interfaces.
 Declaring implemented interfaces
 --------------------------------
 
-The most common way to declare interfaces is using the implements
-function in a class statement:
+The most common way to declare interfaces is using the `implementer`
+decorator on a class:
 
 .. doctest::
 
-  >>> class Foo:
-  ...     zope.interface.implements(IFoo)
+  >>> @zope.interface.implementer(IFoo)
+  ... class Foo:
   ...
   ...     def __init__(self, x=None):
   ...         self.x = x
@@ -223,7 +223,7 @@ We can also ask what interfaces are implemented by a class:
 .. doctest::
 
   >>> list(zope.interface.implementedBy(Foo))
-  [<InterfaceClass __builtin__.IFoo>]
+  [<InterfaceClass builtins.IFoo>]
 
 It's an error to ask for interfaces implemented by a non-callable
 object:
@@ -245,24 +245,23 @@ Similarly, we can ask what interfaces are provided by an object:
 .. doctest::
 
   >>> list(zope.interface.providedBy(foo))
-  [<InterfaceClass __builtin__.IFoo>]
+  [<InterfaceClass builtins.IFoo>]
   >>> list(zope.interface.providedBy(Foo))
   []
 
 We can declare interfaces implemented by other factories (besides
-classes).  We do this using a Python-2.4-style decorator named
-`implementer`.  In versions of Python before 2.4, this looks like:
+classes).  We do this using the same `implementer` decorator.
 
 .. doctest::
 
-  >>> def yfoo(y):
+  >>> @zope.interface.implementer(IFoo)
+  ... def yfoo(y):
   ...     foo = Foo()
   ...     foo.y = y
   ...     return foo
-  >>> yfoo = zope.interface.implementer(IFoo)(yfoo)
 
   >>> list(zope.interface.implementedBy(yfoo))
-  [<InterfaceClass __builtin__.IFoo>]
+  [<InterfaceClass builtins.IFoo>]
 
 Note that the implementer decorator may modify its argument. Callers
 should not assume that a new object is created.
@@ -281,7 +280,7 @@ Using implementer also works on callable objects. This is used by
   >>> yfoo = zope.interface.implementer(IFoo)(yfoo)
 
   >>> list(zope.interface.implementedBy(yfoo))
-  [<InterfaceClass __builtin__.IFoo>]
+  [<InterfaceClass builtins.IFoo>]
 
 XXX: Double check and update these version numbers:
 
@@ -292,9 +291,9 @@ be used for classes, but in 3.6.0 and higher it can:
 
   >>> Foo = zope.interface.implementer(IFoo)(Foo)
   >>> list(zope.interface.providedBy(Foo()))
-  [<InterfaceClass __builtin__.IFoo>]
-  
-Note that class decorators using the ``@implementer(IFoo)`` syntax are only 
+  [<InterfaceClass builtins.IFoo>]
+
+Note that class decorators using the ``@implementer(IFoo)`` syntax are only
 supported in Python 2.6 and later.
 
 
@@ -330,19 +329,18 @@ And then, we'll see that Foo provides some interfaces:
 .. doctest::
 
   >>> list(zope.interface.providedBy(Foo))
-  [<InterfaceClass __builtin__.IFooFactory>]
+  [<InterfaceClass builtins.IFooFactory>]
   >>> IFooFactory.providedBy(Foo)
   True
 
 Declaring class interfaces is common enough that there's a special
-declaration function for it, `classProvides`, that allows the
-declaration from within a class statement:
+decorator for it, `provider`:
 
 .. doctest::
 
-  >>> class Foo2:
-  ...     zope.interface.implements(IFoo)
-  ...     zope.interface.classProvides(IFooFactory)
+  >>> @zope.interface.implementer(IFoo)
+  ... @zope.interface.provider(IFooFactory)
+  ... class Foo2:
   ...
   ...     def __init__(self, x=None):
   ...         self.x = x
@@ -354,7 +352,7 @@ declaration from within a class statement:
   ...         return "Foo(%s)" % self.x
 
   >>> list(zope.interface.providedBy(Foo2))
-  [<InterfaceClass __builtin__.IFooFactory>]
+  [<InterfaceClass builtins.IFooFactory>]
   >>> IFooFactory.providedBy(Foo2)
   True
 
@@ -401,14 +399,14 @@ then the new interface is included in the provided interfaces:
   >>> ISpecial.providedBy(foo)
   True
   >>> list(zope.interface.providedBy(foo))
-  [<InterfaceClass __builtin__.ISpecial>, <InterfaceClass __builtin__.IFoo>]
+  [<InterfaceClass builtins.ISpecial>, <InterfaceClass builtins.IFoo>]
 
 We can find out what interfaces are directly provided by an object:
 
 .. doctest::
 
   >>> list(zope.interface.directlyProvidedBy(foo))
-  [<InterfaceClass __builtin__.ISpecial>]
+  [<InterfaceClass builtins.ISpecial>]
 
   >>> newfoo = Foo()
   >>> list(zope.interface.directlyProvidedBy(newfoo))
@@ -421,34 +419,34 @@ Normally, declarations are inherited:
 
 .. doctest::
 
-  >>> class SpecialFoo(Foo):
-  ...     zope.interface.implements(ISpecial)
+  >>> @zope.interface.implementer(ISpecial)
+  ... class SpecialFoo(Foo):
   ...     reason = 'I just am'
   ...     def brag(self):
   ...         return "I'm special because %s" % self.reason
 
   >>> list(zope.interface.implementedBy(SpecialFoo))
-  [<InterfaceClass __builtin__.ISpecial>, <InterfaceClass __builtin__.IFoo>]
+  [<InterfaceClass builtins.ISpecial>, <InterfaceClass builtins.IFoo>]
 
   >>> list(zope.interface.providedBy(SpecialFoo()))
-  [<InterfaceClass __builtin__.ISpecial>, <InterfaceClass __builtin__.IFoo>]
+  [<InterfaceClass builtins.ISpecial>, <InterfaceClass builtins.IFoo>]
 
 Sometimes, you don't want to inherit declarations.  In that case, you
-can use ``implementsOnly``, instead of ``implements``:
+can use ``implementer_only``, instead of ``implementer``:
 
 .. doctest::
 
-  >>> class Special(Foo):
-  ...     zope.interface.implementsOnly(ISpecial)
+  >>> @zope.interface.implementer_only(ISpecial)
+  ... class Special(Foo):
   ...     reason = 'I just am'
   ...     def brag(self):
   ...         return "I'm special because %s" % self.reason
 
   >>> list(zope.interface.implementedBy(Special))
-  [<InterfaceClass __builtin__.ISpecial>]
+  [<InterfaceClass builtins.ISpecial>]
 
   >>> list(zope.interface.providedBy(Special()))
-  [<InterfaceClass __builtin__.ISpecial>]
+  [<InterfaceClass builtins.ISpecial>]
 
 External declarations
 ---------------------
@@ -466,7 +464,7 @@ be used for this purpose:
 
   >>> zope.interface.classImplements(C, IFoo)
   >>> list(zope.interface.implementedBy(C))
-  [<InterfaceClass __builtin__.IFoo>]
+  [<InterfaceClass builtins.IFoo>]
 
 We can use ``classImplementsOnly`` to exclude inherited interfaces:
 
@@ -477,7 +475,7 @@ We can use ``classImplementsOnly`` to exclude inherited interfaces:
 
   >>> zope.interface.classImplementsOnly(C, ISpecial)
   >>> list(zope.interface.implementedBy(C))
-  [<InterfaceClass __builtin__.ISpecial>]
+  [<InterfaceClass builtins.ISpecial>]
 
 
 
@@ -499,23 +497,23 @@ declarations. Here's a silly example:
 
 .. doctest::
 
-  >>> class Special2(Foo):
-  ...     zope.interface.implementsOnly(
-  ...          zope.interface.implementedBy(Foo),
-  ...          ISpecial,
-  ...          )
+  >>> @zope.interface.implementer_only(
+  ...     zope.interface.implementedBy(Foo),
+  ...     ISpecial,
+  ... )
+  ... class Special2(Foo):
   ...     reason = 'I just am'
   ...     def brag(self):
   ...         return "I'm special because %s" % self.reason
 
 The declaration here is almost the same as
-``zope.interface.implements(ISpecial)``, except that the order of
+``zope.interface.implementer(ISpecial)``, except that the order of
 interfaces in the resulting declaration is different:
 
 .. doctest::
 
   >>> list(zope.interface.implementedBy(Special2))
-  [<InterfaceClass __builtin__.IFoo>, <InterfaceClass __builtin__.ISpecial>]
+  [<InterfaceClass builtins.IFoo>, <InterfaceClass builtins.ISpecial>]
 
 
 Interface Inheritance
@@ -543,7 +541,7 @@ the other interfaces as base interfaces:
   ...
 
   >>> IBaz.__bases__
-  (<InterfaceClass __builtin__.IFoo>, <InterfaceClass __builtin__.IBlat>)
+  (<InterfaceClass builtins.IFoo>, <InterfaceClass builtins.IBlat>)
 
   >>> names = list(IBaz)
   >>> names.sort()
@@ -656,12 +654,13 @@ interfaces that they declare:
 
 .. doctest::
 
-  >>> class Baz(object):
-  ...     zope.interface.implements(IBaz)
+  >>> @zope.interface.implementer(IBaz)
+  ... class Baz(object):
+  ...     pass
 
   >>> baz_implements = zope.interface.implementedBy(Baz)
   >>> baz_implements.__bases__
-  (<InterfaceClass __builtin__.IBaz>, <implementedBy ...object>)
+  (<InterfaceClass builtins.IBaz>, <implementedBy ...object>)
 
   >>> baz_implements.extends(IFoo)
   True
@@ -678,10 +677,10 @@ that lists the specification and all of it's ancestors:
 
   >>> from pprint import pprint
   >>> pprint(baz_implements.__sro__)
-  (<implementedBy __builtin__.Baz>,
-   <InterfaceClass __builtin__.IBaz>,
-   <InterfaceClass __builtin__.IFoo>,
-   <InterfaceClass __builtin__.IBlat>,
+  (<implementedBy builtins.Baz>,
+   <InterfaceClass builtins.IBaz>,
+   <InterfaceClass builtins.IFoo>,
+   <InterfaceClass builtins.IBlat>,
    <InterfaceClass zope.interface.Interface>,
    <implementedBy ...object>)
 
@@ -718,7 +717,7 @@ attribute definitions are created:
   ...     __call__.return_type = IBaz
 
   >>> IBazFactory['__call__'].getTaggedValue('return_type')
-  <InterfaceClass __builtin__.IBaz>
+  <InterfaceClass builtins.IBaz>
 
 Tagged values can also be defined from within an interface definition:
 
@@ -763,9 +762,8 @@ Interfaces have a method for checking their invariants:
 
 .. doctest::
 
-  >>> class Range(object):
-  ...     zope.interface.implements(IRange)
-  ...
+  >>> @zope.interface.implementer(IRange)
+  ... class Range(object):
   ...     def __init__(self, min, max):
   ...         self.min, self.max = min, max
   ...
@@ -790,7 +788,7 @@ exceptions as its argument:
   >>> errors = []
   >>> try:
   ...     IRange.validateInvariants(Range(2,1), errors)
-  ... except Invalid, e:
+  ... except Invalid as e:
   ...     str(e)
   '[RangeError(Range(2, 1))]'
   
@@ -820,7 +818,7 @@ If an object cannot be adapted, then a ``TypeError`` is raised:
   >>> I(0)
   Traceback (most recent call last):
   ...
-  TypeError: ('Could not adapt', 0, <InterfaceClass __builtin__.I>)
+  TypeError: ('Could not adapt', 0, <InterfaceClass builtins.I>)
 
 
 unless an alternate value is provided as a second positional argument:
@@ -834,8 +832,9 @@ If an object already implements the interface, then it will be returned:
 
 .. doctest::
 
-  >>> class C(object):
-  ...     zope.interface.implements(I)
+  >>> @zope.interface.implementer(I)
+  ... class C(object):
+  ...     pass
 
   >>> obj = C()
   >>> I(obj) is obj
@@ -845,8 +844,8 @@ If an object implements ``__conform__``, then it will be used:
 
 .. doctest::
 
-  >>> class C(object):
-  ...     zope.interface.implements(I)
+  >>> @zope.interface.implementer(I)
+  ... class C(object):
   ...     def __conform__(self, proto):
   ...          return 0
 
@@ -870,7 +869,7 @@ Adapter hooks (see ``__adapt__``) will also be used, if present:
   >>> I(0)
   Traceback (most recent call last):
   ...
-  TypeError: ('Could not adapt', 0, <InterfaceClass __builtin__.I>)
+  TypeError: ('Could not adapt', 0, <InterfaceClass builtins.I>)
 
 ``__adapt__``
 -------------
@@ -898,8 +897,9 @@ unless the object given provides the interface:
 
 .. doctest::
 
-  >>> class C(object):
-  ...     zope.interface.implements(I)
+  >>> @zope.interface.implementer(I)
+  ... class C(object):
+  ...     pass
 
   >>> obj = C()
   >>> I.__adapt__(obj) is obj
diff --git a/docs/adapter.rst b/docs/adapter.rst
index 517ae9b..6a728a3 100644
--- a/docs/adapter.rst
+++ b/docs/adapter.rst
@@ -67,8 +67,9 @@ We can use a class implementation specification to look up the object:
 
 .. doctest::
 
-  >>> class C2:
-  ...     zope.interface.implements(IRequire2)
+  >>> @zope.interface.implementer(IRequire2)
+  ... class C2:
+  ...     pass
 
   >>> registry.lookup([zope.interface.implementedBy(C2)], IProvide2, '')
   12
@@ -154,20 +155,20 @@ exact match:
 
 .. doctest::
 
-  >>> print registry.registered([IRequire1], IProvide1)
+  >>> print(registry.registered([IRequire1], IProvide1))
   11
 
-  >>> print registry.registered([IRequire1], IProvide2)
+  >>> print(registry.registered([IRequire1], IProvide2))
   12
 
-  >>> print registry.registered([IRequire1], IProvide2, 'bob')
+  >>> print(registry.registered([IRequire1], IProvide2, 'bob'))
   Bob's 12
 
 
-  >>> print registry.registered([IRequire2], IProvide1)
+  >>> print(registry.registered([IRequire2], IProvide1))
   21
 
-  >>> print registry.registered([IRequire2], IProvide2)
+  >>> print(registry.registered([IRequire2], IProvide2))
   None
 
 In the last example, ``None`` was returned because nothing was registered
@@ -200,11 +201,12 @@ factories:
    >>> class IR(zope.interface.Interface):
    ...     pass
 
-   >>> class X:
-   ...     zope.interface.implements(IR)
+   >>> @zope.interface.implementer(IR)
+   ... class X:
+   ...     pass
 
-   >>> class Y:
-   ...     zope.interface.implements(IProvide1)
+   >>> @zope.interface.implementer(IProvide1)
+   ... class Y:
    ...     def __init__(self, context):
    ...         self.context = context
 
@@ -248,8 +250,8 @@ the state of the object being adapted:
   ...         return 'adapter'
   ...     return None
 
-  >>> class Object(object):
-  ...     zope.interface.implements(IR)
+  >>> @zope.interface.implementer(IR)
+  ... class Object(object):
   ...     name = 'object'
 
   >>> registry.register([IR], IProvide1, 'conditional', factory)
@@ -385,8 +387,9 @@ You can adapt multiple objects:
 
 .. doctest::
 
-  >>> class Q:
-  ...     zope.interface.implements(IQ)
+  >>> @zope.interface.implementer(IQ)
+  ... class Q:
+  ...     pass
 
 As with single adapters, we register a factory, which is often a class:
 
@@ -394,8 +397,8 @@ As with single adapters, we register a factory, which is often a class:
 
   >>> class IM(zope.interface.Interface):
   ...     pass
-  >>> class M:
-  ...     zope.interface.implements(IM)
+  >>> @zope.interface.implementer(IM)
+  ... class M:
   ...     def __init__(self, x, q):
   ...         self.x, self.q = x, q
   >>> registry.register([IR, IQ], IM, '', M)
@@ -637,7 +640,7 @@ To register a handler, simply provide ``None`` as the provided interface:
 .. doctest::
 
   >>> def handler(event):
-  ...     print 'handler', event
+  ...     print('handler', event)
 
   >>> registry.subscribe([IRequire1], None, handler)
   >>> registry.subscriptions([IRequire1], None) == [handler]
diff --git a/docs/api/declarations.rst b/docs/api/declarations.rst
index 98bc226..dede2b3 100644
--- a/docs/api/declarations.rst
+++ b/docs/api/declarations.rst
@@ -61,7 +61,7 @@ Consider the following example:
 .. doctest::
 
    >>> from zope.interface import implementedBy
-   >>> from zope.interface import implements
+   >>> from zope.interface import implementer
    >>> from zope.interface import classImplementsOnly
    >>> from zope.interface import Interface
    >>> class I1(Interface): pass
@@ -72,10 +72,12 @@ Consider the following example:
    ...
    >>> class I4(Interface): pass
    ...
-   >>> class A(object):
-   ...   implements(I3)
-   >>> class B(object):
-   ...   implements(I4)
+   >>> @implementer(I3)
+   ... class A(object):
+   ...     pass
+   >>> @implementer(I4)
+   ... class B(object):
+   ...     pass
    >>> class C(A, B):
    ...   pass
    >>> classImplementsOnly(C, I1, I2)
@@ -107,10 +109,12 @@ Consider the following example:
    ...
    >>> class I5(Interface): pass
    ...
-   >>> class A(object):
-   ...   implements(I3)
-   >>> class B(object):
-   ...   implements(I4)
+   >>> @implementer(I3)
+   ... class A(object):
+   ...     pass
+   >>> @implementer(I4)
+   ... class B(object):
+   ...     pass
    >>> class C(A, B):
    ...   pass
    >>> classImplements(C, I1, I2)
@@ -149,12 +153,15 @@ Consider the following example:
    ...
    >>> class IC(Interface): pass
    ...
-   >>> class A(object):
-   ...     implements(IA1, IA2)
-   >>> class B(object):
-   ...     implements(IB)
-   >>> class C(A, B):
-   ...    implements(IC)
+   >>> @implementer(IA1, IA2)
+   ... class A(object):
+   ...     pass
+   >>> @implementer(IB)
+   ... class B(object):
+   ...     pass
+   >>> @implementer(IC)
+   ... class C(A, B):
+   ...     pass
    >>> ob = C()
    >>> directlyProvides(ob, I1, I2)
    >>> int(I1 in providedBy(ob))
@@ -236,12 +243,15 @@ Consider the following example:
    ...
    >>> class IC(Interface): pass
    ...
-   >>> class A(object):
-   ...     implements(IA1, IA2)
-   >>> class B(object):
-   ...     implements(IB)
-   >>> class C(A, B):
-   ...    implements(IC)
+   >>> @implementer(IA1, IA2)
+   ... class A(object):
+   ...     pass
+   >>> @implementer(IB)
+   ... class B(object):
+   ...     pass
+   >>> @implementer(IC)
+   ... class C(A, B):
+   ...     pass
    >>> ob = C()
    >>> directlyProvides(ob, I1)
    >>> int(I1 in providedBy(ob))
@@ -295,8 +305,9 @@ by the object:
 
 .. doctest::
 
-   >>> class C(object):
-   ...    implements(I1)
+   >>> @implementer(I1)
+   ... class C(object):
+   ...     pass
    >>> c = C()
    >>> alsoProvides(c, I2)
    >>> I2.providedBy(c)
@@ -324,6 +335,8 @@ Removing an interface that is provided through the class is not possible:
 classProvides
 -------------
 
+(The `provider` decorator is preferred to this.)
+
 .. autofunction:: classProvides
 
 
@@ -332,15 +345,16 @@ For example:
 .. doctest::
 
    >>> from zope.interface import Interface
-   >>> from zope.interface.declarations import implementer
-   >>> from zope.interface import classProvides
+   >>> from zope.interface import implementer
+   >>> from zope.interface import provider
    >>> class IFooFactory(Interface):
    ...     pass
    >>> class IFoo(Interface):
    ...     pass
    >>> @implementer(IFoo)
+   ... @provider(IFooFactory)
    ... class C(object):
-   ...     classProvides(IFooFactory)
+   ...     pass
    >>> [i.getName() for i in C.__provides__]
    ['IFooFactory']
    >>> [i.getName() for i in C().__provides__]
@@ -425,7 +439,7 @@ Consider the following example:
 .. doctest::
 
    >>> from zope.interface import Interface
-   >>> from zope.interface import implements
+   >>> from zope.interface import implementer
    >>> from zope.interface import classImplementsOnly
    >>> from zope.interface import implementedBy
    >>> class I1(Interface): pass
@@ -436,10 +450,12 @@ Consider the following example:
    ...
    >>> class I4(Interface): pass
    ...
-   >>> class A(object):
-   ...   implements(I3)
-   >>> class B(object):
-   ...   implements(I4)
+   >>> @implementer(I3)
+   ... class A(object):
+   ...     pass
+   >>> @implementer(I4)
+   ... class B(object):
+   ...     pass
    >>> class C(A, B):
    ...   pass
    >>> classImplementsOnly(C, I1, I2)
@@ -462,10 +478,12 @@ Another example:
    ...
    >>> class I4(I3): pass
    ...
-   >>> class C1(object):
-   ...   implements(I2)
-   >>> class C2(C1):
-   ...   implements(I3)
+   >>> @implementer(I2)
+   ... class C1(object):
+   ...     pass
+   >>> @implementer(I3)
+   ... class C2(C1):
+   ...     pass
    >>> [i.getName() for i in implementedBy(C2)]
    ['I3', 'I2']
 
@@ -478,7 +496,7 @@ an instance:
    ...     def __call__(self):
    ...         return self
    >>> implementedBy(Callable())
-   <implementedBy __builtin__.?>
+   <implementedBy builtins.?>
 
 Note that the name of the spec ends with a '?', because the ``Callable``
 instance does not have a ``__name__`` attribute.
@@ -659,10 +677,10 @@ Descriptor semantics (via ``Provides.__get__``):
 .. doctest::
 
    >>> from zope.interface import Interface
-   >>> class IFooFactory(Interface): pass
-   ...
+   >>> class IFooFactory(Interface):
+   ...     pass
    >>> class C(object):
-   ...   pass
+   ...     pass
    >>> from zope.interface.declarations import ProvidesClass
    >>> C.__provides__ = ProvidesClass(C, IFooFactory)
    >>> [i.getName() for i in C.__provides__]
@@ -701,10 +719,10 @@ collect function to help with this:
    >>> from zope.interface.declarations import InstanceDeclarations
    >>> before = len(InstanceDeclarations)
    >>> class C(object):
-   ...    pass
+   ...     pass
    >>> from zope.interface import Interface
    >>> class I(Interface):
-   ...    pass
+   ...     pass
    >>> c1 = C()
    >>> c2 = C()
    >>> len(InstanceDeclarations) == before
@@ -736,7 +754,7 @@ For example:
 .. doctest::
 
    >>> from zope.interface import Interface
-   >>> from zope.interface import implementsOnly
+   >>> from zope.interface import implementer_only
    >>> class I1(Interface): pass
    ...
    >>> class I2(Interface): pass
@@ -749,12 +767,14 @@ For example:
    ...
    >>> class I5(Interface): pass
    ...
-   >>> class A(object):
-   ...     implements(I1)
-   >>> class B(object): __implemented__ = I2
-   ...
-   >>> class C(A, B):
-   ...     implements(I31)
+   >>> @implementer(I1)
+   ... class A(object):
+   ...     pass
+   >>> class B(object):
+   ...     __implemented__ = I2
+   >>> @implementer(I31)
+   ... class C(A, B):
+   ...     pass
    >>> c = C()
    >>> directlyProvides(c, I4)
    >>> [i.getName() for i in providedBy(c)]
@@ -771,10 +791,12 @@ For example:
    1
    >>> int(providedBy(c).extends(I5))
    0
-   >>> class COnly(A, B):
-   ...     implementsOnly(I31)
-   >>> class D(COnly):
-   ...     implements(I5)
+   >>> @implementer_only(I31)
+   ... class COnly(A, B):
+   ...     pass
+   >>> @implementer(I5)
+   ... class D(COnly):
+   ...     pass
    >>> c = D()
    >>> directlyProvides(c, I4)
    >>> [i.getName() for i in providedBy(c)]
@@ -809,8 +831,9 @@ For example:
    >>> class IFooFactory(Interface): pass
    ...
    >>> @implementer(IFoo)
+   ... @provider(IFooFactory)
    ... class C(object):
-   ...   classProvides(IFooFactory)
+   ...     pass
    >>> [i.getName() for i in C.__providedBy__]
    ['IFooFactory']
    >>> [i.getName() for i in C().__providedBy__]
diff --git a/docs/api/specifications.rst b/docs/api/specifications.rst
index 72bf8f3..2152e26 100644
--- a/docs/api/specifications.rst
+++ b/docs/api/specifications.rst
@@ -55,8 +55,9 @@ Exmples for :meth:`.Specification.providedBy`:
    >>> from zope.interface import *
    >>> class I1(Interface):
    ...     pass
-   >>> class C(object):
-   ...     implements(I1)
+   >>> @implementer(I1)
+   ... class C(object):
+   ...     pass
    >>> c = C()
    >>> class X(object):
    ...     pass
diff --git a/docs/human.rst b/docs/human.rst
index 139c582..6da620b 100644
--- a/docs/human.rst
+++ b/docs/human.rst
@@ -42,9 +42,9 @@ value (just to make things simpler for this example):
 
 .. doctest::
 
-  >>> class File(object):
+  >>> @zope.interface.implementer(IFile)
+  ... class File(object):
   ...
-  ...      zope.interface.implements(IFile)
   ...      body = 'foo bar'
   ...
 
@@ -64,9 +64,9 @@ use a specific argument name, such as ``file``:
 
 .. doctest::
 
-  >>> class FileSize(object):
+  >>> @zope.interface.implementer(ISize)
+  ... class FileSize(object):
   ...
-  ...      zope.interface.implements(ISize)
   ...      __used_for__ = IFile
   ...
   ...      def __init__(self, context):
diff --git a/docs/verify.rst b/docs/verify.rst
index 0ae7fdf..4d5191e 100644
--- a/docs/verify.rst
+++ b/docs/verify.rst
@@ -36,14 +36,14 @@ Attributes of the object, be they defined by its class or added by its
 
 .. doctest::
 
-   >>> from zope.interface import Interface, Attribute, implements
+   >>> from zope.interface import Interface, Attribute, implementer
    >>> from zope.interface.exceptions import BrokenImplementation
    >>> class IFoo(Interface):
    ...     x = Attribute("The X attribute")
    ...     y = Attribute("The Y attribute")
 
-   >>> class Foo(object):
-   ...     implements(IFoo)
+   >>> @implementer(IFoo)
+   ... class Foo(object):
    ...     x = 1
    ...     def __init__(self):
    ...         self.y = 2
@@ -56,25 +56,25 @@ If either attribute is missing, verification will fail:
 
 .. doctest::
 
-   >>> class Foo(object):
-   ...     implements(IFoo)
+   >>> @implementer(IFoo)
+   ... class Foo(object):
    ...     x = 1
    >>> try: #doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
    ...     verifyObject(IFoo, Foo())
-   ... except BrokenImplementation, e:
-   ...     print str(e)
+   ... except BrokenImplementation as e:
+   ...     print(e)
    An object has failed to implement interface <InterfaceClass ...IFoo>
    <BLANKLINE>
            The y attribute was not provided.
    <BLANKLINE>
-   >>> class Foo(object):
-   ...     implements(IFoo)
+   >>> @implementer(IFoo)
+   ... class Foo(object):
    ...     def __init__(self):
    ...         self.y = 2
    >>> try: #doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
    ...     verifyObject(IFoo, Foo())
-   ... except BrokenImplementation, e:
-   ...     print str(e)
+   ... except BrokenImplementation as e:
+   ...     print(e)
    An object has failed to implement interface <InterfaceClass ...IFoo>
    <BLANKLINE>
            The x attribute was not provided.
@@ -87,15 +87,15 @@ when trying to get its value, the attribute is considered missing:
 
    >>> class IFoo(Interface):
    ...     x = Attribute('The X attribute')
-   >>> class Foo(object):
-   ...     implements(IFoo)
+   >>> @implementer(IFoo)
+   ... class Foo(object):
    ...     @property
    ...     def x(self):
    ...         raise AttributeError
    >>> try: #doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
    ...     verifyObject(IFoo, Foo())
-   ... except BrokenImplementation, e:
-   ...     print str(e)
+   ... except BrokenImplementation as e:
+   ...     print(e)
    An object has failed to implement interface <InterfaceClass ...IFoo>
    <BLANKLINE>
            The x attribute was not provided.
@@ -106,8 +106,8 @@ Any other exception raised by a property will propagate to the caller of
 
 .. doctest::
 
-   >>> class Foo(object):
-   ...     implements(IFoo)
+   >>> @implementer(IFoo)
+   ... class Foo(object):
    ...     @property
    ...     def x(self):
    ...         raise Exception
@@ -120,8 +120,8 @@ any harm:
 
 .. doctest::
 
-   >>> class Foo(object):
-   ...     implements(IFoo)
+   >>> @implementer(IFoo)
+   ... class Foo(object):
    ...     x = 1
    ...     @property
    ...     def y(self):
diff --git a/tox.ini b/tox.ini
index 34c7ca8..941e14c 100644
--- a/tox.ini
+++ b/tox.ini
@@ -43,7 +43,7 @@ parallel_show_output = true
 
 [testenv:docs]
 basepython =
-    python2.7
+    python3
 commands =
     sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html
     sphinx-build -b doctest -d docs/_build/doctrees docs docs/_build/doctest