€cdocutils.nodes
document
q
)q}q(UtagnameqUdocumentqUreporterqNU
attributesq}q(Udupnamesq	]Ubackrefsq
]UsourceX=/home/tseaver/projects/Zope/Z3/zope.interface/docs/README.rstqUidsq]Uclassesq
]Unamesq]uUparse_messagesq]qU
decorationqNU	citationsq]qU	rawsourceqUU	nametypesq}q(Xexternal declarationsqNX'inheritance of attribute specificationsqNXspecificationsqNX
tagged valuesqNXdeclaration objectsqNXinherited declarationsqNX
invariantsqNXcompatqˆXdefining interfacesqNX
interfacesq NX	__adapt__q!NXdeclaring interfacesq"NXcreateq#ˆXdeclaring provided interfacesq$NXfactoryq%ˆX declaring implemented interfacesq&NXinterface inheritanceq'NX
adaptationq(NuUsettingsq)(cdocutils.frontend
Values
q*oq+}q,(Upep_referencesq-NUoutput_encoding_error_handlerq.Ustrictq/U
halt_levelq0KU
source_urlq1NU
dump_settingsq2NUdoctitle_xformq3‰Udump_pseudo_xmlq4NU	tab_widthq5KU	id_prefixq6UUtitleq7NUembed_stylesheetq8‰U
docinfo_xformq9K
Ufootnote_backlinksq:K
Uerror_encodingq;UUTF-8q<Uauto_id_prefixq=Uidq>U
language_codeq?Uenq@U	datestampqANUdump_transformsqBNUoutput_encodingqCUutf-8qDUexit_status_levelqEKUstrict_visitorqFNU_disable_configqGNUfile_insertion_enabledqHˆU	tracebackqIˆUrecord_dependenciesqJNUstrip_commentsqKNUdebugqLNU	generatorqMNUgettext_compactqNˆUenvqONU
strip_classesqPNUpep_file_url_templateqQUpep-%04dqRUinput_encoding_error_handlerqSh/Uexpose_internalsqTNUrfc_referencesqUNU
toc_backlinksqVUentryqWUtrim_footnote_reference_spaceqX‰U_sourceqYhUwarning_streamqZNUinput_encodingq[U	utf-8-sigq\Usectsubtitle_xformq]‰Usource_linkq^NUconfigq_NU
sectnum_xformq`K
Uerror_encoding_error_handlerqaUbackslashreplaceqbU
_config_filesqc]Udump_internalsqdNUsmart_quotesqe‰Ucloak_email_addressesqfˆUraw_enabledqgK
Ustrip_elements_with_classesqhNUpep_base_urlqiU https://www.python.org/dev/peps/qjUreport_levelqkKUrfc_base_urlqlUhttps://tools.ietf.org/html/qmU_destinationqnNUsyntax_highlightqoUlongqpubUautofootnote_refsqq]qr(cdocutils.nodes
footnote_reference
qs)qt}qu(hUfootnote_referenceqvh}qw(h	]h
]UrefidqxUcreateqyh
]h]qzUid1q{aUautoq|K
h]uhX
[#create]_Uresolvedq}K
Uparentq~cdocutils.nodes
paragraph
q)q€}q(hhhU	paragraphq‚h}qƒ(h
]h	]h]h]h
]uUlineq„K%Usourceq…hhX0
In the example above, we've created an interface, `IFoo`.  We
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`:h~cdocutils.nodes
section
q†)q‡}qˆ(hhhUsectionq‰h}qŠ(h
]h	]h]q‹hah]qŒUdefining-interfacesqah
]uh„Kh…hhUh~h†)qŽ}q(hhhh‰h}q(h
]h	]h]q‘h ah]q’U
interfacesq“ah
]uh„Kh…hhUh~hUchildrenq”]q•(cdocutils.nodes
title
q–)q—}q˜(hhhh7h}q™(h
]h	]h]h]h
]uh„Kh…hhX
Interfacesqšh~hŽh”]q›cdocutils.nodes
Text
qœX
Interfacesq…qž}qŸ(hhšh~h—ubaubh)q }q¡(hhhh‚h}q¢(h
]h	]h]h]h
]uh„Kh…hhXŽInterfaces are objects that specify (document) the external behavior
of objects that "provide" them.  An interface specifies behavior
through:q£h~hŽh”]q¤hœXŽInterfaces are objects that specify (document) the external behavior
of objects that "provide" them.  An interface specifies behavior
through:q¥…q¦}q§(hh£h~h ubaubcdocutils.nodes
bullet_list
q¨)q©}qª(hhhUbullet_listq«h}q¬(h	]h
]h
]h]Ubulletq­X
-h]uh„K	h…hhUh~hŽh”]q®(cdocutils.nodes
list_item
q¯)q°}q±(hhhU	list_itemq²h}q³(h
]h	]h]h]h
]uh„Nh…hhX'Informal documentation in a doc string
h~h©h”]q´h)qµ}q¶(hh‚h}q·(h
]h	]h]h]h
]uh„K	h…hhX&Informal documentation in a doc stringq¸h~h°h”]q¹hœX&Informal documentation in a doc stringqº…q»}q¼(hh¸h~hµubaubaubh¯)q½}q¾(hhhh²h}q¿(h
]h	]h]h]h
]uh„Nh…hhXAttribute definitions
h~h©h”]qÀh)qÁ}qÂ(hh‚h}qÃ(h
]h	]h]h]h
]uh„Kh…hhXAttribute definitionsqÄh~h½h”]qÅhœXAttribute definitionsqƅqÇ}qÈ(hhÄh~hÁubaubaubh¯)qÉ}qÊ(hhhh²h}qË(h
]h	]h]h]h
]uh„Nh…hhXWInvariants, which are conditions that must hold for objects that
provide the interface
h~h©h”]qÌh)qÍ}qÎ(hh‚h}qÏ(h
]h	]h]h]h
]uh„K
h…hhXVInvariants, which are conditions that must hold for objects that
provide the interfaceqÐh~hÉh”]qÑhœXVInvariants, which are conditions that must hold for objects that
provide the interfaceq҅qÓ}qÔ(hhÐh~hÍubaubaubeubh)qÕ}qÖ(hhhh‚h}q×(h
]h	]h]h]h
]uh„Kh…hhX×Attribute definitions specify specific attributes. They define the
attribute name and provide documentation and constraints of attribute
values.  Attribute definitions can take a number of forms, as we'll
see below.qØh~hŽh”]qÙhœX×Attribute definitions specify specific attributes. They define the
attribute name and provide documentation and constraints of attribute
values.  Attribute definitions can take a number of forms, as we'll
see below.qڅqÛ}qÜ(hhØh~hÕubaubh‡h†)qÝ}qÞ(hhhh‰h}qß(h
]h	]h]qàh"ah]qáUdeclaring-interfacesqâah
]uh„K“h…hhUh~hŽh”]qã(h–)qä}qå(hhhh7h}qæ(h
]h	]h]h]h
]uh„K“h…hhXDeclaring interfacesqçh~hÝh”]qèhœXDeclaring interfacesq酁qê}që(hhçh~häubaubh)qì}qí(hhhh‚h}qî(h
]h	]h]h]h
]uh„K•h…hhXHaving defined interfaces, we can *declare* that objects provide
them.  Before we describe the details, lets define some terms:h~hÝh”]qï(hœX"Having defined interfaces, we can qð…qñ}qò(hX"Having defined interfaces, we can h~hìubcdocutils.nodes
emphasis
qó)qô}qõ(hX	*declare*hUemphasisqöh}q÷(h
]h	]h]h]h
]uh~hìh”]qøhœXdeclareqù…qú}qû(hUh~hôubaubhœXT that objects provide
them.  Before we describe the details, lets define some terms:qü…qý}qþ(hXT that objects provide
them.  Before we describe the details, lets define some terms:h~hìubeubcdocutils.nodes
definition_list
qÿ)r
}r

(hhhUdefinition_listr
h}r
(h
]h	]h]h]h
]uh„Nh…hhUh~hÝh”]r
(cdocutils.nodes
definition_list_item
r
)r
}r
(hUdefinition_list_itemr
h}r	
(h
]h	]h]h]h
]uh„Kœh…hhXä*provide*
We say that objects *provide* interfaces.  If an object provides an
interface, then the interface specifies the behavior of the
object. In other words, interfaces specify the behavior of the
objects that provide them.
h~j
h”]r

(cdocutils.nodes
term
r
)r
}r

(hUtermr
h}r
(h
]h	]h]h]h
]uh„Kœh…hhX	*provide*r
h~j
h”]r
hó)r
}r
(hj
hhöh}r
(h
]h	]h]h]h
]uh~j
h”]r
hœXprovider
…r
}r
(hUh~j
ubaubaubcdocutils.nodes
definition
r
)r
}r
(hUhU
definitionr
h}r
(h
]h	]h]h]h
]uh~j
h”]r
h)r
}r 
(hh‚h}r!
(h
]h	]h]h]h
]uh„K™h…hhXÙWe say that objects *provide* interfaces.  If an object provides an
interface, then the interface specifies the behavior of the
object. In other words, interfaces specify the behavior of the
objects that provide them.h~j
h”]r"
(hœXWe say that objects r#
…r$
}r%
(hXWe say that objects h~j
ubhó)r&
}r'
(hX	*provide*hhöh}r(
(h
]h	]h]h]h
]uh~j
h”]r)
hœXprovider*
…r+
}r,
(hUh~j&
ubaubhœX¼ interfaces.  If an object provides an
interface, then the interface specifies the behavior of the
object. In other words, interfaces specify the behavior of the
objects that provide them.r-
…r.
}r/
(hX¼ interfaces.  If an object provides an
interface, then the interface specifies the behavior of the
object. In other words, interfaces specify the behavior of the
objects that provide them.h~j
ubeubaubeubj
)r0
}r1
(hhhj
h}r2
(h
]h	]h]h]h
]uh„Kªh…hhXV*implement*
We normally say that classes *implement* interfaces.  If a class
implements an interface, then the instances of the class provide
the interface.  Objects provide interfaces that their classes
implement [#factory]_.  (Objects can provide interfaces directly,
in addition to what their classes implement.)

It is important to note that classes don't usually provide the
interfaces that they implement.

