[Checkins] SVN: zope.interface/branches/tseaver-no_2to3/docs/ Fix up snippets to run in Sphinx context.
Tres Seaver
cvs-admin at zope.org
Fri Apr 6 01:15:11 UTC 2012
Log message for revision 124983:
Fix up snippets to run in Sphinx context.
Changed:
U zope.interface/branches/tseaver-no_2to3/docs/README.rst
U zope.interface/branches/tseaver-no_2to3/docs/adapter.rst
U zope.interface/branches/tseaver-no_2to3/docs/api.rst
U zope.interface/branches/tseaver-no_2to3/docs/foodforthought.rst
U zope.interface/branches/tseaver-no_2to3/docs/human.rst
U zope.interface/branches/tseaver-no_2to3/docs/verify.rst
-=-
Modified: zope.interface/branches/tseaver-no_2to3/docs/README.rst
===================================================================
--- zope.interface/branches/tseaver-no_2to3/docs/README.rst 2012-04-06 01:15:03 UTC (rev 124982)
+++ zope.interface/branches/tseaver-no_2to3/docs/README.rst 2012-04-06 01:15:07 UTC (rev 124983)
@@ -21,8 +21,10 @@
Defining interfaces
===================
-Interfaces are defined using Python class statements::
+Interfaces are defined using Python class statements:
+.. doctest::
+
>>> import zope.interface
>>> class IFoo(zope.interface.Interface):
... """Foo blah blah"""
@@ -36,25 +38,33 @@
subclassed `zope.interface.Interface`, which is an ancestor interface for
all interfaces, much as `object` is an ancestor of all new-style
classes [#create]_. The interface is not a class, it's an Interface,
-an instance of `InterfaceClass`::
+an instance of `InterfaceClass`:
+.. doctest::
+
>>> type(IFoo)
<class 'zope.interface.interface.InterfaceClass'>
-We can ask for the interface's documentation::
+We can ask for the interface's documentation:
+.. doctest::
+
>>> IFoo.__doc__
'Foo blah blah'
-and its name::
+and its name:
+.. doctest::
+
>>> IFoo.__name__
'IFoo'
-and even its module::
+and even its module:
+.. doctest::
+
>>> IFoo.__module__
- '__main__'
+ '__builtin__'
The interface defined two attributes:
@@ -78,8 +88,10 @@
methods that are not instance methods.
You can access the attributes defined by an interface using mapping
-syntax::
+syntax:
+.. doctest::
+
>>> x = IFoo['x']
>>> type(x)
<class 'zope.interface.interface.Attribute'>
@@ -93,28 +105,36 @@
>>> IFoo.get('y')
-You can use `in` to determine if an interface defines a name::
+You can use `in` to determine if an interface defines a name:
+.. doctest::
+
>>> 'x' in IFoo
True
-You can iterate over interfaces to get the names they define::
+You can iterate over interfaces to get the names they define:
+.. doctest::
+
>>> names = list(IFoo)
>>> names.sort()
>>> names
['bar', 'x']
Remember that interfaces aren't classes. You can't access attribute
-definitions as attributes of interfaces::
+definitions as attributes of interfaces:
+.. doctest::
+
>>> IFoo.x
Traceback (most recent call last):
File "<stdin>", line 1, in ?
AttributeError: 'InterfaceClass' object has no attribute 'x'
-Methods provide access to the method signature::
+Methods provide access to the method signature:
+.. doctest::
+
>>> bar = IFoo['bar']
>>> bar.getSignatureString()
'(q, r=None)'
@@ -156,8 +176,10 @@
--------------------------------
The most common way to declare interfaces is using the implements
-function in a class statement::
+function in a class statement:
+.. doctest::
+
>>> class Foo:
... zope.interface.implements(IFoo)
...
@@ -174,30 +196,40 @@
In this example, we declared that `Foo` implements `IFoo`. This means
that instances of `Foo` provide `IFoo`. Having made this declaration,
there are several ways we can introspect the declarations. First, we
-can ask an interface whether it is implemented by a class::
+can ask an interface whether it is implemented by a class:
+.. doctest::
+
>>> IFoo.implementedBy(Foo)
True
-And we can ask whether an interface is provided by an object::
+And we can ask whether an interface is provided by an object:
+.. doctest::
+
>>> foo = Foo()
>>> IFoo.providedBy(foo)
True
-Of course, `Foo` doesn't provide `IFoo`, it implements it::
+Of course, `Foo` doesn't provide `IFoo`, it implements it:
+.. doctest::
+
>>> IFoo.providedBy(Foo)
False
-We can also ask what interfaces are implemented by an object::
+We can also ask what interfaces are implemented by an object:
+.. doctest::
+
>>> list(zope.interface.implementedBy(Foo))
- [<InterfaceClass __main__.IFoo>]
+ [<InterfaceClass __builtin__.IFoo>]
It's an error to ask for interfaces implemented by a non-callable
-object::
+object:
+.. doctest::
+
>>> IFoo.implementedBy(foo)
Traceback (most recent call last):
...
@@ -208,17 +240,21 @@
...
TypeError: ('ImplementedBy called for non-factory', Foo(None))
-Similarly, we can ask what interfaces are provided by an object::
+Similarly, we can ask what interfaces are provided by an object:
+.. doctest::
+
>>> list(zope.interface.providedBy(foo))
- [<InterfaceClass __main__.IFoo>]
+ [<InterfaceClass __builtin__.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::
+`implementer`. In versions of Python before 2.4, this looks like:
+.. doctest::
+
>>> def yfoo(y):
... foo = Foo()
... foo.y = y
@@ -226,14 +262,16 @@
>>> yfoo = zope.interface.implementer(IFoo)(yfoo)
>>> list(zope.interface.implementedBy(yfoo))
- [<InterfaceClass __main__.IFoo>]
+ [<InterfaceClass __builtin__.IFoo>]
Note that the implementer decorator may modify it's argument. Callers
should not assume that a new object is created.
Using implementer also works on callable objects. This is used by
-zope.formlib, as an example::
+zope.formlib, as an example:
+.. doctest::
+
>>> class yfactory:
... def __call__(self, y):
... foo = Foo()
@@ -243,16 +281,18 @@
>>> yfoo = zope.interface.implementer(IFoo)(yfoo)
>>> list(zope.interface.implementedBy(yfoo))
- [<InterfaceClass __main__.IFoo>]
+ [<InterfaceClass __builtin__.IFoo>]
XXX: Double check and update these version numbers:
In zope.interface 3.5.2 and lower, the implementer decorator can not
-be used for classes, but in 3.6.0 and higher it can::
+be used for classes, but in 3.6.0 and higher it can:
+.. doctest::
+
>>> Foo = zope.interface.implementer(IFoo)(Foo)
>>> list(zope.interface.providedBy(Foo()))
- [<InterfaceClass __main__.IFoo>]
+ [<InterfaceClass __builtin__.IFoo>]
Note that class decorators using the @implementer(IFoo) syntax are only
supported in Python 2.6 and later.
@@ -265,8 +305,10 @@
we want to document what the `__init__` method of the `Foo` class
does. It's not *really* part of `IFoo`. You wouldn't normally call
the `__init__` method on Foo instances. Rather, the `__init__` method
-is part of the `Foo`'s `__call__` method::
+is part of the `Foo`'s `__call__` method:
+.. doctest::
+
>>> class IFooFactory(zope.interface.Interface):
... """Create foos"""
...
@@ -277,21 +319,27 @@
... """
It's the class that provides this interface, so we declare the
-interface on the class::
+interface on the class:
+.. doctest::
+
>>> zope.interface.directlyProvides(Foo, IFooFactory)
-And then, we'll see that Foo provides some interfaces::
+And then, we'll see that Foo provides some interfaces:
+.. doctest::
+
>>> list(zope.interface.providedBy(Foo))
- [<InterfaceClass __main__.IFooFactory>]
+ [<InterfaceClass __builtin__.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::
+declaration from within a class statement:
+.. doctest::
+
>>> class Foo2:
... zope.interface.implements(IFoo)
... zope.interface.classProvides(IFooFactory)
@@ -306,7 +354,7 @@
... return "Foo(%s)" % self.x
>>> list(zope.interface.providedBy(Foo2))
- [<InterfaceClass __main__.IFooFactory>]
+ [<InterfaceClass __builtin__.IFooFactory>]
>>> IFooFactory.providedBy(Foo2)
True
@@ -317,16 +365,20 @@
Sometimes, we want to declare interfaces on instances, even though
those instances get interfaces from their classes. Suppose we create
-a new interface, `ISpecial`::
+a new interface, `ISpecial`:
+.. doctest::
+
>>> class ISpecial(zope.interface.Interface):
... reason = zope.interface.Attribute("Reason why we're special")
... def brag():
... "Brag about being special"
We can make an existing foo instance special by providing `reason`
-and `brag` attributes::
+and `brag` attributes:
+.. doctest::
+
>>> foo.reason = 'I just am'
>>> def brag():
... return "I'm special!"
@@ -336,21 +388,27 @@
>>> foo.brag()
"I'm special!"
-and by declaring the interface::
+and by declaring the interface:
+.. doctest::
+
>>> zope.interface.directlyProvides(foo, ISpecial)
-then the new interface is included in the provided interfaces::
+then the new interface is included in the provided interfaces:
+.. doctest::
+
>>> ISpecial.providedBy(foo)
True
>>> list(zope.interface.providedBy(foo))
- [<InterfaceClass __main__.ISpecial>, <InterfaceClass __main__.IFoo>]
+ [<InterfaceClass __builtin__.ISpecial>, <InterfaceClass __builtin__.IFoo>]
-We can find out what interfaces are directly provided by an object::
+We can find out what interfaces are directly provided by an object:
+.. doctest::
+
>>> list(zope.interface.directlyProvidedBy(foo))
- [<InterfaceClass __main__.ISpecial>]
+ [<InterfaceClass __builtin__.ISpecial>]
>>> newfoo = Foo()
>>> list(zope.interface.directlyProvidedBy(newfoo))
@@ -359,8 +417,10 @@
Inherited declarations
----------------------
-Normally, declarations are inherited::
+Normally, declarations are inherited:
+.. doctest::
+
>>> class SpecialFoo(Foo):
... zope.interface.implements(ISpecial)
... reason = 'I just am'
@@ -368,14 +428,16 @@
... return "I'm special because %s" % self.reason
>>> list(zope.interface.implementedBy(SpecialFoo))
- [<InterfaceClass __main__.ISpecial>, <InterfaceClass __main__.IFoo>]
+ [<InterfaceClass __builtin__.ISpecial>, <InterfaceClass __builtin__.IFoo>]
>>> list(zope.interface.providedBy(SpecialFoo()))
- [<InterfaceClass __main__.ISpecial>, <InterfaceClass __main__.IFoo>]
+ [<InterfaceClass __builtin__.ISpecial>, <InterfaceClass __builtin__.IFoo>]
Sometimes, you don't want to inherit declarations. In that case, you
-can use `implementsOnly`, instead of `implements`::
+can use `implementsOnly`, instead of `implements`:
+.. doctest::
+
>>> class Special(Foo):
... zope.interface.implementsOnly(ISpecial)
... reason = 'I just am'
@@ -383,10 +445,10 @@
... return "I'm special because %s" % self.reason
>>> list(zope.interface.implementedBy(Special))
- [<InterfaceClass __main__.ISpecial>]
+ [<InterfaceClass __builtin__.ISpecial>]
>>> list(zope.interface.providedBy(Special()))
- [<InterfaceClass __main__.ISpecial>]
+ [<InterfaceClass __builtin__.ISpecial>]
External declarations
---------------------
@@ -395,23 +457,27 @@
definition. Sometimes, we may want to make declarations from outside
the class definition. For example, we might want to declare interfaces
for classes that we didn't write. The function `classImplements` can
-be used for this purpose::
+be used for this purpose:
+.. doctest::
+
>>> class C:
... pass
>>> zope.interface.classImplements(C, IFoo)
>>> list(zope.interface.implementedBy(C))
- [<InterfaceClass __main__.IFoo>]
+ [<InterfaceClass __builtin__.IFoo>]
-We can use `classImplementsOnly` to exclude inherited interfaces::
+We can use `classImplementsOnly` to exclude inherited interfaces:
+.. doctest::
+
>>> class C(Foo):
... pass
>>> zope.interface.classImplementsOnly(C, ISpecial)
>>> list(zope.interface.implementedBy(C))
- [<InterfaceClass __main__.ISpecial>]
+ [<InterfaceClass __builtin__.ISpecial>]
@@ -419,16 +485,20 @@
-------------------
When we declare interfaces, we create *declaration* objects. When we
-query declarations, declaration objects are returned::
+query declarations, declaration objects are returned:
+.. doctest::
+
>>> type(zope.interface.implementedBy(Special))
<class 'zope.interface.declarations.Implements'>
Declaration objects and interface objects are similar in many ways. In
fact, they share a common base class. The important thing to realize
about them is that they can be used where interfaces are expected in
-declarations. Here's a silly example::
+declarations. Here's a silly example:
+.. doctest::
+
>>> class Special2(Foo):
... zope.interface.implementsOnly(
... zope.interface.implementedBy(Foo),
@@ -440,18 +510,22 @@
The declaration here is almost the same as
``zope.interface.implements(ISpecial)``, except that the order of
-interfaces in the resulting declaration is different::
+interfaces in the resulting declaration is different:
+.. doctest::
+
>>> list(zope.interface.implementedBy(Special2))
- [<InterfaceClass __main__.IFoo>, <InterfaceClass __main__.ISpecial>]
+ [<InterfaceClass __builtin__.IFoo>, <InterfaceClass __builtin__.ISpecial>]
Interface Inheritance
=====================
Interfaces can extend other interfaces. They do this simply by listing
-the other interfaces as base interfaces::
+the other interfaces as base interfaces:
+.. doctest::
+
>>> class IBlat(zope.interface.Interface):
... """Blat blah blah"""
...
@@ -469,15 +543,17 @@
...
>>> IBaz.__bases__
- (<InterfaceClass __main__.IFoo>, <InterfaceClass __main__.IBlat>)
+ (<InterfaceClass __builtin__.IFoo>, <InterfaceClass __builtin__.IBlat>)
>>> names = list(IBaz)
>>> names.sort()
>>> names
['bar', 'eek', 'x', 'y']
-Note that `IBaz` overrides eek::
+Note that `IBaz` overrides eek:
+.. doctest::
+
>>> IBlat['eek'].__doc__
'eek blah blah'
>>> IBaz['eek'].__doc__
@@ -487,20 +563,26 @@
an interface, the extending interface should be compatible [#compat]_
with the extended interfaces.
-We can ask whether one interface extends another::
+We can ask whether one interface extends another:
+.. doctest::
+
>>> IBaz.extends(IFoo)
True
>>> IBlat.extends(IFoo)
False
-Note that interfaces don't extend themselves::
+Note that interfaces don't extend themselves:
+.. doctest::
+
>>> IBaz.extends(IBaz)
False
-Sometimes we wish they did, but we can, instead use `isOrExtends`::
+Sometimes we wish they did, but we can, instead use `isOrExtends`:
+.. doctest::
+
>>> IBaz.isOrExtends(IBaz)
True
>>> IBaz.isOrExtends(IFoo)
@@ -511,8 +593,10 @@
When we iterate over an interface, we get all of the names it defines,
including names defined by base interfaces. Sometimes, we want *just*
the names defined by the interface directly. We bane use the `names`
-method for that::
+method for that:
+.. doctest::
+
>>> list(IBaz.names())
['eek']
@@ -521,8 +605,10 @@
An interface may override attribute definitions from base interfaces.
If two base interfaces define the same attribute, the attribute is
-inherited from the most specific interface. For example, with::
+inherited from the most specific interface. For example, with:
+.. doctest::
+
>>> class IBase(zope.interface.Interface):
...
... def foo():
@@ -540,8 +626,10 @@
... pass
ISub's definition of foo is the one from IBase2, since IBase2 is more
-specific that IBase::
+specific that IBase:
+.. doctest::
+
>>> ISub['foo'].__doc__
'base2 foo doc'
@@ -549,8 +637,10 @@
Sometimes, it's useful to ask whether an interface defines an
attribute directly. You can use the direct method to get a directly
-defined definitions::
+defined definitions:
+.. doctest::
+
>>> IBase.direct('foo').__doc__
'base foo doc'
@@ -562,14 +652,16 @@
Interfaces and declarations are both special cases of specifications.
What we described above for interface inheritance applies to both
declarations and specifications. Declarations actually extend the
-interfaces that they declare::
+interfaces that they declare:
+.. doctest::
+
>>> class Baz(object):
... zope.interface.implements(IBaz)
>>> baz_implements = zope.interface.implementedBy(Baz)
>>> baz_implements.__bases__
- (<InterfaceClass __main__.IBaz>, <implementedBy ...object>)
+ (<InterfaceClass __builtin__.IBaz>, <implementedBy ...object>)
>>> baz_implements.extends(IFoo)
True
@@ -580,13 +672,16 @@
True
Specifications (interfaces and declarations) provide an `__sro__`
-that lists the specification and all of it's ancestors::
+that lists the specification and all of it's ancestors:
- >>> baz_implements.__sro__
- (<implementedBy __main__.Baz>,
- <InterfaceClass __main__.IBaz>,
- <InterfaceClass __main__.IFoo>,
- <InterfaceClass __main__.IBlat>,
+.. doctest::
+
+ >>> from pprint import pprint
+ >>> pprint(baz_implements.__sro__)
+ (<implementedBy __builtin__.Baz>,
+ <InterfaceClass __builtin__.IBaz>,
+ <InterfaceClass __builtin__.IFoo>,
+ <InterfaceClass __builtin__.IBlat>,
<InterfaceClass zope.interface.Interface>,
<implementedBy ...object>)
@@ -596,8 +691,10 @@
Interfaces and attribute descriptions support an extension mechanism,
borrowed from UML, called "tagged values" that lets us store extra
-data::
+data:
+.. doctest::
+
>>> IFoo.setTaggedValue('date-modified', '2004-04-01')
>>> IFoo.setTaggedValue('author', 'Jim Fulton')
>>> IFoo.getTaggedValue('date-modified')
@@ -611,18 +708,22 @@
['author', 'date-modified']
Function attributes are converted to tagged values when method
-attribute definitions are created::
+attribute definitions are created:
+.. doctest::
+
>>> class IBazFactory(zope.interface.Interface):
... def __call__():
... "create one"
... __call__.return_type = IBaz
>>> IBazFactory['__call__'].getTaggedValue('return_type')
- <InterfaceClass __main__.IBaz>
+ <InterfaceClass __builtin__.IBaz>
-Tagged values can also be defined from within an interface definition::
+Tagged values can also be defined from within an interface definition:
+.. doctest::
+
>>> class IWithTaggedValues(zope.interface.Interface):
... zope.interface.taggedValue('squish', 'squash')
>>> IWithTaggedValues.getTaggedValue('squish')
@@ -635,8 +736,10 @@
provide them. These conditions are expressed using one or more
invariants. Invariants are callable objects that will be called with
an object that provides an interface. An invariant raises an `Invalid`
-exception if the condition doesn't hold. Here's an example::
+exception if the condition doesn't hold. Here's an example:
+.. doctest::
+
>>> class RangeError(zope.interface.Invalid):
... """A range has invalid limits"""
... def __repr__(self):
@@ -646,16 +749,20 @@
... if ob.max < ob.min:
... raise RangeError(ob)
-Given this invariant, we can use it in an interface definition::
+Given this invariant, we can use it in an interface definition:
+.. doctest::
+
>>> class IRange(zope.interface.Interface):
... min = zope.interface.Attribute("Lower bound")
... max = zope.interface.Attribute("Upper bound")
...
... zope.interface.invariant(range_invariant)
-Interfaces have a method for checking their invariants::
+Interfaces have a method for checking their invariants:
+.. doctest::
+
>>> class Range(object):
... zope.interface.implements(IRange)
...
@@ -675,8 +782,10 @@
If you have multiple invariants, you may not want to stop checking
after the first error. If you pass a list to `validateInvariants`,
then a single `Invalid` exception will be raised with the list of
-exceptions as it's argument::
+exceptions as it's argument:
+.. doctest::
+
>>> from zope.interface.exceptions import Invalid
>>> errors = []
>>> try:
@@ -685,8 +794,10 @@
... str(e)
'[RangeError(Range(2, 1))]'
-And the list will be filled with the individual exceptions::
+And the list will be filled with the individual exceptions:
+.. doctest::
+
>>> errors
[RangeError(Range(2, 1))]
@@ -700,25 +811,31 @@
The semantics are based on those of the PEP 246 adapt function.
-If an object cannot be adapted, then a TypeError is raised::
+If an object cannot be adapted, then a TypeError is raised:
+.. doctest::
+
>>> class I(zope.interface.Interface):
... pass
>>> I(0)
Traceback (most recent call last):
...
- TypeError: ('Could not adapt', 0, <InterfaceClass __main__.I>)
+ TypeError: ('Could not adapt', 0, <InterfaceClass __builtin__.I>)
-unless an alternate value is provided as a second positional argument::
+unless an alternate value is provided as a second positional argument:
+.. doctest::
+
>>> I(0, 'bob')
'bob'
-If an object already implements the interface, then it will be returned::
+If an object already implements the interface, then it will be returned:
+.. doctest::
+
>>> class C(object):
... zope.interface.implements(I)
@@ -726,8 +843,10 @@
>>> I(obj) is obj
True
-If an object implements __conform__, then it will be used::
+If an object implements __conform__, then it will be used:
+.. doctest::
+
>>> class C(object):
... zope.interface.implements(I)
... def __conform__(self, proto):
@@ -736,8 +855,10 @@
>>> I(C())
0
-Adapter hooks (see __adapt__) will also be used, if present::
+Adapter hooks (see __adapt__) will also be used, if present:
+.. doctest::
+
>>> from zope.interface.interface import adapter_hooks
>>> def adapt_0_to_42(iface, obj):
... if obj == 0:
@@ -751,12 +872,12 @@
>>> I(0)
Traceback (most recent call last):
...
- TypeError: ('Could not adapt', 0, <InterfaceClass __main__.I>)
+ TypeError: ('Could not adapt', 0, <InterfaceClass __builtin__.I>)
__adapt__
---------
-::
+.. doctest::
>>> class I(zope.interface.Interface):
... pass
@@ -769,12 +890,16 @@
The adapt method is responsible for adapting an object to the
reciever.
-The default version returns None::
+The default version returns None:
+.. doctest::
+
>>> I.__adapt__(0)
-unless the object given provides the interface::
+unless the object given provides the interface:
+.. doctest::
+
>>> class C(object):
... zope.interface.implements(I)
@@ -785,8 +910,10 @@
Adapter hooks can be provided (or removed) to provide custom
adaptation. We'll install a silly hook that adapts 0 to 42.
We install a hook by simply adding it to the adapter_hooks
-list::
+list:
+.. doctest::
+
>>> from zope.interface.interface import adapter_hooks
>>> def adapt_0_to_42(iface, obj):
... if obj == 0:
@@ -799,8 +926,10 @@
Hooks must either return an adapter, or None if no adapter can
be found.
-Hooks can be uninstalled by removing them from the list::
+Hooks can be uninstalled by removing them from the list:
+.. doctest::
+
>>> adapter_hooks.remove(adapt_0_to_42)
>>> I.__adapt__(0)
Modified: zope.interface/branches/tseaver-no_2to3/docs/adapter.rst
===================================================================
--- zope.interface/branches/tseaver-no_2to3/docs/adapter.rst 2012-04-06 01:15:03 UTC (rev 124982)
+++ zope.interface/branches/tseaver-no_2to3/docs/adapter.rst 2012-04-06 01:15:07 UTC (rev 124983)
@@ -15,8 +15,10 @@
Single Adapters
===============
-Let's look at a simple example, using a single required specification::
+Let's look at a simple example, using a single required specification:
+.. doctest::
+
>>> from zope.interface.adapter import AdapterRegistry
>>> import zope.interface
@@ -29,12 +31,16 @@
>>> registry = AdapterRegistry()
-We'll register an object that depends on IR1 and "provides" IP2::
+We'll register an object that depends on IR1 and "provides" IP2:
+.. doctest::
+
>>> registry.register([IR1], IP2, '', 12)
-Given the registration, we can look it up again::
+Given the registration, we can look it up again:
+.. doctest::
+
>>> registry.lookup([IR1], IP2, '')
12
@@ -46,15 +52,19 @@
previously-registered value.
If an object depends on a specification, it can be looked up with a
-specification that extends the specification that it depends on::
+specification that extends the specification that it depends on:
+.. doctest::
+
>>> class IR2(IR1):
... pass
>>> registry.lookup([IR2], IP2, '')
12
-We can use a class implementation specification to look up the object::
+We can use a class implementation specification to look up the object:
+.. doctest::
+
>>> class C2:
... zope.interface.implements(IR2)
@@ -63,54 +73,72 @@
and it can be looked up for interfaces that its provided interface
-extends::
+extends:
+.. doctest::
+
>>> registry.lookup([IR1], IP1, '')
12
>>> registry.lookup([IR2], IP1, '')
12
But if you require a specification that doesn't extend the specification the
-object depends on, you won't get anything::
+object depends on, you won't get anything:
+.. doctest::
+
>>> registry.lookup([zope.interface.Interface], IP1, '')
-By the way, you can pass a default value to lookup::
+By the way, you can pass a default value to lookup:
+.. doctest::
+
>>> registry.lookup([zope.interface.Interface], IP1, '', 42)
42
If you try to get an interface the object doesn't provide, you also
-won't get anything::
+won't get anything:
+.. doctest::
+
>>> class IP3(IP2):
... pass
>>> registry.lookup([IR1], IP3, '')
-You also won't get anything if you use the wrong name::
+You also won't get anything if you use the wrong name:
+.. doctest::
+
>>> registry.lookup([IR1], IP1, 'bob')
>>> registry.register([IR1], IP2, 'bob', "Bob's 12")
>>> registry.lookup([IR1], IP1, 'bob')
"Bob's 12"
-You can leave the name off when doing a lookup::
+You can leave the name off when doing a lookup:
+.. doctest::
+
>>> registry.lookup([IR1], IP1)
12
-If we register an object that provides IP1::
+If we register an object that provides IP1:
+.. doctest::
+
>>> registry.register([IR1], IP1, '', 11)
-then that object will be prefered over O(12)::
+then that object will be prefered over O(12):
+.. doctest::
+
>>> registry.lookup([IR1], IP1, '')
11
Also, if we register an object for IR2, then that will be prefered
-when using IR2::
+when using IR2:
+.. doctest::
+
>>> registry.register([IR2], IP1, '', 21)
>>> registry.lookup([IR2], IP1, '')
21
@@ -120,8 +148,10 @@
We can ask if there is an adapter registered for a collection of
interfaces. This is different than lookup, because it looks for an
-exact match::
+exact match:
+.. doctest::
+
>>> print registry.registered([IR1], IP1)
11
@@ -145,8 +175,10 @@
-------
Lookup of single adapters is common enough that there is a specialized
-version of lookup that takes a single required interface::
+version of lookup that takes a single required interface:
+.. doctest::
+
>>> registry.lookup1(IR2, IP1, '')
21
>>> registry.lookup1(IR2, IP1)
@@ -159,8 +191,10 @@
object that implements an interface is adapted to another object that
supports a different interface. The adapter registry supports the
computation of adapters. In this case, we have to register adapter
-factories::
+factories:
+.. doctest::
+
>>> class IR(zope.interface.Interface):
... pass
@@ -175,8 +209,10 @@
>>> registry.register([IR], IP1, '', Y)
In this case, we registered a class as the factory. Now we can call
-`queryAdapter` to get the adapted object::
+`queryAdapter` to get the adapted object:
+.. doctest::
+
>>> x = X()
>>> y = registry.queryAdapter(x, IP1)
>>> y.__class__.__name__
@@ -184,8 +220,10 @@
>>> y.context is x
True
-We can register and lookup by name too::
+We can register and lookup by name too:
+.. doctest::
+
>>> class Y2(Y):
... pass
@@ -199,8 +237,10 @@
When the adapter factory produces `None`, then this is treated as if no
adapter has been found. This allows us to prevent adaptation (when desired)
and let the adapter factory determine whether adaptation is possible based on
-the state of the object being adapted::
+the state of the object being adapted:
+.. doctest::
+
>>> def factory(context):
... if context.name == 'object':
... return 'adapter'
@@ -221,8 +261,10 @@
'default'
An alternate method that provides the same function as `queryAdapter()` is
-`adapter_hook()`::
+`adapter_hook()`:
+.. doctest::
+
>>> y = registry.adapter_hook(IP1, x)
>>> y.__class__.__name__
'Y'
@@ -243,20 +285,26 @@
----------------
Sometimes, you want to provide an adapter that will adapt anything.
-For that, provide None as the required interface::
+For that, provide None as the required interface:
+.. doctest::
+
>>> registry.register([None], IP1, '', 1)
then we can use that adapter for interfaces we don't have specific
-adapters for::
+adapters for:
+.. doctest::
+
>>> class IQ(zope.interface.Interface):
... pass
>>> registry.lookup([IQ], IP1, '')
1
-Of course, specific adapters are still used when applicable::
+Of course, specific adapters are still used when applicable:
+.. doctest::
+
>>> registry.lookup([IR2], IP1, '')
21
@@ -264,8 +312,10 @@
--------------
You can register adapters for class declarations, which is almost the
-same as registering them for a class::
+same as registering them for a class:
+.. doctest::
+
>>> registry.register([zope.interface.implementedBy(C2)], IP1, '', 'C21')
>>> registry.lookup([zope.interface.implementedBy(C2)], IP1, '')
'C21'
@@ -274,8 +324,10 @@
-------------
At some point it was impossible to register dictionary-based adapters due a
-bug. Let's make sure this works now::
+bug. Let's make sure this works now:
+.. doctest::
+
>>> adapter = {}
>>> registry.register((), IQ, '', adapter)
>>> registry.lookup((), IQ, '') is adapter
@@ -284,8 +336,10 @@
Unregistering
-------------
-You can unregister by registering None, rather than an object::
+You can unregister by registering None, rather than an object:
+.. doctest::
+
>>> registry.register([zope.interface.implementedBy(C2)], IP1, '', None)
>>> registry.lookup([zope.interface.implementedBy(C2)], IP1, '')
21
@@ -297,8 +351,10 @@
Multi-adapters
==============
-You can adapt multiple specifications::
+You can adapt multiple specifications:
+.. doctest::
+
>>> registry.register([IR1, IQ], IP2, '', '1q2')
>>> registry.lookup([IR1, IQ], IP2, '')
'1q2'
@@ -322,13 +378,17 @@
Multi-adaptation
----------------
-You can adapt multiple objects::
+You can adapt multiple objects:
+.. doctest::
+
>>> class Q:
... zope.interface.implements(IQ)
-As with single adapters, we register a factory, which is often a class::
+As with single adapters, we register a factory, which is often a class:
+.. doctest::
+
>>> class IM(zope.interface.Interface):
... pass
>>> class M:
@@ -337,8 +397,10 @@
... self.x, self.q = x, q
>>> registry.register([IR, IQ], IM, '', M)
-And then we can call `queryMultiAdapter` to compute an adapter::
+And then we can call `queryMultiAdapter` to compute an adapter:
+.. doctest::
+
>>> q = Q()
>>> m = registry.queryMultiAdapter((x, q), IM)
>>> m.__class__.__name__
@@ -346,8 +408,10 @@
>>> m.x is x and m.q is q
True
-and, of course, we can use names::
+and, of course, we can use names:
+.. doctest::
+
>>> class M2(M):
... pass
>>> registry.register([IR, IQ], IM, 'bob', M2)
@@ -361,8 +425,10 @@
----------------
As with single adapters, you can define default adapters by specifying
-None for the *first* specification::
+None for the *first* specification:
+.. doctest::
+
>>> registry.register([None, IQ], IP2, '', 'q2')
>>> registry.lookup([IS, IQ], IP2, '')
'q2'
@@ -370,8 +436,10 @@
Null Adapters
=============
-You can also adapt no specification::
+You can also adapt no specification:
+.. doctest::
+
>>> registry.register([], IP2, '', 2)
>>> registry.lookup([], IP2, '')
2
@@ -382,21 +450,27 @@
----------------------
Adapters are named. Sometimes, it's useful to get all of the named
-adapters for given interfaces::
+adapters for given interfaces:
+.. doctest::
+
>>> adapters = list(registry.lookupAll([IR1], IP1))
>>> adapters.sort()
>>> assert adapters == [(u'', 11), (u'bob', "Bob's 12")]
-This works for multi-adapters too::
+This works for multi-adapters too:
+.. doctest::
+
>>> registry.register([IR1, IQ2], IP2, 'bob', '1q2 for bob')
>>> adapters = list(registry.lookupAll([IR2, IQ2], IP1))
>>> adapters.sort()
>>> assert adapters == [(u'', '1q22'), (u'bob', '1q2 for bob')]
-And even null adapters::
+And even null adapters:
+.. doctest::
+
>>> registry.register([], IP2, 'bob', 3)
>>> adapters = list(registry.lookupAll([], IP1))
>>> adapters.sort()
@@ -409,16 +483,20 @@
specification. Sometimes, we want to get all of the objects that
match some specification. We use subscriptions for this. We
subscribe objects against specifications and then later find all of
-the subscribed objects::
+the subscribed objects:
+.. doctest::
+
>>> registry.subscribe([IR1], IP2, 'sub12 1')
>>> registry.subscriptions([IR1], IP2)
['sub12 1']
Note that, unlike regular adapters, subscriptions are unnamed.
-You can have multiple subscribers for the same specification::
+You can have multiple subscribers for the same specification:
+.. doctest::
+
>>> registry.subscribe([IR1], IP2, 'sub12 2')
>>> registry.subscriptions([IR1], IP2)
['sub12 1', 'sub12 2']
@@ -426,8 +504,10 @@
If subscribers are registered for the same required interfaces, they
are returned in the order of definition.
-You can register subscribers for all specifications using None::
+You can register subscribers for all specifications using None:
+.. doctest::
+
>>> registry.subscribe([None], IP1, 'sub_1')
>>> registry.subscriptions([IR2], IP1)
['sub_1', 'sub12 1', 'sub12 2']
@@ -436,8 +516,10 @@
for less general required interfaces are returned before subscribers
for more general interfaces.
-Subscriptions may be combined over multiple compatible specifications::
+Subscriptions may be combined over multiple compatible specifications:
+.. doctest::
+
>>> registry.subscriptions([IR2], IP1)
['sub_1', 'sub12 1', 'sub12 2']
>>> registry.subscribe([IR1], IP1, 'sub11')
@@ -449,22 +531,28 @@
>>> registry.subscriptions([IR2], IP2)
['sub12 1', 'sub12 2', 'sub22']
-Subscriptions can be on multiple specifications::
+Subscriptions can be on multiple specifications:
+.. doctest::
+
>>> registry.subscribe([IR1, IQ], IP2, 'sub1q2')
>>> registry.subscriptions([IR1, IQ], IP2)
['sub1q2']
As with single subscriptions and non-subscription adapters, you can
-specify None for the first required interface, to specify a default::
+specify None for the first required interface, to specify a default:
+.. doctest::
+
>>> registry.subscribe([None, IQ], IP2, 'sub_q2')
>>> registry.subscriptions([IS, IQ], IP2)
['sub_q2']
>>> registry.subscriptions([IR1, IQ], IP2)
['sub_q2', 'sub1q2']
-You can have subscriptions that are indepenent of any specifications::
+You can have subscriptions that are indepenent of any specifications:
+
+.. doctest::
>>> list(registry.subscriptions([], IP1))
[]
@@ -482,15 +570,19 @@
-------------------------
We can unregister subscribers. When unregistering a subscriber, we
-can unregister a specific subscriber::
+can unregister a specific subscriber:
+.. doctest::
+
>>> registry.unsubscribe([IR1], IP1, 'sub11')
>>> registry.subscriptions([IR1], IP1)
['sub_1', 'sub12 1', 'sub12 2']
If we don't specify a value, then all subscribers matching the given
-interfaces will be unsubscribed::
+interfaces will be unsubscribed:
+.. doctest::
+
>>> registry.unsubscribe([IR1], IP2)
>>> registry.subscriptions([IR1], IP1)
['sub_1']
@@ -501,8 +593,10 @@
We normally register adapter factories, which then allow us to compute
adapters, but with subscriptions, we get multiple adapters. Here's an
-example of multiple-object subscribers::
+example of multiple-object subscribers:
+.. doctest::
+
>>> registry.subscribe([IR, IQ], IM, M)
>>> registry.subscribe([IR, IQ], IM, M2)
@@ -516,8 +610,10 @@
>>> [(s.x is x and s.q is q) for s in subscribers]
[True, True]
-adapter factory subcribers can't return None values::
+adapter factory subcribers can't return None values:
+.. doctest::
+
>>> def M3(x, y):
... return None
@@ -533,8 +629,10 @@
output. It returns None. A handler is unlike adapters in that it does
all of its work when the factory is called.
-To register a handler, simply provide None as the provided interface::
+To register a handler, simply provide None as the provided interface:
+.. doctest::
+
>>> def handler(event):
... print 'handler', event
Modified: zope.interface/branches/tseaver-no_2to3/docs/api.rst
===================================================================
--- zope.interface/branches/tseaver-no_2to3/docs/api.rst 2012-04-06 01:15:03 UTC (rev 124982)
+++ zope.interface/branches/tseaver-no_2to3/docs/api.rst 2012-04-06 01:15:07 UTC (rev 124983)
@@ -19,8 +19,11 @@
Usage
+++++
-For example::
+For example:
+.. doctest::
+
+ >>> from zope.interface.interface import Specification
>>> from zope.interface import Interface
>>> class I1(Interface):
... pass
@@ -33,15 +36,17 @@
>>> [i.__name__ for i in I2.__bases__]
['I1']
>>> I3.extends(I1)
- 1
+ True
>>> I2.__bases__ = (Interface, )
>>> [i.__name__ for i in I2.__bases__]
['Interface']
>>> I3.extends(I1)
- 0
+ False
-Exmples for :meth:`Specification.providedBy`::
+Exmples for :meth:`Specification.providedBy`:
+.. doctest::
+
>>> from zope.interface import *
>>> class I1(Interface):
... pass
@@ -64,8 +69,10 @@
>>> I1.providedBy(C)
True
-Examples for :meth:`Specification.isOrExtends`::
+Examples for :meth:`Specification.isOrExtends`:
+.. doctest::
+
>>> from zope.interface import Interface
>>> from zope.interface.declarations import Declaration
>>> class I1(Interface): pass
@@ -91,8 +98,10 @@
>>> int(spec.extends(I4))
0
-Examples for :meth:`Specification.interfaces`::
+Examples for :meth:`Specification.interfaces`:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -110,8 +119,10 @@
>>> list(i)
[]
-Exmples for :meth:`Specification.extends`::
+Exmples for :meth:`Specification.extends`:
+.. doctest::
+
>>> from zope.interface import Interface
>>> from zope.interface.declarations import Declaration
>>> class I1(Interface): pass
@@ -137,11 +148,11 @@
>>> int(spec.extends(I4))
0
>>> I2.extends(I2)
- 0
+ False
>>> I2.extends(I2, False)
- 1
+ True
>>> I2.extends(I2, strict=False)
- 1
+ True
:class:`zope.interface.interface.InterfaceClass`
@@ -161,8 +172,10 @@
Usage
+++++
-Exmples for :meth:`InterfaceClass.extends`::
+Exmples for :meth:`InterfaceClass.extends`:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -191,8 +204,10 @@
Usage
+++++
-Exmples for :meth:`Declaration.__contains__`::
+Exmples for :meth:`Declaration.__contains__`:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -213,8 +228,10 @@
>>> int(I4 in spec)
1
-Exmples for :meth:`Declaration.__iter__`::
+Exmples for :meth:`Declaration.__iter__`:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -232,8 +249,10 @@
>>> list(i)
[]
-Exmples for :meth:`Declaration.flattened`::
+Exmples for :meth:`Declaration.flattened`:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -251,8 +270,10 @@
>>> list(i)
[]
-Exmples for :meth:`Declaration.__sub__`::
+Exmples for :meth:`Declaration.__sub__`:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -282,8 +303,10 @@
... in spec - Declaration(I3, I4)]
['I2']
-Exmples for :meth:`Declaration.__add__`::
+Exmples for :meth:`Declaration.__add__`:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -327,8 +350,10 @@
Usage
+++++
-Consider the following example::
+Consider the following example:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -351,8 +376,10 @@
Instances of ``C`` provide only ``I1``, ``I2``, and regardless of
whatever interfaces instances of ``A`` and ``B`` implement.
-Another example::
+Another example:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -370,13 +397,15 @@
['I3', 'I2']
Really, any object should be able to receive a successful answer, even
-an instance::
+an instance:
+.. doctest::
+
>>> class Callable(object):
... def __call__(self):
... return self
>>> implementedBy(Callable())
- <implementedBy zope.interface.declarations.?>
+ <implementedBy __builtin__.?>
Note that the name of the spec ends with a '?', because the `Callable`
instance does not have a `__name__` attribute.
@@ -396,8 +425,10 @@
Usage
+++++
-Consider the following example::
+Consider the following example:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -433,8 +464,10 @@
Usage
+++++
-Consider the following example::
+Consider the following example:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -464,7 +497,7 @@
:class:`zope.interface.declarations.implementer`
------------------------------------------------
+------------------------------------------------
API
+++
@@ -475,7 +508,7 @@
:class:`zope.interface.declarations.implementer_only`
-----------------------------------------------------
+-----------------------------------------------------
API
+++
@@ -519,13 +552,16 @@
Usage
+++++
-Descriptor semantics (via ``Provides.__get__``)::
+Descriptor semantics (via ``Provides.__get__``):
+.. doctest::
+
>>> from zope.interface import Interface
>>> class IFooFactory(Interface): pass
...
>>> class C(object):
... pass
+ >>> from zope.interface.declarations import ProvidesClass
>>> C.__provides__ = ProvidesClass(C, IFooFactory)
>>> [i.getName() for i in C.__provides__]
['IFooFactory']
@@ -551,13 +587,16 @@
meaningful, we need to force garbage collection to make sure garbage
objects are, indeed, removed from the system. Depending on how Python
is run, we may need to make multiple calls to be sure. We provide a
-collect function to help with this::
+collect function to help with this:
+.. doctest::
+
>>> import gc
>>> def collect():
... for i in range(4):
... gc.collect()
>>> collect()
+ >>> from zope.interface.declarations import InstanceDeclarations
>>> before = len(InstanceDeclarations)
>>> class C(object):
... pass
@@ -567,21 +606,21 @@
>>> c1 = C()
>>> c2 = C()
>>> len(InstanceDeclarations) == before
- 1
+ True
>>> directlyProvides(c1, I)
>>> len(InstanceDeclarations) == before + 1
- 1
+ True
>>> directlyProvides(c2, I)
>>> len(InstanceDeclarations) == before + 1
- 1
+ True
>>> del c1
>>> collect()
>>> len(InstanceDeclarations) == before + 1
- 1
+ True
>>> del c2
>>> collect()
>>> len(InstanceDeclarations) == before
- 1
+ True
:func:`zope.interface.declarations.directlyProvides`
@@ -596,8 +635,10 @@
Usage
+++++
-Consider the following example::
+Consider the following example:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -636,8 +677,10 @@
instances have been declared for instances of ``C``.
To remove directly provided interfaces, use ``directlyProvidedBy`` and
-subtract the unwanted interfaces. For example::
+subtract the unwanted interfaces. For example:
+.. doctest::
+
>>> directlyProvides(ob, directlyProvidedBy(ob)-I2)
>>> int(I1 in providedBy(ob))
1
@@ -649,14 +692,18 @@
provide ``I2`` if it's class implements ``I2``.
To add directly provided interfaces, use ``directlyProvidedBy`` and
-include additional interfaces. For example::
+include additional interfaces. For example:
+.. doctest::
+
>>> int(I2 in providedBy(ob))
0
>>> directlyProvides(ob, directlyProvidedBy(ob), I2)
-adds ``I2`` to the interfaces directly provided by ob::
+adds ``I2`` to the interfaces directly provided by ob:
+.. doctest::
+
>>> int(I2 in providedBy(ob))
1
@@ -678,8 +725,10 @@
Usage
+++++
-Consider the following example::
+Consider the following example:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -744,8 +793,10 @@
Usage
+++++
-Consider the following two interfaces::
+Consider the following two interfaces:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -753,8 +804,10 @@
...
``I1`` is provided through the class, ``I2`` is directly provided
-by the object::
+by the object:
+.. doctest::
+
>>> class C(object):
... implements(I1)
>>> c = C()
@@ -762,14 +815,18 @@
>>> I2.providedBy(c)
True
-Remove I2 from c again::
+Remove I2 from c again:
+.. doctest::
+
>>> noLongerProvides(c, I2)
>>> I2.providedBy(c)
False
-Removing an interface that is provided through the class is not possible::
+Removing an interface that is provided through the class is not possible:
+.. doctest::
+
>>> noLongerProvides(c, I1)
Traceback (most recent call last):
...
@@ -797,30 +854,35 @@
Usage
+++++
-For example::
+For example:
+.. doctest::
+
>>> from zope.interface import Interface
+ >>> from zope.interface.declarations import implementer
>>> class IFooFactory(Interface):
... pass
>>> class IFoo(Interface):
... pass
>>> @implementer(IFoo)
- >>> class C(object):
+ ... class C(object):
... classProvides(IFooFactory)
>>> [i.getName() for i in C.__provides__]
['IFooFactory']
>>> [i.getName() for i in C().__provides__]
['IFoo']
-Which is equivalent to::
+Which is equivalent to:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class IFoo(Interface): pass
...
>>> class IFooFactory(Interface): pass
...
>>> @implementer(IFoo)
- >>> class C(object):
+ ... class C(object):
... pass
>>> directlyProvides(C, IFooFactory)
>>> [i.getName() for i in C.__providedBy__]
@@ -862,8 +924,10 @@
Usage
+++++
-For example::
+For example:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@@ -945,15 +1009,17 @@
Usage
+++++
-For example::
+For example:
+.. doctest::
+
>>> from zope.interface import Interface
>>> class IFoo(Interface): pass
...
>>> class IFooFactory(Interface): pass
...
>>> @implementer(IFoo)
- >>> class C(object):
+ ... class C(object):
... classProvides(IFooFactory)
>>> [i.getName() for i in C.__providedBy__]
['IFooFactory']
Modified: zope.interface/branches/tseaver-no_2to3/docs/foodforthought.rst
===================================================================
--- zope.interface/branches/tseaver-no_2to3/docs/foodforthought.rst 2012-04-06 01:15:03 UTC (rev 124982)
+++ zope.interface/branches/tseaver-no_2to3/docs/foodforthought.rst 2012-04-06 01:15:07 UTC (rev 124983)
@@ -3,8 +3,10 @@
================================
-This file gives more subscription examples using a cooking-based example::
+This file gives more subscription examples using a cooking-based example:
+.. doctest::
+
>>> from zope.interface.adapter import AdapterRegistry
>>> registry = AdapterRegistry()
@@ -19,8 +21,10 @@
... pass
Adapting to some other interface for which there is no
-subscription adapter returns an empty sequence::
+subscription adapter returns an empty sequence:
+.. doctest::
+
>>> class IRecipe(zope.interface.Interface):
... pass
>>> class ISausages(IRecipe):
@@ -33,14 +37,18 @@
>>> list(registry.subscriptions([IPoultry], IRecipe))
[]
-unless we define a subscription::
+unless we define a subscription:
+.. doctest::
+
>>> registry.subscribe([IAnimal], ISausages, 'sausages')
>>> list(registry.subscriptions([IPoultry], ISausages))
['sausages']
-And define another subscription adapter::
+And define another subscription adapter:
+.. doctest::
+
>>> registry.subscribe([IPoultry], INoodles, 'noodles')
>>> meals = list(registry.subscriptions([IPoultry], IRecipe))
>>> meals.sort()
@@ -53,8 +61,10 @@
>>> meals
['kfc', 'noodles', 'sausages']
-And the answer for poultry hasn't changed::
+And the answer for poultry hasn't changed:
+.. doctest::
+
>>> meals = list(registry.subscriptions([IPoultry], IRecipe))
>>> meals.sort()
>>> meals
Modified: zope.interface/branches/tseaver-no_2to3/docs/human.rst
===================================================================
--- zope.interface/branches/tseaver-no_2to3/docs/human.rst 2012-04-06 01:15:03 UTC (rev 124982)
+++ zope.interface/branches/tseaver-no_2to3/docs/human.rst 2012-04-06 01:15:07 UTC (rev 124983)
@@ -6,14 +6,18 @@
adapter registry. It is intended to provide a concrete but narrow example on
how to use interfaces and adapters outside of Zope 3.
-First we have to import the interface package::
+First we have to import the interface package:
+.. doctest::
+
>>> import zope.interface
We now develop an interface for our object, which is a simple file in this
case. For now we simply support one attribute, the body, which contains the
-actual file contents::
+actual file contents:
+.. doctest::
+
>>> class IFile(zope.interface.Interface):
...
... body = zope.interface.Attribute('Contents of the file.')
@@ -22,8 +26,10 @@
For statistical reasons we often want to know the size of a file. However, it
would be clumsy to implement the size directly in the file object, since the
size really represents meta-data. Thus we create another interface that
-provides the size of something::
+provides the size of something:
+.. doctest::
+
>>> class ISize(zope.interface.Interface):
...
... def getSize():
@@ -32,8 +38,10 @@
Now we need to implement the file. It is essential that the object states
that it implements the `IFile` interface. We also provide a default body
-value (just to make things simpler for this example)::
+value (just to make things simpler for this example):
+.. doctest::
+
>>> class File(object):
...
... zope.interface.implements(IFile)
@@ -52,8 +60,10 @@
that is used to extract the size from. Also by convention the context is
stored in an attribute named `context` on the adapter. The twisted community
refers to the context as the `original` object. However, you may feel free to
-use a specific argument name, such as `file`::
+use a specific argument name, such as `file`:
+.. doctest::
+
>>> class FileSize(object):
...
... zope.interface.implements(ISize)
@@ -68,8 +78,10 @@
Now that we have written our adapter, we have to register it with an adapter
registry, so that it can be looked up when needed. There is no such thing as a
-global registry; thus we have to instantiate one for our example manually::
+global registry; thus we have to instantiate one for our example manually:
+.. doctest::
+
>>> from zope.interface.adapter import AdapterRegistry
>>> registry = AdapterRegistry()
@@ -88,19 +100,25 @@
`ISize`. The third argument is the name of the adapter. Since we do not care
about names, we simply leave it as an empty string. Names are commonly useful,
if you have adapters for the same set of interfaces, but they are useful in
-different situations. The last argument is simply the adapter class::
+different situations. The last argument is simply the adapter class:
+.. doctest::
+
>>> registry.register([IFile], ISize, '', FileSize)
-You can now use the the registry to lookup the adapter::
+You can now use the the registry to lookup the adapter:
+.. doctest::
+
>>> registry.lookup1(IFile, ISize, '')
- <class '__main__.FileSize'>
+ <class 'FileSize'>
Let's get a little bit more practical. Let's create a `File` instance and
create the adapter using a registry lookup. Then we see whether the adapter
-returns the correct size by calling `getSize()`::
+returns the correct size by calling `getSize()`:
+.. doctest::
+
>>> file = File()
>>> size = registry.lookup1(IFile, ISize, '')(file)
>>> size.getSize()
@@ -120,28 +138,36 @@
used an adapter cache or persistent adapters, for instance. The helper hook is
required to expect as first argument the desired output interface (for us
`ISize`) and as the second argument the context of the adapter (here
-`file`). The function returns an adapter, i.e. a `FileSize` instance::
+`file`). The function returns an adapter, i.e. a `FileSize` instance:
+.. doctest::
+
>>> def hook(provided, object):
... adapter = registry.lookup1(zope.interface.providedBy(object),
... provided, '')
... return adapter(object)
...
-We now just add the hook to an `adapter_hooks` list::
+We now just add the hook to an `adapter_hooks` list:
+.. doctest::
+
>>> from zope.interface.interface import adapter_hooks
>>> adapter_hooks.append(hook)
-Once the hook is registered, you can use the desired syntax::
+Once the hook is registered, you can use the desired syntax:
+.. doctest::
+
>>> size = ISize(file)
>>> size.getSize()
7
Now we have to cleanup after ourselves, so that others after us have a clean
-`adapter_hooks` list::
+`adapter_hooks` list:
+.. doctest::
+
>>> adapter_hooks.remove(hook)
That's it. I have intentionally left out a discussion of named adapters and
Modified: zope.interface/branches/tseaver-no_2to3/docs/verify.rst
===================================================================
--- zope.interface/branches/tseaver-no_2to3/docs/verify.rst 2012-04-06 01:15:03 UTC (rev 124982)
+++ zope.interface/branches/tseaver-no_2to3/docs/verify.rst 2012-04-06 01:15:07 UTC (rev 124983)
@@ -34,94 +34,97 @@
Attributes of the object, be they defined by its class or added by its
``__init__`` method, will be recognized:
->>> from zope.interface import Interface, Attribute, implements
->>> from zope.interface.exceptions import BrokenImplementation
->>> class IFoo(Interface):
-... x = Attribute("The X attribute")
-... y = Attribute("The Y attribute")
+.. doctest::
->>> class Foo(object):
-... implements(IFoo)
-... x = 1
-... def __init__(self):
-... self.y = 2
+ >>> from zope.interface import Interface, Attribute, implements
+ >>> from zope.interface.exceptions import BrokenImplementation
+ >>> class IFoo(Interface):
+ ... x = Attribute("The X attribute")
+ ... y = Attribute("The Y attribute")
->>> from zope.interface.verify import verifyObject
->>> verifyObject(IFoo, Foo())
-True
+ >>> class Foo(object):
+ ... implements(IFoo)
+ ... x = 1
+ ... def __init__(self):
+ ... self.y = 2
+ >>> from zope.interface.verify import verifyObject
+ >>> verifyObject(IFoo, Foo())
+ True
+
If either attribute is missing, verification will fail:
->>> class Foo(object):
-... implements(IFoo)
-... x = 1
+.. doctest::
->>> try: #doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
-... verifyObject(IFoo, Foo())
-... except BrokenImplementation, e:
-... print str(e)
-An object has failed to implement interface <InterfaceClass ...IFoo>
-<BLANKLINE>
- The y attribute was not provided.
-<BLANKLINE>
+ >>> class Foo(object):
+ ... implements(IFoo)
+ ... x = 1
+ >>> try: #doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+ ... verifyObject(IFoo, Foo())
+ ... except BrokenImplementation, e:
+ ... print str(e)
+ An object has failed to implement interface <InterfaceClass ...IFoo>
+ <BLANKLINE>
+ The y attribute was not provided.
+ <BLANKLINE>
+ >>> class Foo(object):
+ ... implements(IFoo)
+ ... def __init__(self):
+ ... self.y = 2
+ >>> try: #doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+ ... verifyObject(IFoo, Foo())
+ ... except BrokenImplementation, e:
+ ... print str(e)
+ An object has failed to implement interface <InterfaceClass ...IFoo>
+ <BLANKLINE>
+ The x attribute was not provided.
+ <BLANKLINE>
->>> class Foo(object):
-... implements(IFoo)
-... def __init__(self):
-... self.y = 2
-
->>> try: #doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
-... verifyObject(IFoo, Foo())
-... except BrokenImplementation, e:
-... print str(e)
-An object has failed to implement interface <InterfaceClass ...IFoo>
-<BLANKLINE>
- The x attribute was not provided.
-<BLANKLINE>
-
If an attribute is implemented as a property that raises an AttributeError
when trying to get its value, the attribute is considered missing:
->>> class IFoo(Interface):
-... x = Attribute('The X attribute')
+.. doctest::
->>> class Foo(object):
-... implements(IFoo)
-... @property
-... def x(self):
-... raise AttributeError
+ >>> class IFoo(Interface):
+ ... x = Attribute('The X attribute')
+ >>> class Foo(object):
+ ... implements(IFoo)
+ ... @property
+ ... def x(self):
+ ... raise AttributeError
+ >>> try: #doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+ ... verifyObject(IFoo, Foo())
+ ... except BrokenImplementation, e:
+ ... print str(e)
+ An object has failed to implement interface <InterfaceClass ...IFoo>
+ <BLANKLINE>
+ The x attribute was not provided.
+ <BLANKLINE>
->>> try: #doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
-... verifyObject(IFoo, Foo())
-... except BrokenImplementation, e:
-... print str(e)
-An object has failed to implement interface <InterfaceClass ...IFoo>
-<BLANKLINE>
- The x attribute was not provided.
-<BLANKLINE>
-
Any other exception raised by a property will propagate to the caller of
``verifyObject``:
->>> class Foo(object):
-... implements(IFoo)
-... @property
-... def x(self):
-... raise Exception
+.. doctest::
->>> verifyObject(IFoo, Foo())
-Traceback (most recent call last):
-Exception
+ >>> class Foo(object):
+ ... implements(IFoo)
+ ... @property
+ ... def x(self):
+ ... raise Exception
+ >>> verifyObject(IFoo, Foo())
+ Traceback (most recent call last):
+ Exception
Of course, broken properties that are not required by the interface don't do
any harm:
->>> class Foo(object):
-... implements(IFoo)
-... x = 1
-... @property
-... def y(self):
-... raise Exception
+.. doctest::
->>> verifyObject(IFoo, Foo())
-True
+ >>> class Foo(object):
+ ... implements(IFoo)
+ ... x = 1
+ ... @property
+ ... def y(self):
+ ... raise Exception
+ >>> verifyObject(IFoo, Foo())
+ True
More information about the checkins
mailing list