We can generalize this to factories.  For any callable object we
can declare that it produces objects that provide some interfaces
by saying that the factory implements the interfaces.
h~j
h”]r3
(j
)r4
}r5
(hj
h}r6
(h
]h	]h]h]h
]uh„Kªh…hhX*implement*r7
h~j0
h”]r8
hó)r9
}r:
(hj7
hhöh}r;
(h
]h	]h]h]h
]uh~j4
h”]r<
hœX	implementr=
…r>
}r?
(hUh~j9
ubaubaubj
)r@
}rA
(hUhj
h}rB
(h
]h	]h]h]h
]uh~j0
h”]rC
(h)rD
}rE
(hh‚h}rF
(h
]h	]h]h]h
]uh„KŸh…hhX/
We normally say that classes *implement* interfaces.  If a class
implements an interface, then the instances of the class provide
the interface.  Objects provide interfaces that their classes
implement [#factory]_.  (Objects can provide interfaces directly,
in addition to what their classes implement.)h~j@
h”]rG
(hœXWe normally say that classes rH
…rI
}rJ
(hXWe normally say that classes h~jD
ubhó)rK
}rL
(hX*implement*hhöh}rM
(h
]h	]h]h]h
]uh~jD
h”]rN
hœX	implementrO
…rP
}rQ
(hUh~jK
ubaubhœX¢ interfaces.  If a class
implements an interface, then the instances of the class provide
the interface.  Objects provide interfaces that their classes
implement rR
…rS
}rT
(hX¢ interfaces.  If a class
implements an interface, then the instances of the class provide
the interface.  Objects provide interfaces that their classes
implement h~jD
ubhs)rU
}rV
(hhvh}rW
(h	]h
]hxUfactoryrX
h
]h]rY
Uid2rZ
ah|K
h]uhX[#factory]_h}K
h~jD
h”]r[
hœX
2…r\
}r]
(hUh~jU
ubaubhœXZ.  (Objects can provide interfaces directly,
in addition to what their classes implement.)r^
…r_
}r`
(hXZ.  (Objects can provide interfaces directly,
in addition to what their classes implement.)h~jD
ubeubh)ra
}rb
(hh‚h}rc
(h
]h	]h]h]h
]uh„K¥h…hhX^It is important to note that classes don't usually provide the
interfaces that they implement.rd
h~j@
h”]re
hœX^It is important to note that classes don't usually provide the
interfaces that they implement.rf
…rg
}rh
(hjd
h~ja
ubaubh)ri
}rj
(hh‚h}rk
(h
]h	]h]h]h
]uh„K¨h…hhX¸We can generalize this to factories.  For any callable object we
can declare that it produces objects that provide some interfaces
by saying that the factory implements the interfaces.rl
h~j@
h”]rm
hœX¸We can generalize this to factories.  For any callable object we
can declare that it produces objects that provide some interfaces
by saying that the factory implements the interfaces.rn
…ro
}rp
(hjl
h~ji
ubaubeubeubeubh)rq
}rr
(hhhh‚h}rs
(h
]h	]h]h]h
]uh„K¬h…hhXWNow that we've defined these terms, we can talk about the API for
declaring interfaces.rt
h~hÝh”]ru
hœXWNow that we've defined these terms, we can talk about the API for
declaring interfaces.rv
…rw
}rx
(hjt
h~jq
ubaubh†)ry
}rz
(hhhh‰h}r{
(h
]h	]h]r|
h&ah]r}
U declaring-implemented-interfacesr~
ah
]uh„K°h…hhUh~hÝh”]r
(h–)r€
}r
(hhhh7h}r‚
(h
]h	]h]h]h
]uh„K°h…hhX Declaring implemented interfacesrƒ
h~jy
h”]r„
hœX Declaring implemented interfacesr…
…r†
}r‡
(hjƒ
h~j€
ubaubh)rˆ
}r‰
(hhhh‚h}rŠ
(h
]h	]h]h]h
]uh„K²h…hhX`The most common way to declare interfaces is using the implements
function in a class statement:r‹
h~jy
h”]rŒ
hœX`The most common way to declare interfaces is using the implements
function in a class statement:r
…rŽ
}r
(hj‹
h~jˆ
ubaubcdocutils.nodes
literal_block
r
)r‘
}r’
(hhhU
literal_blockr“
h}r”
(h	]U	xml:spacer•
Upreserver–
h
]UtestnodetypeXdoctesth
]Ugroups]r—
Udefaultr˜
ah]Uoptionsr™
}h]uh„Kµh…hhX

>>> class Foo:
...     zope.interface.implements(IFoo)
...
...     def __init__(self, x=None):
...         self.x = x
...
...     def bar(self, q, r=None):
...         return q, r, self.x
...
...     def __repr__(self):
...         return "Foo(%s)" % self.xh~jy
h”]rš
hœX

>>> class Foo:
...     zope.interface.implements(IFoo)
...
...     def __init__(self, x=None):
...         self.x = x
...
...     def bar(self, q, r=None):
...         return q, r, self.x
...
...     def __repr__(self):
...         return "Foo(%s)" % self.xr›
…rœ
}r
(hUh~j‘
ubaubh)rž
}rŸ
(hhhh‚h}r 
(h
]h	]h]h]h
]uh„KÄh…hhX

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:h~jy
h”]r¡
(hœX"In this example, we declared that r¢
…r£
}r¤
(hX"In this example, we declared that h~jž
ubcdocutils.nodes
title_reference
r¥
)r¦
}r§
(hX`Foo`hUtitle_referencer¨
h}r©
(h
]h	]h]h]h
]uh~jž
h”]rª
hœXFoor«
…r¬
}r­
(hUh~j¦
ubaubhœX implements r®
…r¯
}r°
(hX implements h~jž
ubj¥
)r±
}r²
(hX`IFoo`hj¨
h}r³
(h
]h	]h]h]h
]uh~jž
h”]r´
hœXIFoorµ
…r¶
}r·
(hUh~j±
ubaubhœX. This means
that instances of r¸
…r¹
}rº
(hX. This means
that instances of h~jž
ubj¥
)r»
}r¼
(hX`Foo`hj¨
h}r½
(h
]h	]h]h]h
]uh~jž
h”]r¾
hœXFoor¿
…rÀ
}rÁ
(hUh~j»
ubaubhœX	 provide rÂ
…rÃ
}rÄ
(hX	 provide h~jž
ubj¥
)rÅ
}rÆ
(hX`IFoo`hj¨
h}rÇ
(h
]h	]h]h]h
]uh~jž
h”]rÈ
hœXIFoorÉ
…rÊ
}rË
(hUh~jÅ
ubaubhœX¡.  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:rÌ
…rÍ
}rÎ
(hX¡.  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:h~jž
ubeubj
)rÏ
}rÐ
(hhhj“
h}rÑ
(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rÒ
j˜
ah]j™
}h]uh„KÉh…hhX >>> IFoo.implementedBy(Foo)
Trueh~jy
h”]rÓ
hœX >>> IFoo.implementedBy(Foo)
TruerÔ
…rÕ
}rÖ
(hUh~jÏ
ubaubh)r×
}rØ
(hhhh‚h}rÙ
(h
]h	]h]h]h
]uh„KÎh…hhX=And we can ask whether an interface is provided by an object:rÚ
h~jy
h”]rÛ
hœX=And we can ask whether an interface is provided by an object:rÜ
…rÝ
}rÞ
(hjÚ
h~j×
ubaubj
)rß
}rà
(hhhj“
h}rá
(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]râ
j˜
ah]j™
}h]uh„KÐh…hhX->>> foo = Foo()
>>> IFoo.providedBy(foo)
Trueh~jy
h”]rã
hœX->>> foo = Foo()
>>> IFoo.providedBy(foo)
Truerä
…rå
}ræ
(hUh~jß
ubaubh)rç
}rè
(hhhh‚h}ré
(h
]h	]h]h]h
]uh„KÖh…hhX:Of course, `Foo` doesn't provide `IFoo`, it implements it:rê
h~jy
h”]rë
(hœXOf course, rì
…rí
}rî
(hXOf course, h~jç
ubj¥
)rï
}rð
(hX`Foo`hj¨
h}rñ
(h
]h	]h]h]h
]uh~jç
h”]rò
hœXFooró
…rô
}rõ
(hUh~jï
ubaubhœX doesn't provide rö
…r÷
}rø
(hX doesn't provide h~jç
ubj¥
)rù
}rú
(hX`IFoo`hj¨
h}rû
(h
]h	]h]h]h
]uh~jç
h”]rü
hœXIFoorý
…rþ
}rÿ
(hUh~jù
ubaubhœX, it implements it:r…r
}r(hX, it implements it:h~jç
ubeubj
)r}r(hhhj“
h}r(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rj˜
ah]j™
}h]uh„KØh…hhX>>> IFoo.providedBy(Foo)
Falseh~jy
h”]rhœX>>> IFoo.providedBy(Foo)
Falser…r	}r
(hUh~jubaubh)r}r(hhhh‚h}r
(h
]h	]h]h]h
]uh„KÝh…hhX=We can also ask what interfaces are implemented by an object:rh~jy
h”]rhœX=We can also ask what interfaces are implemented by an object:r…r}r(hjh~jubaubj
)r}r(hhhj“
h}r(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rj˜
ah]j™
}h]uh„Kßh…hhXO>>> list(zope.interface.implementedBy(Foo))
[<InterfaceClass __builtin__.IFoo>]h~jy
h”]rhœXO>>> list(zope.interface.implementedBy(Foo))
[<InterfaceClass __builtin__.IFoo>]r…r}r(hUh~jubaubh)r}r(hhhh‚h}r(h
]h	]h]h]h
]uh„Käh…hhXIIt's an error to ask for interfaces implemented by a non-callable
object:rh~jy
h”]rhœXIIt's an error to ask for interfaces implemented by a non-callable
object:r …r!}r"(hjh~jubaubj
)r#}r$(hhhj“
h}r%(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r&j˜
ah]j™
}h]uh„Kçh…hhX
>>> IFoo.implementedBy(foo)
Traceback (most recent call last):
...
TypeError: ('ImplementedBy called for non-factory', Foo(None))

>>> list(zope.interface.implementedBy(foo))
Traceback (most recent call last):
...
TypeError: ('ImplementedBy called for non-factory', Foo(None))h~jy
h”]r'hœX
>>> IFoo.implementedBy(foo)
Traceback (most recent call last):
...
TypeError: ('ImplementedBy called for non-factory', Foo(None))

>>> list(zope.interface.implementedBy(foo))
Traceback (most recent call last):
...
TypeError: ('ImplementedBy called for non-factory', Foo(None))r(…r)}r*(hUh~j#ubaubh)r+}r,(hhhh‚h}r-(h
]h	]h]h]h
]uh„Kóh…hhX@Similarly, we can ask what interfaces are provided by an object:r.h~jy
h”]r/hœX@Similarly, we can ask what interfaces are provided by an object:r0…r1}r2(hj.h~j+ubaubj
)r3}r4(hhhj“
h}r5(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r6j˜
ah]j™
}h]uh„Kõh…hhXx>>> list(zope.interface.providedBy(foo))
[<InterfaceClass __builtin__.IFoo>]
>>> list(zope.interface.providedBy(Foo))
[]h~jy
h”]r7hœXx>>> list(zope.interface.providedBy(foo))
[<InterfaceClass __builtin__.IFoo>]
>>> list(zope.interface.providedBy(Foo))
[]r8…r9}r:(hUh~j3ubaubh)r;}r<(hhhh‚h}r=(h
]h	]h]h]h
]uh„Küh…hhXÃ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:h~jy
h”]r>(hœXWe can declare interfaces implemented by other factories (besides
classes).  We do this using a Python-2.4-style decorator named
r?…r@}rA(hXWe can declare interfaces implemented by other factories (besides
classes).  We do this using a Python-2.4-style decorator named
h~j;ubj¥
)rB}rC(hX
`implementer`hj¨
h}rD(h
]h	]h]h]h
]uh~j;h”]rEhœXimplementerrF…rG}rH(hUh~jBubaubhœX5.  In versions of Python before 2.4, this looks like:rI…rJ}rK(hX5.  In versions of Python before 2.4, this looks like:h~j;ubeubj
)rL}rM(hhhj“
h}rN(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rOj˜
ah]j™
}h]uh„M
h…hhXÍ>>> def yfoo(y):
...     foo = Foo()
...     foo.y = y
...     return foo
>>> yfoo = zope.interface.implementer(IFoo)(yfoo)

>>> list(zope.interface.implementedBy(yfoo))
[<InterfaceClass __builtin__.IFoo>]h~jy
h”]rPhœXÍ>>> def yfoo(y):
...     foo = Foo()
...     foo.y = y
...     return foo
>>> yfoo = zope.interface.implementer(IFoo)(yfoo)

>>> list(zope.interface.implementedBy(yfoo))
[<InterfaceClass __builtin__.IFoo>]rQ…rR}rS(hUh~jLubaubh)rT}rU(hhhh‚h}rV(h
]h	]h]h]h
]uh„M
h…hhXuNote that the implementer decorator may modify it's argument. Callers
should not assume that a new object is created.rWh~jy
h”]rXhœXuNote that the implementer decorator may modify it's argument. Callers
should not assume that a new object is created.rY…rZ}r[(hjWh~jTubaubh)r\}r](hhhh‚h}r^(h
]h	]h]h]h
]uh„M
h…hhX^Using implementer also works on callable objects. This is used by
zope.formlib, as an example:r_h~jy
h”]r`hœX^Using implementer also works on callable objects. This is used by
zope.formlib, as an example:ra…rb}rc(hj_h~j\ubaubj
)rd}re(hhhj“
h}rf(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rgj˜
ah]j™
}h]uh„M
h…hhX
>>> class yfactory:
...     def __call__(self, y):
...         foo = Foo()
...         foo.y = y
...         return foo
>>> yfoo = yfactory()
>>> yfoo = zope.interface.implementer(IFoo)(yfoo)

>>> list(zope.interface.implementedBy(yfoo))
[<InterfaceClass __builtin__.IFoo>]h~jy
h”]rhhœX
>>> class yfactory:
...     def __call__(self, y):
...         foo = Foo()
...         foo.y = y
...         return foo
>>> yfoo = yfactory()
>>> yfoo = zope.interface.implementer(IFoo)(yfoo)

>>> list(zope.interface.implementedBy(yfoo))
[<InterfaceClass __builtin__.IFoo>]ri…rj}rk(hUh~jdubaubh)rl}rm(hhhh‚h}rn(h
]h	]h]h]h
]uh„M
h…hhX3XXX: Double check and update these version numbers:roh~jy
h”]rphœX3XXX: Double check and update these version numbers:rq…rr}rs(hjoh~jlubaubh)rt}ru(hhhh‚h}rv(h
]h	]h]h]h
]uh„M 
h…hhXyIn 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:rwh~jy
h”]rxhœXyIn 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:ry…rz}r{(hjwh~jtubaubj
)r|}r}(hhhj“
h}r~(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rj˜
ah]j™
}h]uh„M#
h…hhX~>>> Foo = zope.interface.implementer(IFoo)(Foo)
>>> list(zope.interface.providedBy(Foo()))
[<InterfaceClass __builtin__.IFoo>]h~jy
h”]r€hœX~>>> Foo = zope.interface.implementer(IFoo)(Foo)
>>> list(zope.interface.providedBy(Foo()))
[<InterfaceClass __builtin__.IFoo>]r…r‚}rƒ(hUh~j|ubaubh)r„}r…(hhhh‚h}r†(h
]h	]h]h]h
]uh„M)
h…hhXjNote that class decorators using the @implementer(IFoo) syntax are only
supported in Python 2.6 and later.r‡h~jy
h”]rˆhœXjNote that class decorators using the @implementer(IFoo) syntax are only
supported in Python 2.6 and later.r‰…rŠ}r‹(hj‡h~j„ubaubeubh†)rŒ}r(hhhh‰h}rŽ(h
]h	]h]rh$ah]rUdeclaring-provided-interfacesr‘ah
]uh„M.
h…hhUh~hÝh”]r’(h–)r“}r”(hhhh7h}r•(h
]h	]h]h]h
]uh„M.
h…hhXDeclaring provided interfacesr–h~jŒh”]r—hœXDeclaring provided interfacesr˜…r™}rš(hj–h~j“ubaubh)r›}rœ(hhhh‚h}r(h
]h	]h]h]h
]uh„M0
h…hhX=
We can declare interfaces directly provided by objects.  Suppose that
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:h~jŒh”]rž(hœXcWe can declare interfaces directly provided by objects.  Suppose that
we want to document what the rŸ…r }r¡(hXcWe can declare interfaces directly provided by objects.  Suppose that
we want to document what the h~j›ubj¥
)r¢}r£(hX
`__init__`hj¨
h}r¤(h
]h	]h]h]h
]uh~j›h”]r¥hœX__init__r¦…r§}r¨(hUh~j¢ubaubhœX method of the r©…rª}r«(hX method of the h~j›ubj¥
)r¬}r­(hX`Foo`hj¨
h}r®(h
]h	]h]h]h
]uh~j›h”]r¯hœXFoor°…r±}r²(hUh~j¬ubaubhœX class
does.  It's not r³…r´}rµ(hX class
does.  It's not h~j›ubhó)r¶}r·(hX*really*hhöh}r¸(h
]h	]h]h]h
]uh~j›h”]r¹hœXreallyrº…r»}r¼(hUh~j¶ubaubhœX	 part of r½…r¾}r¿(hX	 part of h~j›ubj¥
)rÀ}rÁ(hX`IFoo`hj¨
h}rÂ(h
]h	]h]h]h
]uh~j›h”]rÃhœXIFoorÄ…rÅ}rÆ(hUh~jÀubaubhœX".  You wouldn't normally call
the rÇ…rÈ}rÉ(hX".  You wouldn't normally call
the h~j›ubj¥
)rÊ}rË(hX
`__init__`hj¨
h}rÌ(h
]h	]h]h]h
]uh~j›h”]rÍhœX__init__rÎ…rÏ}rÐ(hUh~jÊubaubhœX' method on Foo instances.  Rather, the rÑ…rÒ}rÓ(hX' method on Foo instances.  Rather, the h~j›ubj¥
)rÔ}rÕ(hX
`__init__`hj¨
h}rÖ(h
]h	]h]h]h
]uh~j›h”]r×hœX__init__rØ…rÙ}rÚ(hUh~jÔubaubhœX method
is part of the rÛ…rÜ}rÝ(hX method
is part of the h~j›ubj¥
)rÞ}rß(hX`Foo`hj¨
h}rà(h
]h	]h]h]h
]uh~j›h”]ráhœXFoor⅁rã}rä(hUh~jÞubaubhœX's r允ræ}rç(hX's h~j›ubj¥
)rè}ré(hX
`__call__`hj¨
h}rê(h
]h	]h]h]h
]uh~j›h”]rëhœX__call__r셁rí}rî(hUh~jèubaubhœX method:rrð}rñ(hX method:h~j›ubeubj
)rò}ró(hhhj“
h}rô(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rõj˜
ah]j™
}h]uh„M6
h…hhXÚ>>> class IFooFactory(zope.interface.Interface):
...     """Create foos"""
...
...     def __call__(x=None):
...         """Create a foo
...
...         The argument provides the initial value for x ...
...         """h~jŒh”]röhœXÚ>>> class IFooFactory(zope.interface.Interface):
...     """Create foos"""
...
...     def __call__(x=None):
...         """Create a foo
...
...         The argument provides the initial value for x ...
...         """r÷…rø}rù(hUh~jòubaubh)rú}rû(hhhh‚h}rü(h
]h	]h]h]h
]uh„MA
h…hhXVIt's the class that provides this interface, so we declare the
interface on the class:rýh~jŒh”]rþhœXVIt's the class that provides this interface, so we declare the
interface on the class:rÿ…r}r
(hjýh~júubaubj
)r}r(hhhj“
h}r(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rj˜
ah]j™
}h]uh„MD
h…hhX5>>> zope.interface.directlyProvides(Foo, IFooFactory)h~jŒh”]rhœX5>>> zope.interface.directlyProvides(Foo, IFooFactory)r…r}r	(hUh~jubaubh)r
}r(hhhh‚h}r(h
]h	]h]h]h
]uh„MH
h…hhX6And then, we'll see that Foo provides some interfaces:r
h~jŒh”]rhœX6And then, we'll see that Foo provides some interfaces:r…r}r(hj
h~j
ubaubj
)r}r(hhhj“
h}r(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rj˜
ah]j™
}h]uh„MJ
h…hhXx>>> list(zope.interface.providedBy(Foo))
[<InterfaceClass __builtin__.IFooFactory>]
>>> IFooFactory.providedBy(Foo)
Trueh~jŒh”]rhœXx>>> list(zope.interface.providedBy(Foo))
[<InterfaceClass __builtin__.IFooFactory>]
>>> IFooFactory.providedBy(Foo)
Truer…r}r(hUh~jubaubh)r}r(hhhh‚h}r(h
]h	]h]h]h
]uh„MQ
h…hhX«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:h~jŒh”]r(hœX`Declaring class interfaces is common enough that there's a special
declaration function for it, r…r}r (hX`Declaring class interfaces is common enough that there's a special
declaration function for it, h~jubj¥
)r!}r"(hX`classProvides`hj¨
h}r#(h
]h	]h]h]h
]uh~jh”]r$hœX
classProvidesr%…r&}r'(hUh~j!ubaubhœX<, that allows the
declaration from within a class statement:r(…r)}r*(hX<, that allows the
declaration from within a class statement:h~jubeubj
)r+}r,(hhhj“
h}r-(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r.j˜
ah]j™
}h]uh„MU
h…hhX°
>>> class Foo2:
...     zope.interface.implements(IFoo)
...     zope.interface.classProvides(IFooFactory)
...
...     def __init__(self, x=None):
...         self.x = x
...
...     def bar(self, q, r=None):
...         return q, r, self.x
...
...     def __repr__(self):
...         return "Foo(%s)" % self.x

>>> list(zope.interface.providedBy(Foo2))
[<InterfaceClass __builtin__.IFooFactory>]
>>> IFooFactory.providedBy(Foo2)
Trueh~jŒh”]r/hœX°
>>> class Foo2:
...     zope.interface.implements(IFoo)
...     zope.interface.classProvides(IFooFactory)
...
...     def __init__(self, x=None):
...         self.x = x
...
...     def bar(self, q, r=None):
...         return q, r, self.x
...
...     def __repr__(self):
...         return "Foo(%s)" % self.x

>>> list(zope.interface.providedBy(Foo2))
[<InterfaceClass __builtin__.IFooFactory>]
>>> IFooFactory.providedBy(Foo2)
Truer0…r1}r2(hUh~j+ubaubh)r3}r4(hhhh‚h}r5(h
]h	]h]h]h
]uh„Mi
h…hhX
There's a similar function, `moduleProvides`, that supports interface
declarations from within module definitions.  For example, see the use
of `moduleProvides` call in `zope.interface.__init__`, which declares that
the package `zope.interface` provides `IInterfaceDeclaration`.h~jŒh”]r6(hœXThere's a similar function, r7…r8}r9(hXThere's a similar function, h~j3ubj¥
)r:}r;(hX`moduleProvides`hj¨
h}r<(h
]h	]h]h]h
]uh~j3h”]r=hœXmoduleProvidesr>…r?}r@(hUh~j:ubaubhœXd, that supports interface
declarations from within module definitions.  For example, see the use
of rA…rB}rC(hXd, that supports interface
declarations from within module definitions.  For example, see the use
of h~j3ubj¥
)rD}rE(hX`moduleProvides`hj¨
h}rF(h
]h	]h]h]h
]uh~j3h”]rGhœXmoduleProvidesrH…rI}rJ(hUh~jDubaubhœX	 call in rK…rL}rM(hX	 call in h~j3ubj¥
)rN}rO(hX`zope.interface.__init__`hj¨
h}rP(h
]h	]h]h]h
]uh~j3h”]rQhœXzope.interface.__init__rR…rS}rT(hUh~jNubaubhœX", which declares that
the package rU…rV}rW(hX", which declares that
the package h~j3ubj¥
)rX}rY(hX`zope.interface`hj¨
h}rZ(h
]h	]h]h]h
]uh~j3h”]r[hœXzope.interfacer\…r]}r^(hUh~jXubaubhœX
 provides r_…r`}ra(hX
 provides h~j3ubj¥
)rb}rc(hX`IInterfaceDeclaration`hj¨
h}rd(h
]h	]h]h]h
]uh~j3h”]rehœXIInterfaceDeclarationrf…rg}rh(hUh~jbubaubhœX
.…ri}rj(hX
.h~j3ubeubh)rk}rl(hhhh‚h}rm(h
]h	]h]h]h
]uh„Mn
h…hhX¥Sometimes, we want to declare interfaces on instances, even though
those instances get interfaces from their classes.  Suppose we create
a new interface, `ISpecial`:h~jŒh”]rn(hœXšSometimes, we want to declare interfaces on instances, even though
those instances get interfaces from their classes.  Suppose we create
a new interface, ro…rp}rq(hXšSometimes, we want to declare interfaces on instances, even though
those instances get interfaces from their classes.  Suppose we create
a new interface, h~jkubj¥
)rr}rs(hX
`ISpecial`hj¨
h}rt(h
]h	]h]h]h
]uh~jkh”]ruhœXISpecialrv…rw}rx(hUh~jrubaubhœX
:…ry}rz(hX
:h~jkubeubj
)r{}r|(hhhj“
h}r}(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r~j˜
ah]j™
}h]uh„Mr
h…hhX®>>> class ISpecial(zope.interface.Interface):
...     reason = zope.interface.Attribute("Reason why we're special")
...     def brag():
...         "Brag about being special"h~jŒh”]rhœX®>>> class ISpecial(zope.interface.Interface):
...     reason = zope.interface.Attribute("Reason why we're special")
...     def brag():
...         "Brag about being special"r€…r}r‚(hUh~j{ubaubh)rƒ}r„(hhhh‚h}r…(h
]h	]h]h]h
]uh„My
h…hhXYWe can make an existing foo instance special by providing `reason`
and `brag` attributes:h~jŒh”]r†(hœX:We can make an existing foo instance special by providing r‡…rˆ}r‰(hX:We can make an existing foo instance special by providing h~jƒubj¥
)rŠ}r‹(hX`reason`hj¨
h}rŒ(h
]h	]h]h]h
]uh~jƒh”]rhœXreasonrŽ…r}r(hUh~jŠubaubhœX
and r‘…r’}r“(hX
and h~jƒubj¥
)r”}r•(hX`brag`hj¨
h}r–(h
]h	]h]h]h
]uh~jƒh”]r—hœXbragr˜…r™}rš(hUh~j”ubaubhœX attributes:r›…rœ}r(hX attributes:h~jƒubeubj
)rž}rŸ(hhhj“
h}r (h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r¡j˜
ah]j™
}h]uh„M|
h…hhX˜>>> foo.reason = 'I just am'
>>> def brag():
...      return "I'm special!"
>>> foo.brag = brag
>>> foo.reason
'I just am'
>>> foo.brag()
"I'm special!"h~jŒh”]r¢hœX˜>>> foo.reason = 'I just am'
>>> def brag():
...      return "I'm special!"
>>> foo.brag = brag
>>> foo.reason
'I just am'
>>> foo.brag()
"I'm special!"r£…r¤}r¥(hUh~jžubaubh)r¦}r§(hhhh‚h}r¨(h
]h	]h]h]h
]uh„M‡
h…hhXand by declaring the interface:r©h~jŒh”]rªhœXand by declaring the interface:r«…r¬}r­(hj©h~j¦ubaubj
)r®}r¯(hhhj“
h}r°(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r±j˜
ah]j™
}h]uh„M‰
h…hhX2>>> zope.interface.directlyProvides(foo, ISpecial)h~jŒh”]r²hœX2>>> zope.interface.directlyProvides(foo, ISpecial)r³…r´}rµ(hUh~j®ubaubh)r¶}r·(hhhh‚h}r¸(h
]h	]h]h]h
]uh„M
h…hhX>then the new interface is included in the provided interfaces:r¹h~jŒh”]rºhœX>then the new interface is included in the provided interfaces:r»…r¼}r½(hj¹h~j¶ubaubj
)r¾}r¿(hhhj“
h}rÀ(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rÁj˜
ah]j™
}h]uh„M
h…hhX•>>> ISpecial.providedBy(foo)
True
>>> list(zope.interface.providedBy(foo))
[<InterfaceClass __builtin__.ISpecial>, <InterfaceClass __builtin__.IFoo>]h~jŒh”]rÂhœX•>>> ISpecial.providedBy(foo)
True
>>> list(zope.interface.providedBy(foo))
[<InterfaceClass __builtin__.ISpecial>, <InterfaceClass __builtin__.IFoo>]rÃ…rÄ}rÅ(hUh~j¾ubaubh)rÆ}rÇ(hhhh‚h}rÈ(h
]h	]h]h]h
]uh„M–
h…hhXCWe can find out what interfaces are directly provided by an object:rÉh~jŒh”]rÊhœXCWe can find out what interfaces are directly provided by an object:rË…rÌ}rÍ(hjÉh~jÆubaubj
)rÎ}rÏ(hhhj“
h}rÐ(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rÑj˜
ah]j™
}h]uh„M˜
h…hhX£>>> list(zope.interface.directlyProvidedBy(foo))
[<InterfaceClass __builtin__.ISpecial>]

>>> newfoo = Foo()
>>> list(zope.interface.directlyProvidedBy(newfoo))
[]h~jŒh”]rÒhœX£>>> list(zope.interface.directlyProvidedBy(foo))
[<InterfaceClass __builtin__.ISpecial>]

>>> newfoo = Foo()
>>> list(zope.interface.directlyProvidedBy(newfoo))
[]rÓ…rÔ}rÕ(hUh~jÎubaubeubh†)rÖ}r×(hhhh‰h}rØ(h
]h	]h]rÙhah]rÚUinherited-declarationsrÛah
]uh„M¢
h…hhUh~hÝh”]rÜ(h–)rÝ}rÞ(hhhh7h}rß(h
]h	]h]h]h
]uh„M¢
h…hhXInherited declarationsràh~jÖh”]ráhœXInherited declarationsr⅁rã}rä(hjàh~jÝubaubh)rå}ræ(hhhh‚h}rç(h
]h	]h]h]h
]uh„M¤
h…hhX%Normally, declarations are inherited:rèh~jÖh”]réhœX%Normally, declarations are inherited:rꅁrë}rì(hjèh~jåubaubj
)rí}rî(hhhj“
h}rï(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rðj˜
ah]j™
}h]uh„M¦
h…hhX²
>>> class SpecialFoo(Foo):
...     zope.interface.implements(ISpecial)
...     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>]

>>> list(zope.interface.providedBy(SpecialFoo()))
[<InterfaceClass __builtin__.ISpecial>, <InterfaceClass __builtin__.IFoo>]h~jÖh”]rñhœX²
>>> class SpecialFoo(Foo):
...     zope.interface.implements(ISpecial)
...     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>]

>>> list(zope.interface.providedBy(SpecialFoo()))
[<InterfaceClass __builtin__.ISpecial>, <InterfaceClass __builtin__.IFoo>]rò…ró}rô(hUh~jíubaubh)rõ}rö(hhhh‚h}r÷(h
]h	]h]h]h
]uh„M´
h…hhXxSometimes, you don't want to inherit declarations.  In that case, you
can use `implementsOnly`, instead of `implements`:h~jÖh”]rø(hœXNSometimes, you don't want to inherit declarations.  In that case, you
can use rù…rú}rû(hXNSometimes, you don't want to inherit declarations.  In that case, you
can use h~jõubj¥
)rü}rý(hX`implementsOnly`hj¨
h}rþ(h
]h	]h]h]h
]uh~jõh”]rÿhœXimplementsOnlyr…r
}r(hUh~jüubaubhœX
, instead of r…r}r(hX
, instead of h~jõubj¥
)r}r(hX`implements`hj¨
h}r(h
]h	]h]h]h
]uh~jõh”]r	hœX
implementsr
…r}r(hUh~jubaubhœX
:…r
}r(hX
:h~jõubeubj
)r}r(hhhj“
h}r(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rj˜
ah]j™
}h]uh„M·
h…hhXg
>>> class Special(Foo):
...     zope.interface.implementsOnly(ISpecial)
...     reason = 'I just am'
...     def brag(self):
...         return "I'm special because %s" % self.reason

>>> list(zope.interface.implementedBy(Special))
[<InterfaceClass __builtin__.ISpecial>]

>>> list(zope.interface.providedBy(Special()))
[<InterfaceClass __builtin__.ISpecial>]h~jÖh”]rhœXg
>>> class Special(Foo):
...     zope.interface.implementsOnly(ISpecial)
...     reason = 'I just am'
...     def brag(self):
...         return "I'm special because %s" % self.reason

>>> list(zope.interface.implementedBy(Special))
[<InterfaceClass __builtin__.ISpecial>]

>>> list(zope.interface.providedBy(Special()))
[<InterfaceClass __builtin__.ISpecial>]r…r}r(hUh~jubaubeubh†)r}r(hhhh‰h}r(h
]h	]h]rhah]rUexternal-declarationsrah
]uh„MÆ
h…hhUh~hÝh”]r(h–)r}r(hhhh7h}r (h
]h	]h]h]h
]uh„MÆ
h…hhXExternal declarationsr!h~jh”]r"hœXExternal declarationsr#…r$}r%(hj!h~jubaubh)r&}r'(hhhh‚h}r((h
]h	]h]h]h
]uh„MÈ
h…hhX,
Normally, we make implementation declarations as part of a class
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:h~jh”]r)(hœXýNormally, we make implementation declarations as part of a class
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 r*…r+}r,(hXýNormally, we make implementation declarations as part of a class
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 h~j&ubj¥
)r-}r.(hX`classImplements`hj¨
h}r/(h
]h	]h]h]h
]uh~j&h”]r0hœXclassImplementsr1…r2}r3(hUh~j-ubaubhœX can
be used for this purpose:r4…r5}r6(hX can
be used for this purpose:h~j&ubeubj
)r7}r8(hhhj“
h}r9(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r:j˜
ah]j™
}h]uh„MÎ
h…hhX”>>> class C:
...     pass

>>> zope.interface.classImplements(C, IFoo)
>>> list(zope.interface.implementedBy(C))
[<InterfaceClass __builtin__.IFoo>]h~jh”]r;hœX”>>> class C:
...     pass

>>> zope.interface.classImplements(C, IFoo)
>>> list(zope.interface.implementedBy(C))
[<InterfaceClass __builtin__.IFoo>]r<…r=}r>(hUh~j7ubaubh)r?}r@(hhhh‚h}rA(h
]h	]h]h]h
]uh„M×
h…hhXAWe can use `classImplementsOnly` to exclude inherited interfaces:rBh~jh”]rC(hœXWe can use rD…rE}rF(hXWe can use h~j?ubj¥
)rG}rH(hX`classImplementsOnly`hj¨
h}rI(h
]h	]h]h]h
]uh~j?h”]rJhœXclassImplementsOnlyrK…rL}rM(hUh~jGubaubhœX! to exclude inherited interfaces:rN…rO}rP(hX! to exclude inherited interfaces:h~j?ubeubj
)rQ}rR(hhhj“
h}rS(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rTj˜
ah]j™
}h]uh„MÙ
h…hhX¥>>> class C(Foo):
...     pass

>>> zope.interface.classImplementsOnly(C, ISpecial)
>>> list(zope.interface.implementedBy(C))
[<InterfaceClass __builtin__.ISpecial>]h~jh”]rUhœX¥>>> class C(Foo):
...     pass

>>> zope.interface.classImplementsOnly(C, ISpecial)
>>> list(zope.interface.implementedBy(C))
[<InterfaceClass __builtin__.ISpecial>]rV…rW}rX(hUh~jQubaubeubh†)rY}rZ(hhhh‰h}r[(h
]h	]h]r\hah]r]Udeclaration-objectsr^ah
]uh„Må
h…hhUh~hÝh”]r_(h–)r`}ra(hhhh7h}rb(h
]h	]h]h]h
]uh„Må
h…hhXDeclaration Objectsrch~jYh”]rdhœXDeclaration Objectsre…rf}rg(hjch~j`ubaubh)rh}ri(hhhh‚h}rj(h
]h	]h]h]h
]uh„Mç
h…hhX{When we declare interfaces, we create *declaration* objects.  When we
query declarations, declaration objects are returned:h~jYh”]rk(hœX&When we declare interfaces, we create rl…rm}rn(hX&When we declare interfaces, we create h~jhubhó)ro}rp(hX
*declaration*hhöh}rq(h
]h	]h]h]h
]uh~jhh”]rrhœXdeclarationrs…rt}ru(hUh~joubaubhœXH objects.  When we
query declarations, declaration objects are returned:rv…rw}rx(hXH objects.  When we
query declarations, declaration objects are returned:h~jhubeubj
)ry}rz(hhhj“
h}r{(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r|j˜
ah]j™
}h]uh„Mê
h…hhX`>>> type(zope.interface.implementedBy(Special))
<class 'zope.interface.declarations.Implements'>h~jYh”]r}hœX`>>> type(zope.interface.implementedBy(Special))
<class 'zope.interface.declarations.Implements'>r~…r}r€(hUh~jyubaubh)r}r‚(hhhh‚h}rƒ(h
]h	]h]h]h
]uh„Mï
h…hhX÷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:r„h~jYh”]r…hœX÷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:r†…r‡}rˆ(hj„h~jubaubj
)r‰}rŠ(hhhj“
h}r‹(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rŒj˜
ah]j™
}h]uh„Mô
h…hhX
>>> class Special2(Foo):
...     zope.interface.implementsOnly(
...          zope.interface.implementedBy(Foo),
...          ISpecial,
...          )
...     reason = 'I just am'
...     def brag(self):
...         return "I'm special because %s" % self.reasonh~jYh”]rhœX
>>> class Special2(Foo):
...     zope.interface.implementsOnly(
...          zope.interface.implementedBy(Foo),
...          ISpecial,
...          )
...     reason = 'I just am'
...     def brag(self):
...         return "I'm special because %s" % self.reasonrŽ…r}r(hUh~j‰ubaubh)r‘}r’(hhhh‚h}r“(h
]h	]h]h]h
]uh„Mÿ
h…hhX¢The declaration here is almost the same as
``zope.interface.implements(ISpecial)``, except that the order of
interfaces in the resulting declaration is different:h~jYh”]r”(hœX+The declaration here is almost the same as
r•…r–}r—(hX+The declaration here is almost the same as
h~j‘ubcdocutils.nodes
literal
r˜)r™}rš(hX'``zope.interface.implements(ISpecial)``hUliteralr›h}rœ(h
]h	]h]h]h
]uh~j‘h”]rhœX#zope.interface.implements(ISpecial)rž…rŸ}r (hUh~j™ubaubhœXP, except that the order of
interfaces in the resulting declaration is different:r¡…r¢}r£(hXP, except that the order of
interfaces in the resulting declaration is different:h~j‘ubeubj
)r¤}r¥(hhhj“
h}r¦(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r§j˜
ah]j™
}h]uh„Mh…hhX{>>> list(zope.interface.implementedBy(Special2))
[<InterfaceClass __builtin__.IFoo>, <InterfaceClass __builtin__.ISpecial>]h~jYh”]r¨hœX{>>> list(zope.interface.implementedBy(Special2))
[<InterfaceClass __builtin__.IFoo>, <InterfaceClass __builtin__.ISpecial>]r©…rª}r«(hUh~j¤ubaubeubeubh†)r¬}r­(hhhh‰h}r®(h
]h	]h]r¯h'ah]r°Uinterface-inheritancer±ah
]uh„M
h…hhUh~hŽh”]r²(h–)r³}r´(hhhh7h}rµ(h
]h	]h]h]h
]uh„M
h…hhXInterface Inheritancer¶h~j¬h”]r·hœXInterface Inheritancer¸…r¹}rº(hj¶h~j³ubaubh)r»}r¼(hhhh‚h}r½(h
]h	]h]h]h
]uh„Mh…hhXoInterfaces can extend other interfaces. They do this simply by listing
the other interfaces as base interfaces:r¾h~j¬h”]r¿hœXoInterfaces can extend other interfaces. They do this simply by listing
the other interfaces as base interfaces:rÀ…rÁ}rÂ(hj¾h~j»ubaubj
)rÃ}rÄ(hhhj“
h}rÅ(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rÆj˜
ah]j™
}h]uh„Mh…hhX
>>> class IBlat(zope.interface.Interface):
...     """Blat blah blah"""
...
...     y = zope.interface.Attribute("y blah blah")
...     def eek():
...         """eek blah blah"""

>>> IBlat.__bases__
(<InterfaceClass zope.interface.Interface>,)

>>> class IBaz(IFoo, IBlat):
...     """Baz blah"""
...     def eek(a=1):
...         """eek in baz blah"""
...

>>> IBaz.__bases__
(<InterfaceClass __builtin__.IFoo>, <InterfaceClass __builtin__.IBlat>)

>>> names = list(IBaz)
>>> names.sort()
>>> names
['bar', 'eek', 'x', 'y']h~j¬h”]rÇhœX
>>> class IBlat(zope.interface.Interface):
...     """Blat blah blah"""
...
...     y = zope.interface.Attribute("y blah blah")
...     def eek():
...         """eek blah blah"""

>>> IBlat.__bases__
(<InterfaceClass zope.interface.Interface>,)

>>> class IBaz(IFoo, IBlat):
...     """Baz blah"""
...     def eek(a=1):
...         """eek in baz blah"""
...

>>> IBaz.__bases__
(<InterfaceClass __builtin__.IFoo>, <InterfaceClass __builtin__.IBlat>)

>>> names = list(IBaz)
>>> names.sort()
>>> names
['bar', 'eek', 'x', 'y']rÈ…rÉ}rÊ(hUh~jÃubaubh)rË}rÌ(hhhh‚h}rÍ(h
]h	]h]h]h
]uh„M)h…hhXNote that `IBaz` overrides eek:rÎh~j¬h”]rÏ(hœX
Note that rÐ…rÑ}rÒ(hX
Note that h~jËubj¥
)rÓ}rÔ(hX`IBaz`hj¨
h}rÕ(h
]h	]h]h]h
]uh~jËh”]rÖhœXIBazr×…rØ}rÙ(hUh~jÓubaubhœX overrides eek:rÚ…rÛ}rÜ(hX overrides eek:h~jËubeubj
)rÝ}rÞ(hhhj“
h}rß(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]ràj˜
ah]j™
}h]uh„M+h…hhXR>>> IBlat['eek'].__doc__
'eek blah blah'
>>> IBaz['eek'].__doc__
'eek in baz blah'h~j¬h”]ráhœXR>>> IBlat['eek'].__doc__
'eek blah blah'
>>> IBaz['eek'].__doc__
'eek in baz blah'r⅁rã}rä(hUh~jÝubaubh)rå}ræ(hhhh‚h}rç(h
]h	]h]h]h
]uh„M2h…hhX¨We were careful to override eek in a compatible way.  When extending
an interface, the extending interface should be compatible [#compat]_
with the extended interfaces.h~j¬h”]rè(hœX€We were careful to override eek in a compatible way.  When extending
an interface, the extending interface should be compatible r酁rê}rë(hX€We were careful to override eek in a compatible way.  When extending
an interface, the extending interface should be compatible h~jåubhs)rì}rí(hhvh}rî(h	]h
]hxUcompatrïh
]h]rðUid3rñah|K
h]uhX
[#compat]_h}K
h~jåh”]ròhœX
3…ró}rô(hUh~jìubaubhœX
with the extended interfaces.rõ…rö}r÷(hX
with the extended interfaces.h~jåubeubh)rø}rù(hhhh‚h}rú(h
]h	]h]h]h
]uh„M6h…hhX1We can ask whether one interface extends another:rûh~j¬h”]rühœX1We can ask whether one interface extends another:rý…rþ}rÿ(hjûh~jøubaubj
)r}r
(hhhj“
h}r(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rj˜
ah]j™
}h]uh„M8h…hhX9>>> IBaz.extends(IFoo)
True
>>> IBlat.extends(IFoo)
Falseh~j¬h”]rhœX9>>> IBaz.extends(IFoo)
True
>>> IBlat.extends(IFoo)
Falser…r}r(hUh~jubaubh)r}r	(hhhh‚h}r
(h
]h	]h]h]h
]uh„M?h…hhX-Note that interfaces don't extend themselves:rh~j¬h”]rhœX-Note that interfaces don't extend themselves:r
…r}r(hjh~jubaubj
)r}r(hhhj“
h}r(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rj˜
ah]j™
}h]uh„MAh…hhX>>> IBaz.extends(IBaz)
Falseh~j¬h”]rhœX>>> IBaz.extends(IBaz)
Falser…r}r(hUh~jubaubh)r}r(hhhh‚h}r(h
]h	]h]h]h
]uh„MFh…hhXBSometimes we wish they did, but we can, instead use `isOrExtends`:rh~j¬h”]r(hœX4Sometimes we wish they did, but we can, instead use r…r}r(hX4Sometimes we wish they did, but we can, instead use h~jubj¥
)r }r!(hX
`isOrExtends`hj¨
h}r"(h
]h	]h]h]h
]uh~jh”]r#hœXisOrExtendsr$…r%}r&(hUh~j ubaubhœX
:…r'}r((hX
:h~jubeubj
)r)}r*(hhhj“
h}r+(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r,j˜
ah]j™
}h]uh„MHh…hhX`>>> IBaz.isOrExtends(IBaz)
True
>>> IBaz.isOrExtends(IFoo)
True
>>> IFoo.isOrExtends(IBaz)
Falseh~j¬h”]r-hœX`>>> IBaz.isOrExtends(IBaz)
True
>>> IBaz.isOrExtends(IFoo)
True
>>> IFoo.isOrExtends(IBaz)
Falser.…r/}r0(hUh~j)ubaubh)r1}r2(hhhh‚h}r3(h
]h	]h]h]h
]uh„MQh…hhXâ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:h~j¬h”]r4(hœX†When we iterate over an interface, we get all of the names it defines,
including names defined by base interfaces. Sometimes, we want r5…r6}r7(hX†When we iterate over an interface, we get all of the names it defines,
including names defined by base interfaces. Sometimes, we want h~j1ubhó)r8}r9(hX*just*hhöh}r:(h
]h	]h]h]h
]uh~j1h”]r;hœXjustr<…r=}r>(hUh~j8ubaubhœX>
the names defined by the interface directly. We bane use the r?…r@}rA(hX>
the names defined by the interface directly. We bane use the h~j1ubj¥
)rB}rC(hX`names`hj¨
h}rD(h
]h	]h]h]h
]uh~j1h”]rEhœXnamesrF…rG}rH(hUh~jBubaubhœX
method for that:rI…rJ}rK(hX
method for that:h~j1ubeubj
)rL}rM(hhhj“
h}rN(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rOj˜
ah]j™
}h]uh„MVh…hhX>>> list(IBaz.names())
['eek']h~j¬h”]rPhœX>>> list(IBaz.names())
['eek']rQ…rR}rS(hUh~jLubaubh†)rT}rU(hhhh‰h}rV(h
]h	]h]rWhah]rXU'inheritance-of-attribute-specificationsrYah
]uh„M\h…hhUh~j¬h”]rZ(h–)r[}r\(hhhh7h}r](h
]h	]h]h]h
]uh„M\h…hhX'Inheritance of attribute specificationsr^h~jTh”]r_hœX'Inheritance of attribute specificationsr`…ra}rb(hj^h~j[ubaubh)rc}rd(hhhh‚h}re(h
]h	]h]h]h
]uh„M^h…hhXÇ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:rfh~jTh”]rghœXÇ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:rh…ri}rj(hjfh~jcubaubj
)rk}rl(hhhj“
h}rm(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rnj˜
ah]j™
}h]uh„Mbh…hhXþ>>> class IBase(zope.interface.Interface):
...
...     def foo():
...         "base foo doc"

>>> class IBase1(IBase):
...     pass

>>> class IBase2(IBase):
...
...     def foo():
...         "base2 foo doc"

>>> class ISub(IBase1, IBase2):
...     passh~jTh”]rohœXþ>>> class IBase(zope.interface.Interface):
...
...     def foo():
...         "base foo doc"

>>> class IBase1(IBase):
...     pass

>>> class IBase2(IBase):
...
...     def foo():
...         "base2 foo doc"

>>> class ISub(IBase1, IBase2):
...     passrp…rq}rr(hUh~jkubaubh)rs}rt(hhhh‚h}ru(h
]h	]h]h]h
]uh„Mth…hhXZISub's definition of foo is the one from IBase2, since IBase2 is more
specific that IBase:rvh~jTh”]rwhœXZISub's definition of foo is the one from IBase2, since IBase2 is more
specific that IBase:rx…ry}rz(hjvh~jsubaubj
)r{}r|(hhhj“
h}r}(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r~j˜
ah]j™
}h]uh„Mwh…hhX'>>> ISub['foo'].__doc__
'base2 foo doc'h~jTh”]rhœX'>>> ISub['foo'].__doc__
'base2 foo doc'r€…r}r‚(hUh~j{ubaubh)rƒ}r„(hhhh‚h}r…(h
]h	]h]h]h
]uh„M|h…hhX1Note that this differs from a depth-first search.r†h~jTh”]r‡hœX1Note that this differs from a depth-first search.rˆ…r‰}rŠ(hj†h~jƒubaubh)r‹}rŒ(hhhh‚h}r(h
]h	]h]h]h
]uh„M~h…hhX—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:rŽh~jTh”]rhœX—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:r…r‘}r’(hjŽh~j‹ubaubj
)r“}r”(hhhj“
h}r•(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r–j˜
ah]j™
}h]uh„M‚h…hhXF>>> IBase.direct('foo').__doc__
'base foo doc'

>>> ISub.direct('foo')h~jTh”]r—hœXF>>> IBase.direct('foo').__doc__
'base foo doc'

>>> ISub.direct('foo')r˜…r™}rš(hUh~j“ubaubeubh†)r›}rœ(hhhh‰h}r(h
]h	]h]ržhah]rŸUspecificationsr ah
]uh„MŠh…hhUh~j¬h”]r¡(h–)r¢}r£(hhhh7h}r¤(h
]h	]h]h]h
]uh„MŠh…hhXSpecificationsr¥h~j›h”]r¦hœXSpecificationsr§…r¨}r©(hj¥h~j¢ubaubh)rª}r«(hhhh‚h}r¬(h
]h	]h]h]h
]uh„MŒh…hhXè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:r­h~j›h”]r®hœXè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:r¯…r°}r±(hj­h~jªubaubj
)r²}r³(hhhj“
h}r´(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rµj˜
ah]j™
}h]uh„M‘h…hhXX
>>> class Baz(object):
...     zope.interface.implements(IBaz)

>>> baz_implements = zope.interface.implementedBy(Baz)
>>> baz_implements.__bases__
(<InterfaceClass __builtin__.IBaz>, <implementedBy ...object>)

>>> baz_implements.extends(IFoo)
True

>>> baz_implements.isOrExtends(IFoo)
True
>>> baz_implements.isOrExtends(baz_implements)
Trueh~j›h”]r¶hœXX
>>> class Baz(object):
...     zope.interface.implements(IBaz)

>>> baz_implements = zope.interface.implementedBy(Baz)
>>> baz_implements.__bases__
(<InterfaceClass __builtin__.IBaz>, <implementedBy ...object>)

>>> baz_implements.extends(IFoo)
True

>>> baz_implements.isOrExtends(IFoo)
True
>>> baz_implements.isOrExtends(baz_implements)
Truer·…r¸}r¹(hUh~j²ubaubh)rº}r»(hhhh‚h}r¼(h
]h	]h]h]h
]uh„M¢h…hhXySpecifications (interfaces and declarations) provide an `__sro__`
that lists the specification and all of it's ancestors:h~j›h”]r½(hœX8Specifications (interfaces and declarations) provide an r¾…r¿}rÀ(hX8Specifications (interfaces and declarations) provide an h~jºubj¥
)rÁ}rÂ(hX	`__sro__`hj¨
h}rÃ(h
]h	]h]h]h
]uh~jºh”]rÄhœX__sro__rÅ…rÆ}rÇ(hUh~jÁubaubhœX8
that lists the specification and all of it's ancestors:rÈ…rÉ}rÊ(hX8
that lists the specification and all of it's ancestors:h~jºubeubj
)rË}rÌ(hhhj“
h}rÍ(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rÎj˜
ah]j™
}h]uh„M¥h…hhX
>>> 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>)h~j›h”]rÏhœX
>>> 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>)rÐ…rÑ}rÒ(hUh~jËubaubeubeubh†)rÓ}rÔ(hhhh‰h}rÕ(h
]h	]h]rÖhah]r×U
tagged-valuesrØah
]uh„M²h…hhUh~hŽh”]rÙ(h–)rÚ}rÛ(hhhh7h}rÜ(h
]h	]h]h]h
]uh„M²h…hhX
Tagged ValuesrÝh~jÓh”]rÞhœX
Tagged Valuesrß…rà}rá(hjÝh~jÚubaubh)râ}rã(hhhh‚h}rä(h
]h	]h]h]h
]uh„M´h…hhXŽInterfaces and attribute descriptions support an extension mechanism,
borrowed from UML, called "tagged values" that lets us store extra
data:råh~jÓh”]ræhœXŽInterfaces and attribute descriptions support an extension mechanism,
borrowed from UML, called "tagged values" that lets us store extra
data:r煁rè}ré(hjåh~jâubaubj
)rê}rë(hhhj“
h}rì(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]ríj˜
ah]j™
}h]uh„M¸h…hhX^
>>> IFoo.setTaggedValue('date-modified', '2004-04-01')
>>> IFoo.setTaggedValue('author', 'Jim Fulton')
>>> IFoo.getTaggedValue('date-modified')
'2004-04-01'
>>> IFoo.queryTaggedValue('date-modified')
'2004-04-01'
>>> IFoo.queryTaggedValue('datemodified')
>>> tags = list(IFoo.getTaggedValueTags())
>>> tags.sort()
>>> tags
['author', 'date-modified']h~jÓh”]rîhœX^
>>> IFoo.setTaggedValue('date-modified', '2004-04-01')
>>> IFoo.setTaggedValue('author', 'Jim Fulton')
>>> IFoo.getTaggedValue('date-modified')
'2004-04-01'
>>> IFoo.queryTaggedValue('date-modified')
'2004-04-01'
>>> IFoo.queryTaggedValue('datemodified')
>>> tags = list(IFoo.getTaggedValueTags())
>>> tags.sort()
>>> tags
['author', 'date-modified']rrð}rñ(hUh~jêubaubh)rò}ró(hhhh‚h}rô(h
]h	]h]h]h
]uh„MÆh…hhXaFunction attributes are converted to tagged values when method
attribute definitions are created:rõh~jÓh”]röhœXaFunction attributes are converted to tagged values when method
attribute definitions are created:r÷…rø}rù(hjõh~jòubaubj
)rú}rû(hhhj“
h}rü(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rýj˜
ah]j™
}h]uh„MÉh…hhXâ>>> class IBazFactory(zope.interface.Interface):
...     def __call__():
...         "create one"
...     __call__.return_type = IBaz

>>> IBazFactory['__call__'].getTaggedValue('return_type')
<InterfaceClass __builtin__.IBaz>h~jÓh”]rþhœXâ>>> class IBazFactory(zope.interface.Interface):
...     def __call__():
...         "create one"
...     __call__.return_type = IBaz

>>> IBazFactory['__call__'].getTaggedValue('return_type')
<InterfaceClass __builtin__.IBaz>rÿ…r}r
(hUh~júubaubh)r}r(hhhh‚h}r(h
]h	]h]h]h
]uh„MÓh…hhXFTagged values can also be defined from within an interface definition:rh~jÓh”]rhœXFTagged values can also be defined from within an interface definition:r…r}r	(hjh~jubaubj
)r
}r(hhhj“
h}r(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r
j˜
ah]j™
}h]uh„MÕh…hhX¥>>> class IWithTaggedValues(zope.interface.Interface):
...     zope.interface.taggedValue('squish', 'squash')
>>> IWithTaggedValues.getTaggedValue('squish')
'squash'h~jÓh”]rhœX¥>>> class IWithTaggedValues(zope.interface.Interface):
...     zope.interface.taggedValue('squish', 'squash')
>>> IWithTaggedValues.getTaggedValue('squish')
'squash'r…r}r(hUh~j
ubaubeubh†)r}r(hhhh‰h}r(h
]h	]h]rhah]rU
invariantsrah
]uh„MÝh…hhUh~hŽh”]r(h–)r}r(hhhh7h}r(h
]h	]h]h]h
]uh„MÝh…hhX
Invariantsrh~jh”]rhœX
Invariantsr…r}r (hjh~jubaubh)r!}r"(hhhh‚h}r#(h
]h	]h]h]h
]uh„Mßh…hhXJ
Interfaces can express conditions that must hold for objects that
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:h~jh”]r$(hœX
Interfaces can express conditions that must hold for objects that
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 r%…r&}r'(hX
Interfaces can express conditions that must hold for objects that
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 h~j!ubj¥
)r(}r)(hX	`Invalid`hj¨
h}r*(h
]h	]h]h]h
]uh~j!h”]r+hœXInvalidr,…r-}r.(hUh~j(ubaubhœX=
exception if the condition doesn't hold.  Here's an example:r/…r0}r1(hX=
exception if the condition doesn't hold.  Here's an example:h~j!ubeubj
)r2}r3(hhhj“
h}r4(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r5j˜
ah]j™
}h]uh„Måh…hhXý>>> class RangeError(zope.interface.Invalid):
...     """A range has invalid limits"""
...     def __repr__(self):
...         return "RangeError(%r)" % self.args

>>> def range_invariant(ob):
...     if ob.max < ob.min:
...         raise RangeError(ob)h~jh”]r6hœXý>>> class RangeError(zope.interface.Invalid):
...     """A range has invalid limits"""
...     def __repr__(self):
...         return "RangeError(%r)" % self.args

>>> def range_invariant(ob):
...     if ob.max < ob.min:
...         raise RangeError(ob)r7…r8}r9(hUh~j2ubaubh)r:}r;(hhhh‚h}r<(h
]h	]h]h]h
]uh„Mðh…hhX?Given this invariant, we can use it in an interface definition:r=h~jh”]r>hœX?Given this invariant, we can use it in an interface definition:r?…r@}rA(hj=h~j:ubaubj
)rB}rC(hhhj“
h}rD(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rEj˜
ah]j™
}h]uh„Mòh…hhXÍ>>> class IRange(zope.interface.Interface):
...     min = zope.interface.Attribute("Lower bound")
...     max = zope.interface.Attribute("Upper bound")
...
...     zope.interface.invariant(range_invariant)h~jh”]rFhœXÍ>>> class IRange(zope.interface.Interface):
...     min = zope.interface.Attribute("Lower bound")
...     max = zope.interface.Attribute("Upper bound")
...
...     zope.interface.invariant(range_invariant)rG…rH}rI(hUh~jBubaubh)rJ}rK(hhhh‚h}rL(h
]h	]h]h]h
]uh„Múh…hhX7Interfaces have a method for checking their invariants:rMh~jh”]rNhœX7Interfaces have a method for checking their invariants:rO…rP}rQ(hjMh~jJubaubj
)rR}rS(hhhj“
h}rT(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rUj˜
ah]j™
}h]uh„Müh…hhX®
>>> class Range(object):
...     zope.interface.implements(IRange)
...
...     def __init__(self, min, max):
...         self.min, self.max = min, max
...
...     def __repr__(self):
...         return "Range(%s, %s)" % (self.min, self.max)

>>> IRange.validateInvariants(Range(1,2))
>>> IRange.validateInvariants(Range(1,1))
>>> IRange.validateInvariants(Range(2,1))
Traceback (most recent call last):
...
RangeError: Range(2, 1)h~jh”]rVhœX®
>>> class Range(object):
...     zope.interface.implements(IRange)
...
...     def __init__(self, min, max):
...         self.min, self.max = min, max
...
...     def __repr__(self):
...         return "Range(%s, %s)" % (self.min, self.max)

>>> IRange.validateInvariants(Range(1,2))
>>> IRange.validateInvariants(Range(1,1))
>>> IRange.validateInvariants(Range(2,1))
Traceback (most recent call last):
...
RangeError: Range(2, 1)rW…rX}rY(hUh~jRubaubh)rZ}r[(hhhh‚h}r\(h
]h	]h]h]h
]uh„Mh…hhXå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:h~jh”]r](hœXqIf you have multiple invariants, you may not want to stop checking
after the first error.  If you pass a list to r^…r_}r`(hXqIf you have multiple invariants, you may not want to stop checking
after the first error.  If you pass a list to h~jZubj¥
)ra}rb(hX`validateInvariants`hj¨
h}rc(h
]h	]h]h]h
]uh~jZh”]rdhœXvalidateInvariantsre…rf}rg(hUh~jaubaubhœX,
then a single rh…ri}rj(hX,
then a single h~jZubj¥
)rk}rl(hX	`Invalid`hj¨
h}rm(h
]h	]h]h]h
]uh~jZh”]rnhœXInvalidro…rp}rq(hUh~jkubaubhœXG exception will be raised with the list of
exceptions as it's argument:rr…rs}rt(hXG exception will be raised with the list of
exceptions as it's argument:h~jZubeubj
)ru}rv(hhhj“
h}rw(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rxj˜
ah]j™
}h]uh„Mh…hhXÂ>>> from zope.interface.exceptions import Invalid
>>> errors = []
>>> try:
...     IRange.validateInvariants(Range(2,1), errors)
... except Invalid, e:
...     str(e)
'[RangeError(Range(2, 1))]'h~jh”]ryhœXÂ>>> from zope.interface.exceptions import Invalid
>>> errors = []
>>> try:
...     IRange.validateInvariants(Range(2,1), errors)
... except Invalid, e:
...     str(e)
'[RangeError(Range(2, 1))]'rz…r{}r|(hUh~juubaubh)r}}r~(hhhh‚h}r(h
]h	]h]h]h
]uh„Mh…hhX;And the list will be filled with the individual exceptions:r€h~jh”]rhœX;And the list will be filled with the individual exceptions:r‚…rƒ}r„(hj€h~j}ubaubj
)r…}r†(hhhj“
h}r‡(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rˆj˜
ah]j™
}h]uh„Mh…hhX8>>> errors
[RangeError(Range(2, 1))]


>>> del errors[:]h~jh”]r‰hœX8>>> errors
[RangeError(Range(2, 1))]


>>> del errors[:]rŠ…r‹}rŒ(hUh~j…ubaubeubh†)r}rŽ(hhhh‰h}r(h
]h	]h]rh(ah]r‘U
adaptationr’ah
]uh„M(h…hhUh~hŽh”]r“(h–)r”}r•(hhhh7h}r–(h
]h	]h]h]h
]uh„M(h…hhX
Adaptationr—h~jh”]r˜hœX
Adaptationr™…rš}r›(hj—h~j”ubaubh)rœ}r(hhhh‚h}rž(h
]h	]h]h]h
]uh„M*h…hhX/Interfaces can be called to perform adaptation.rŸh~jh”]r hœX/Interfaces can be called to perform adaptation.r¡…r¢}r£(hjŸh~jœubaubh)r¤}r¥(hhhh‚h}r¦(h
]h	]h]h]h
]uh„M,h…hhX?The semantics are based on those of the PEP 246 adapt function.r§h~jh”]r¨hœX?The semantics are based on those of the PEP 246 adapt function.r©…rª}r«(hj§h~j¤ubaubh)r¬}r­(hhhh‚h}r®(h
]h	]h]h]h
]uh„M.h…hhX;If an object cannot be adapted, then a TypeError is raised:r¯h~jh”]r°hœX;If an object cannot be adapted, then a TypeError is raised:r±…r²}r³(hj¯h~j¬ubaubj
)r´}rµ(hhhj“
h}r¶(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r·j˜
ah]j™
}h]uh„M0h…hhX¦>>> class I(zope.interface.Interface):
...     pass

>>> I(0)
Traceback (most recent call last):
...
TypeError: ('Could not adapt', 0, <InterfaceClass __builtin__.I>)h~jh”]r¸hœX¦>>> class I(zope.interface.Interface):
...     pass

>>> I(0)
Traceback (most recent call last):
...
TypeError: ('Could not adapt', 0, <InterfaceClass __builtin__.I>)r¹…rº}r»(hUh~j´ubaubh)r¼}r½(hhhh‚h}r¾(h
]h	]h]h]h
]uh„M<h…hhXFunless an alternate value is provided as a second positional argument:r¿h~jh”]rÀhœXFunless an alternate value is provided as a second positional argument:rÁ…rÂ}rÃ(hj¿h~j¼ubaubj
)rÄ}rÅ(hhhj“
h}rÆ(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rÇj˜
ah]j™
}h]uh„M>h…hhX>>> I(0, 'bob')
'bob'h~jh”]rÈhœX>>> I(0, 'bob')
'bob'rÉ…rÊ}rË(hUh~jÄubaubh)rÌ}rÍ(hhhh‚h}rÎ(h
]h	]h]h]h
]uh„MCh…hhXHIf an object already implements the interface, then it will be returned:rÏh~jh”]rÐhœXHIf an object already implements the interface, then it will be returned:rÑ…rÒ}rÓ(hjÏh~jÌubaubj
)rÔ}rÕ(hhhj“
h}rÖ(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r×j˜
ah]j™
}h]uh„MEh…hhX_>>> class C(object):
...     zope.interface.implements(I)

>>> obj = C()
>>> I(obj) is obj
Trueh~jh”]rØhœX_>>> class C(object):
...     zope.interface.implements(I)

>>> obj = C()
>>> I(obj) is obj
TruerÙ…rÚ}rÛ(hUh~jÔubaubh)rÜ}rÝ(hhhh‚h}rÞ(h
]h	]h]h]h
]uh„MNh…hhX:If an object implements __conform__, then it will be used:rßh~jh”]ràhœX:If an object implements __conform__, then it will be used:rᅁrâ}rã(hjßh~jÜubaubj
)rä}rå(hhhj“
h}ræ(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rçj˜
ah]j™
}h]uh„MPh…hhXƒ>>> class C(object):
...     zope.interface.implements(I)
...     def __conform__(self, proto):
...          return 0

>>> I(C())
0h~jh”]rèhœXƒ>>> class C(object):
...     zope.interface.implements(I)
...     def __conform__(self, proto):
...          return 0

>>> I(C())
0r酁rê}rë(hUh~jäubaubh)rì}rí(hhhh‚h}rî(h
]h	]h]h]h
]uh„MZh…hhX<Adapter hooks (see __adapt__) will also be used, if present:rïh~jh”]rðhœX<Adapter hooks (see __adapt__) will also be used, if present:rñ…rò}ró(hjïh~jìubaubj
)rô}rõ(hhhj“
h}rö(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r÷j˜
ah]j™
}h]uh„M\h…hhXT
>>> from zope.interface.interface import adapter_hooks
>>> def adapt_0_to_42(iface, obj):
...     if obj == 0:
...         return 42

>>> adapter_hooks.append(adapt_0_to_42)
>>> I(0)
42

>>> adapter_hooks.remove(adapt_0_to_42)
>>> I(0)
Traceback (most recent call last):
...
TypeError: ('Could not adapt', 0, <InterfaceClass __builtin__.I>)h~jh”]røhœXT
>>> from zope.interface.interface import adapter_hooks
>>> def adapt_0_to_42(iface, obj):
...     if obj == 0:
...         return 42

>>> adapter_hooks.append(adapt_0_to_42)
>>> I(0)
42

>>> adapter_hooks.remove(adapt_0_to_42)
>>> I(0)
Traceback (most recent call last):
...
TypeError: ('Could not adapt', 0, <InterfaceClass __builtin__.I>)rù…rú}rû(hUh~jôubaubh†)rü}rý(hhhh‰h}rþ(h
]h	]h]rÿh!ah]rUadaptr
ah
]uh„Mnh…hhUh~jh”]r(h–)r}r(hhhh7h}r(h
]h	]h]h]h
]uh„Mnh…hhX	__adapt__rh~jüh”]rhœX	__adapt__r…r	}r
(hjh~jubaubj
)r}r(hhhj“
h}r
(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rj˜
ah]j™
}h]uh„Mph…hhX3>>> class I(zope.interface.Interface):
...     passh~jüh”]rhœX3>>> class I(zope.interface.Interface):
...     passr…r}r(hUh~jubaubh)r}r(hhhh‚h}r(h
]h	]h]h]h
]uh„Muh…hhX2Interfaces implement the PEP 246 __adapt__ method.rh~jüh”]rhœX2Interfaces implement the PEP 246 __adapt__ method.r…r}r(hjh~jubaubh)r}r(hhhh‚h}r(h
]h	]h]h]h
]uh„Mwh…hhX€This method is normally not called directly. It is called by the PEP
246 adapt framework and by the interface __call__ operator.rh~jüh”]rhœX€This method is normally not called directly. It is called by the PEP
246 adapt framework and by the interface __call__ operator.r …r!}r"(hjh~jubaubh)r#}r$(hhhh‚h}r%(h
]h	]h]h]h
]uh„Mzh…hhXGThe adapt method is responsible for adapting an object to the
reciever.r&h~jüh”]r'hœXGThe adapt method is responsible for adapting an object to the
reciever.r(…r)}r*(hj&h~j#ubaubh)r+}r,(hhhh‚h}r-(h
]h	]h]h]h
]uh„M}h…hhX!The default version returns None:r.h~jüh”]r/hœX!The default version returns None:r0…r1}r2(hj.h~j+ubaubj
)r3}r4(hhhj“
h}r5(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r6j˜
ah]j™
}h]uh„Mh…hhX>>> I.__adapt__(0)h~jüh”]r7hœX>>> I.__adapt__(0)r8…r9}r:(hUh~j3ubaubh)r;}r<(hhhh‚h}r=(h
]h	]h]h]h
]uh„Mƒh…hhX/unless the object given provides the interface:r>h~jüh”]r?hœX/unless the object given provides the interface:r@…rA}rB(hj>h~j;ubaubj
)rC}rD(hhhj“
h}rE(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rFj˜
ah]j™
}h]uh„M…h…hhXi>>> class C(object):
...     zope.interface.implements(I)

>>> obj = C()
>>> I.__adapt__(obj) is obj
Trueh~jüh”]rGhœXi>>> class C(object):
...     zope.interface.implements(I)

>>> obj = C()
>>> I.__adapt__(obj) is obj
TruerH…rI}rJ(hUh~jCubaubh)rK}rL(hhhh‚h}rM(h
]h	]h]h]h
]uh„MŽh…hhX¹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:rNh~jüh”]rOhœX¹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:rP…rQ}rR(hjNh~jKubaubj
)rS}rT(hhhj“
h}rU(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rVj˜
ah]j™
}h]uh„M“h…hhXÃ>>> from zope.interface.interface import adapter_hooks
>>> def adapt_0_to_42(iface, obj):
...     if obj == 0:
...         return 42

>>> adapter_hooks.append(adapt_0_to_42)
>>> I.__adapt__(0)
42h~jüh”]rWhœXÃ>>> from zope.interface.interface import adapter_hooks
>>> def adapt_0_to_42(iface, obj):
...     if obj == 0:
...         return 42

>>> adapter_hooks.append(adapt_0_to_42)
>>> I.__adapt__(0)
42rX…rY}rZ(hUh~jSubaubh)r[}r\(hhhh‚h}r](h
]h	]h]h]h
]uh„Mžh…hhXHHooks must either return an adapter, or None if no adapter can
be found.r^h~jüh”]r_hœXHHooks must either return an adapter, or None if no adapter can
be found.r`…ra}rb(hj^h~j[ubaubh)rc}rd(hhhh‚h}re(h
]h	]h]h]h
]uh„M¡h…hhX8Hooks can be uninstalled by removing them from the list:rfh~jüh”]rghœX8Hooks can be uninstalled by removing them from the list:rh…ri}rj(hjfh~jcubaubj
)rk}rl(hhhj“
h}rm(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rnj˜
ah]j™
}h]uh„M£h…hhX:>>> adapter_hooks.remove(adapt_0_to_42)
>>> I.__adapt__(0)h~jüh”]rohœX:>>> adapter_hooks.remove(adapt_0_to_42)
>>> I.__adapt__(0)rp…rq}rr(hUh~jkubaubcdocutils.nodes
footnote
rs)rt}ru(hhhUfootnotervh}rw(h	]h
]rxh{ah
]h]ryhyah|K
h]rzh#auh„M©h…hhX
The main reason we subclass `Interface` is to cause the
Python class statement to create an interface, rather
than a class.

It's possible to create interfaces by calling a special
interface class directly.  Doing this, it's possible
(and, on rare occasions, useful) to create interfaces
that don't descend from `Interface`.  Using this
technique is beyond the scope of this document.
h~jüh”]r{(cdocutils.nodes
label
r|)r}}r~(hhhUlabelrh}r€(h
]h	]h]h]h
]uh„Nh…NhUh~jth”]rhœX
1…r‚}rƒ(hUh~j}ubaubh)r„}r…(hh‚h}r†(h
]h	]h]h]h
]uh„M©h…hhX{The main reason we subclass `Interface` is to cause the
Python class statement to create an interface, rather
than a class.h~jth”]r‡(hœXThe main reason we subclass rˆ…r‰}rŠ(hXThe main reason we subclass h~j„ubj¥
)r‹}rŒ(hX`Interface`hj¨
h}r(h
]h	]h]h]h
]uh~j„h”]rŽhœX	Interfacer…r}r‘(hUh~j‹ubaubhœXT is to cause the
Python class statement to create an interface, rather
than a class.r’…r“}r”(hXT is to cause the
Python class statement to create an interface, rather
than a class.h~j„ubeubh)r•}r–(hh‚h}r—(h
]h	]h]h]h
]uh„M­h…hhX
It's possible to create interfaces by calling a special
interface class directly.  Doing this, it's possible
(and, on rare occasions, useful) to create interfaces
that don't descend from `Interface`.  Using this
technique is beyond the scope of this document.h~jth”]r˜(hœX»It's possible to create interfaces by calling a special
interface class directly.  Doing this, it's possible
(and, on rare occasions, useful) to create interfaces
that don't descend from r™…rš}r›(hX»It's possible to create interfaces by calling a special
interface class directly.  Doing this, it's possible
(and, on rare occasions, useful) to create interfaces
that don't descend from h~j•ubj¥
)rœ}r(hX`Interface`hj¨
h}rž(h
]h	]h]h]h
]uh~j•h”]rŸhœX	Interfacer …r¡}r¢(hUh~jœubaubhœX=.  Using this
technique is beyond the scope of this document.r£…r¤}r¥(hX=.  Using this
technique is beyond the scope of this document.h~j•ubeubeubjs)r¦}r§(hhhjvh}r¨(h	]h
]r©jZ
ah
]h]rªjX
ah|K
h]r«h%auh„M³h…hhXòClasses are factories.  They can be called to create
their instances.  We expect that we will eventually
extend the concept of implementation to other kinds of
factories, so that we can declare the interfaces
provided by the objects created.
h~jüh”]r¬(j|)r­}r®(hhhjh}r¯(h
]h	]h]h]h
]uh„Nh…NhUh~j¦h”]r°hœX
2…r±}r²(hUh~j­ubaubh)r³}r´(hh‚h}rµ(h
]h	]h]h]h
]uh„M³h…hhXñClasses are factories.  They can be called to create
their instances.  We expect that we will eventually
extend the concept of implementation to other kinds of
factories, so that we can declare the interfaces
provided by the objects created.r¶h~j¦h”]r·hœXñClasses are factories.  They can be called to create
their instances.  We expect that we will eventually
extend the concept of implementation to other kinds of
factories, so that we can declare the interfaces
provided by the objects created.r¸…r¹}rº(hj¶h~j³ubaubeubjs)r»}r¼(hhhjvh}r½(h	]h
]r¾jñah
]h]r¿jïah|K
h]rÀhauh„M¹h…hhXe
The goal is substitutability.  An object that provides an
extending interface should be substitutable for an object
that provides the extended interface.  In our example, an
object that provides IBaz should be usable whereever an
object that provides IBlat is expected.

The interface implementation doesn't enforce this.
but maybe it should do some checks.h~jüh”]rÁ(j|)rÂ}rÃ(hhhjh}rÄ(h
]h	]h]h]h
]uh„Nh…NhUh~j»h”]rÅhœX
3…rÆ}rÇ(hUh~jÂubaubh)rÈ}rÉ(hh‚h}rÊ(h
]h	]h]h]h
]uh„M¹h…hhX

The goal is substitutability.  An object that provides an
extending interface should be substitutable for an object
that provides the extended interface.  In our example, an
object that provides IBaz should be usable whereever an
object that provides IBlat is expected.rËh~j»h”]rÌhœX

The goal is substitutability.  An object that provides an
extending interface should be substitutable for an object
that provides the extended interface.  In our example, an
object that provides IBaz should be usable whereever an
object that provides IBlat is expected.rÍ…rÎ}rÏ(hjËh~jÈubaubh)rÐ}rÑ(hh‚h}rÒ(h
]h	]h]h]h
]uh„M¿h…hhXVThe interface implementation doesn't enforce this.
but maybe it should do some checks.rÓh~j»h”]rÔhœXVThe interface implementation doesn't enforce this.
but maybe it should do some checks.rÕ…rÖ}r×(hjÓh~jÐubaubeubeubeubeubh”]rØ(h–)rÙ}rÚ(hhhh7h}rÛ(h
]h	]h]h]h
]uh„Kh…hhXDefining interfacesrÜh~h‡h”]rÝhœXDefining interfacesrÞ…rß}rà(hjÜh~jÙubaubh)rá}râ(hhhh‚h}rã(h
]h	]h]h]h
]uh„Kh…hhX5Interfaces are defined using Python class statements:räh~h‡h”]råhœX5Interfaces are defined using Python class statements:r慁rç}rè(hjäh~jáubaubj
)ré}rê(hhhj“
h}rë(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rìj˜
ah]j™
}h]uh„Kh…hhX×>>> import zope.interface
>>> class IFoo(zope.interface.Interface):
...    """Foo blah blah"""
...
...    x = zope.interface.Attribute("""X blah blah""")
...
...    def bar(q, r=None):
...        """bar blah blah"""h~h‡h”]ríhœX×>>> import zope.interface
>>> class IFoo(zope.interface.Interface):
...    """Foo blah blah"""
...
...    x = zope.interface.Attribute("""X blah blah""")
...
...    def bar(q, r=None):
...        """bar blah blah"""rrï}rð(hUh~jéubaubh€j
)rñ}rò(hhhj“
h}ró(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rôj˜
ah]j™
}h]uh„K+h…hhX@>>> type(IFoo)
<class 'zope.interface.interface.InterfaceClass'>h~h‡h”]rõhœX@>>> type(IFoo)
<class 'zope.interface.interface.InterfaceClass'>rö…r÷}rø(hUh~jñubaubh)rù}rú(hhhh‚h}rû(h
]h	]h]h]h
]uh„K0h…hhX-We can ask for the interface's documentation:rüh~h‡h”]rýhœX-We can ask for the interface's documentation:rþ…rÿ}r(hjüh~jùubaubj
)r
}r(hhhj“
h}r(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rj˜
ah]j™
}h]uh„K2h…hhX >>> IFoo.__doc__
'Foo blah blah'h~h‡h”]rhœX >>> IFoo.__doc__
'Foo blah blah'r…r}r(hUh~j
ubaubh)r	}r
(hhhh‚h}r(h
]h	]h]h]h
]uh„K7h…hhX
and its name:rh~h‡h”]r
hœX
and its name:r…r}r(hjh~j	ubaubj
)r}r(hhhj“
h}r(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rj˜
ah]j™
}h]uh„K9h…hhX>>> IFoo.__name__
'IFoo'h~h‡h”]rhœX>>> IFoo.__name__
'IFoo'r…r}r(hUh~jubaubh)r}r(hhhh‚h}r(h
]h	]h]h]h
]uh„K>h…hhXand even its module:rh~h‡h”]rhœXand even its module:r…r}r (hjh~jubaubj
)r!}r"(hhhj“
h}r#(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r$j˜
ah]j™
}h]uh„K@h…hhX!>>> IFoo.__module__
'__builtin__'h~h‡h”]r%hœX!>>> IFoo.__module__
'__builtin__'r&…r'}r((hUh~j!ubaubh)r)}r*(hhhh‚h}r+(h
]h	]h]h]h
]uh„KEh…hhX%The interface defined two attributes:r,h~h‡h”]r-hœX%The interface defined two attributes:r.…r/}r0(hj,h~j)ubaubhÿ)r1}r2(hhhj
h}r3(h
]h	]h]h]h
]uh„Nh…hhUh~h‡h”]r4(j
)r5}r6(hj
h}r7(h
]h	]h]h]h
]uh„KIh…hhX„`x`
This is the simplest form of attribute definition.  It has a name
and a doc string.  It doesn't formally specify anything else.
h~j1h”]r8(j
)r9}r:(hj
h}r;(h
]h	]h]h]h
]uh„KIh…hhX`x`r<h~j5h”]r=j¥
)r>}r?(hj<hj¨
h}r@(h
]h	]h]h]h
]uh~j9h”]rAhœX
x…rB}rC(hUh~j>ubaubaubj
)rD}rE(hUhj
h}rF(h
]h	]h]h]h
]uh~j5h”]rGh)rH}rI(hh‚h}rJ(h
]h	]h]h]h
]uh„KHh…hhXThis is the simplest form of attribute definition.  It has a name
and a doc string.  It doesn't formally specify anything else.rKh~jDh”]rLhœXThis is the simplest form of attribute definition.  It has a name
and a doc string.  It doesn't formally specify anything else.rM…rN}rO(hjKh~jHubaubaubeubj
)rP}rQ(hhhj
h}rR(h
]h	]h]h]h
]uh„KXh…hhX`bar`
This is a method.  A method is defined via a function definition.  A
method is simply an attribute constrained to be a callable with a
particular signature, as provided by the function definition.

Note that `bar` doesn't take a `self` argument.  Interfaces document
how an object is *used*.  When calling instance methods, you don't
pass a `self` argument, so a `self` argument isn't included in the
interface signature.  The `self` argument in instance methods is
really an implementation detail of Python instances. Other objects,
besides instances can provide interfaces and their methods might not
be instance methods. For example, modules can provide interfaces and
their methods are usually just functions.  Even instances can have
methods that are not instance methods.
h~j1h”]rS(j
)rT}rU(hj
h}rV(h
]h	]h]h]h
]uh„KXh…hhX`bar`rWh~jPh”]rXj¥
)rY}rZ(hjWhj¨
h}r[(h
]h	]h]h]h
]uh~jTh”]r\hœXbarr]…r^}r_(hUh~jYubaubaubj
)r`}ra(hUhj
h}rb(h
]h	]h]h]h
]uh~jPh”]rc(h)rd}re(hh‚h}rf(h
]h	]h]h]h
]uh„KLh…hhXÄThis is a method.  A method is defined via a function definition.  A
method is simply an attribute constrained to be a callable with a
particular signature, as provided by the function definition.rgh~j`h”]rhhœXÄThis is a method.  A method is defined via a function definition.  A
method is simply an attribute constrained to be a callable with a
particular signature, as provided by the function definition.ri…rj}rk(hjgh~jdubaubh)rl}rm(hh‚h}rn(h
]h	]h]h]h
]uh„KPh…hhXCNote that `bar` doesn't take a `self` argument.  Interfaces document
how an object is *used*.  When calling instance methods, you don't
pass a `self` argument, so a `self` argument isn't included in the
interface signature.  The `self` argument in instance methods is
really an implementation detail of Python instances. Other objects,
besides instances can provide interfaces and their methods might not
be instance methods. For example, modules can provide interfaces and
their methods are usually just functions.  Even instances can have
methods that are not instance methods.h~j`h”]ro(hœX
Note that rp…rq}rr(hX
Note that h~jlubj¥
)rs}rt(hX`bar`hj¨
h}ru(h
]h	]h]h]h
]uh~jlh”]rvhœXbarrw…rx}ry(hUh~jsubaubhœX doesn't take a rz…r{}r|(hX doesn't take a h~jlubj¥
)r}}r~(hX`self`hj¨
h}r(h
]h	]h]h]h
]uh~jlh”]r€hœXselfr…r‚}rƒ(hUh~j}ubaubhœX1 argument.  Interfaces document
how an object is r„…r…}r†(hX1 argument.  Interfaces document
how an object is h~jlubhó)r‡}rˆ(hX*used*hhöh}r‰(h
]h	]h]h]h
]uh~jlh”]rŠhœXusedr‹…rŒ}r(hUh~j‡ubaubhœX3.  When calling instance methods, you don't
pass a rŽ…r}r(hX3.  When calling instance methods, you don't
pass a h~jlubj¥
)r‘}r’(hX`self`hj¨
h}r“(h
]h	]h]h]h
]uh~jlh”]r”hœXselfr•…r–}r—(hUh~j‘ubaubhœX argument, so a r˜…r™}rš(hX argument, so a h~jlubj¥
)r›}rœ(hX`self`hj¨
h}r(h
]h	]h]h]h
]uh~jlh”]ržhœXselfrŸ…r }r¡(hUh~j›ubaubhœX: argument isn't included in the
interface signature.  The r¢…r£}r¤(hX: argument isn't included in the
interface signature.  The h~jlubj¥
)r¥}r¦(hX`self`hj¨
h}r§(h
]h	]h]h]h
]uh~jlh”]r¨hœXselfr©…rª}r«(hUh~j¥ubaubhœXX
 argument in instance methods is
really an implementation detail of Python instances. Other objects,
besides instances can provide interfaces and their methods might not
be instance methods. For example, modules can provide interfaces and
their methods are usually just functions.  Even instances can have
methods that are not instance methods.r¬…r­}r®(hXX
 argument in instance methods is
really an implementation detail of Python instances. Other objects,
besides instances can provide interfaces and their methods might not
be instance methods. For example, modules can provide interfaces and
their methods are usually just functions.  Even instances can have
methods that are not instance methods.h~jlubeubeubeubeubh)r¯}r°(hhhh‚h}r±(h
]h	]h]h]h
]uh„KZh…hhXKYou can access the attributes defined by an interface using mapping
syntax:r²h~h‡h”]r³hœXKYou can access the attributes defined by an interface using mapping
syntax:r´…rµ}r¶(hj²h~j¯ubaubj
)r·}r¸(hhhj“
h}r¹(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rºj˜
ah]j™
}h]uh„K]h…hhX¬>>> x = IFoo['x']
>>> type(x)
<class 'zope.interface.interface.Attribute'>
>>> x.__name__
'x'
>>> x.__doc__
'X blah blah'

>>> IFoo.get('x').__name__
'x'

>>> IFoo.get('y')h~h‡h”]r»hœX¬>>> x = IFoo['x']
>>> type(x)
<class 'zope.interface.interface.Attribute'>
>>> x.__name__
'x'
>>> x.__doc__
'X blah blah'

>>> IFoo.get('x').__name__
'x'

>>> IFoo.get('y')r¼…r½}r¾(hUh~j·ubaubh)r¿}rÀ(hhhh‚h}rÁ(h
]h	]h]h]h
]uh„Klh…hhX=You can use `in` to determine if an interface defines a name:rÂh~h‡h”]rÃ(hœXYou can use rÄ…rÅ}rÆ(hXYou can use h~j¿ubj¥
)rÇ}rÈ(hX`in`hj¨
h}rÉ(h
]h	]h]h]h
]uh~j¿h”]rÊhœXinrË…rÌ}rÍ(hUh~jÇubaubhœX- to determine if an interface defines a name:rÎ…rÏ}rÐ(hX- to determine if an interface defines a name:h~j¿ubeubj
)rÑ}rÒ(hhhj“
h}rÓ(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rÔj˜
ah]j™
}h]uh„Knh…hhX>>> 'x' in IFoo
Trueh~h‡h”]rÕhœX>>> 'x' in IFoo
TruerÖ…r×}rØ(hUh~jÑubaubh)rÙ}rÚ(hhhh‚h}rÛ(h
]h	]h]h]h
]uh„Ksh…hhX=You can iterate over interfaces to get the names they define:rÜh~h‡h”]rÝhœX=You can iterate over interfaces to get the names they define:rÞ…rß}rà(hjÜh~jÙubaubj
)rá}râ(hhhj“
h}rã(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]räj˜
ah]j™
}h]uh„Kuh…hhX>>>> names = list(IFoo)
>>> names.sort()
>>> names
['bar', 'x']h~h‡h”]råhœX>>>> names = list(IFoo)
>>> names.sort()
>>> names
['bar', 'x']r慁rç}rè(hUh~jáubaubh)ré}rê(hhhh‚h}rë(h
]h	]h]h]h
]uh„K|h…hhXlRemember that interfaces aren't classes. You can't access attribute
definitions as attributes of interfaces:rìh~h‡h”]ríhœXlRemember that interfaces aren't classes. You can't access attribute
definitions as attributes of interfaces:rrï}rð(hjìh~jéubaubj
)rñ}rò(hhhj“
h}ró(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]rôj˜
ah]j™
}h]uh„Kh…hhX‰>>> IFoo.x
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
AttributeError: 'InterfaceClass' object has no attribute 'x'h~h‡h”]rõhœX‰>>> IFoo.x
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
AttributeError: 'InterfaceClass' object has no attribute 'x'rö…r÷}rø(hUh~jñubaubh)rù}rú(hhhh‚h}rû(h
]h	]h]h]h
]uh„K†h…hhX/Methods provide access to the method signature:rüh~h‡h”]rýhœX/Methods provide access to the method signature:rþ…rÿ}r	(hjüh~jùubaubj
)r
	}r	(hhhj“
h}r	(h	]j•
j–
h
]UtestnodetypeXdoctesth
]Ugroups]r	j˜
ah]j™
}h]uh„Kˆh…hhX@>>> bar = IFoo['bar']
>>> bar.getSignatureString()
'(q, r=None)'h~h‡h”]r	hœX@>>> bar = IFoo['bar']
>>> bar.getSignatureString()
'(q, r=None)'r	…r	}r	(hUh~j
	ubaubhÿ)r		}r
	(hhhj
h}r	(h
]h	]h]h]h
]uh„Nh…hhUh~h‡h”]r	j
)r
	}r	(hj
h}r	(h
]h	]h]h]h
]uh„Kh…hhX\TODO
Methods really should have a better API.  This is something that
needs to be improved.
h~j		h”]r	(j
)r	}r	(hj
h}r	(h
]h	]h]h]h
]uh„Kh…hhXTODOr	h~j
	h”]r	hœXTODOr	…r	}r	(hj	h~j	ubaubj
)r	}r	(hUhj
h}r	(h
]h	]h]h]h
]uh~j
	h”]r	h)r	}r	(hh‚h}r	(h
]h	]h]h]h
]uh„Kh…hhXVMethods really should have a better API.  This is something that
needs to be improved.r 	h~j	h”]r!	hœXVMethods really should have a better API.  This is something that
needs to be improved.r"	…r#	}r$	(hj 	h~j	ubaubaubeubaubeubh”]r%	(hœX2In the example above, we've created an interface, r&	…r'	}r(	(hX2In the example above, we've created an interface, h~h€ubj¥
)r)	}r*	(hX`IFoo`hj¨
h}r+	(h
]h	]h]h]h
]uh~h€h”]r,	hœXIFoor-	…r.	}r/	(hUh~j)	ubaubhœX.  We
subclassed r0	…r1	}r2	(hX.  We
subclassed h~h€ubj¥
)r3	}r4	(hX`zope.interface.Interface`hj¨
h}r5	(h
]h	]h]h]h
]uh~h€h”]r6	hœXzope.interface.Interfacer7	…r8	}r9	(hUh~j3	ubaubhœX=, which is an ancestor interface for
all interfaces, much as r:	…r;	}r<	(hX=, which is an ancestor interface for
all interfaces, much as h~h€ubj¥
)r=	}r>	(hX`object`hj¨
h}r?	(h
]h	]h]h]h
]uh~h€h”]r@	hœXobjectrA	…rB	}rC	(hUh~j=	ubaubhœX) is an ancestor of all new-style
classes rD	…rE	}rF	(hX) is an ancestor of all new-style
classes h~h€ubhthœXD.   The interface is not a class, it's an Interface,
an instance of rG	…rH	}rI	(hXD.   The interface is not a class, it's an Interface,
an instance of h~h€ubj¥
)rJ	}rK	(hX`InterfaceClass`hj¨
h}rL	(h
]h	]h]h]h
]uh~h€h”]rM	hœXInterfaceClassrN	…rO	}rP	(hUh~jJ	ubaubhœX
:…rQ	}rR	(hX
:h~h€ubeubh”]rS	hœX
1…rT	}rU	(hUh~htubaubjU
jìeU
footnote_refsrV	}rW	(XfactoryrX	]rY	jU
aXcompatrZ	]r[	jìaXcreater\	]r]	htauUid_startr^	KU
citation_refsr_	}r`	Usymbol_footnote_refsra	]rb	Utransform_messagesrc	]rd	U	footnotesre	]rf	Unameidsrg	}rh	(hjhjYhj hjØhj^hjÛhjhjïhhh h“h!j
h"hâh#hyh$j‘h%jX
h&j~
h'j±h(j’uUrefnamesri	}rj	(jX	]rk	jU
ajZ	]rl	jìaj\	]rm	htauUtransformerrn	NUidsro	}rp	(jïj»hâhÝjjj
jüj±j¬j^jYjjjYjTjÛjÖj j›j~
jy
h“hŽjX
j¦jZ
jU
jñjìjØjÓh{hthh‡hyjtj’jj‘jŒuUsymbol_footnotesrq	]rr	hhUindirect_targetsrs	]rt	Usubstitution_namesru	}rv	Ucurrent_linerw	NUsubstitution_defsrx	}ry	Usymbol_footnote_startrz	KUautofootnote_startr{	KU
autofootnotesr|	]r}	(jtj¦j»eh”]r~	hŽaUcurrent_sourcer	NUrefidsr€	}r	(jX
]r‚	jU
ajï]rƒ	jìahy]r„	htauub.