[Checkins] SVN: zope.component/tseaver-test_cleanup/ Explicit doctest sections.
Tres Seaver
cvs-admin at zope.org
Sun Jun 17 18:32:26 UTC 2012
Log message for revision 126898:
Explicit doctest sections.
Changed:
_U zope.component/tseaver-test_cleanup/
U zope.component/tseaver-test_cleanup/docs/persistentregistry.rst
U zope.component/tseaver-test_cleanup/docs/socketexample.rst
U zope.component/tseaver-test_cleanup/docs/zcml.rst
-=-
Modified: zope.component/tseaver-test_cleanup/docs/persistentregistry.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/persistentregistry.rst 2012-06-17 18:32:18 UTC (rev 126897)
+++ zope.component/tseaver-test_cleanup/docs/persistentregistry.rst 2012-06-17 18:32:22 UTC (rev 126898)
@@ -3,4 +3,4 @@
Persistent component management allows persistent management of
components. From a usage point of view, there shouldn't be any new
-behavior beyond what's described in registry.txt.
+behavior.
Modified: zope.component/tseaver-test_cleanup/docs/socketexample.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/socketexample.rst 2012-06-17 18:32:18 UTC (rev 126897)
+++ zope.component/tseaver-test_cleanup/docs/socketexample.rst 2012-06-17 18:32:22 UTC (rev 126898)
@@ -39,36 +39,42 @@
for many as an initial read. Thus, we will only explain adapters in the context
of the component architecture's API.
-So let's say that we have a German socket
+So let's say that we have a German socket:
- >>> from zope.interface import Interface, implements
+.. doctest::
- >>> class IGermanSocket(Interface):
- ... pass
+ >>> from zope.interface import Interface, implements
- >>> class Socket(object):
- ... def __repr__(self):
- ... return '<instance of %s>' %self.__class__.__name__
+ >>> class IGermanSocket(Interface):
+ ... pass
- >>> class GermanSocket(Socket):
- ... """German wall socket."""
- ... implements(IGermanSocket)
+ >>> class Socket(object):
+ ... def __repr__(self):
+ ... return '<instance of %s>' %self.__class__.__name__
+ >>> class GermanSocket(Socket):
+ ... """German wall socket."""
+ ... implements(IGermanSocket)
+
and we want to convert it to an US socket
- >>> class IUSSocket(Interface):
- ... pass
+.. doctest::
+ >>> class IUSSocket(Interface):
+ ... pass
+
so that our shaver can be used in Germany. So we go to a German electronics
store to look for an adapter that we can plug in the wall:
- >>> class GermanToUSSocketAdapter(Socket):
- ... implements(IUSSocket)
- ... __used_for__ = IGermanSocket
- ...
- ... def __init__(self, socket):
- ... self.context = socket
+.. doctest::
+ >>> class GermanToUSSocketAdapter(Socket):
+ ... implements(IUSSocket)
+ ... __used_for__ = IGermanSocket
+ ...
+ ... def __init__(self, socket):
+ ... self.context = socket
+
Note that I could have called the passed in socket any way I like, but
`context` is the standard name accepted.
@@ -80,10 +86,12 @@
inventory. In the component architecture we do this by registering the adapter
with the framework, more specifically with the global site manager:
- >>> import zope.component
- >>> gsm = zope.component.getGlobalSiteManager()
- >>> gsm.registerAdapter(GermanToUSSocketAdapter, (IGermanSocket,), IUSSocket)
+.. doctest::
+ >>> import zope.component
+ >>> gsm = zope.component.getGlobalSiteManager()
+ >>> gsm.registerAdapter(GermanToUSSocketAdapter, (IGermanSocket,), IUSSocket)
+
`zope.component` is the component architecture API that is being
presented by this file. You registered an adapter from `IGermanSocket`
to `IUSSocket` having no name (thus the empty string).
@@ -91,50 +99,62 @@
Anyways, you finally get back to your hotel room and shave, since you have not
been able to shave in the plane. In the bathroom you discover a socket:
- >>> bathroomDE = GermanSocket()
- >>> IGermanSocket.providedBy(bathroomDE)
- True
+.. doctest::
+ >>> bathroomDE = GermanSocket()
+ >>> IGermanSocket.providedBy(bathroomDE)
+ True
+
You now insert the adapter in the German socket
- >>> bathroomUS = zope.component.getAdapter(bathroomDE, IUSSocket, '')
+.. doctest::
+ >>> bathroomUS = zope.component.getAdapter(bathroomDE, IUSSocket, '')
+
so that the socket now provides the US version:
- >>> IUSSocket.providedBy(bathroomUS)
- True
+.. doctest::
+ >>> IUSSocket.providedBy(bathroomUS)
+ True
+
Now you can insert your shaver and get on with your day.
After a week you travel for a couple of days to the Prague and you notice that
the Czech have yet another socket type:
- >>> class ICzechSocket(Interface):
- ... pass
+.. doctest::
- >>> class CzechSocket(Socket):
- ... implements(ICzechSocket)
+ >>> class ICzechSocket(Interface):
+ ... pass
- >>> czech = CzechSocket()
+ >>> class CzechSocket(Socket):
+ ... implements(ICzechSocket)
+ >>> czech = CzechSocket()
+
You try to find an adapter for your shaver in your bag, but you fail, since
you do not have one:
- >>> zope.component.getAdapter(czech, IUSSocket, '') \
- ... #doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- ComponentLookupError: (<instance of CzechSocket>,
- <InterfaceClass __builtin__.IUSSocket>,
- '')
+.. doctest::
+ >>> zope.component.getAdapter(czech, IUSSocket, '') \
+ ... #doctest: +NORMALIZE_WHITESPACE
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError: (<instance of CzechSocket>,
+ <InterfaceClass __builtin__.IUSSocket>,
+ '')
+
or the more graceful way:
- >>> marker = object()
- >>> socket = zope.component.queryAdapter(czech, IUSSocket, '', marker)
- >>> socket is marker
- True
+.. doctest::
+ >>> marker = object()
+ >>> socket = zope.component.queryAdapter(czech, IUSSocket, '', marker)
+ >>> socket is marker
+ True
+
In the component architecture API any `get*` method will fail with a specific
exception, if a query failed, whereby methods starting with `query*` will
always return a `default` value after a failure.
@@ -149,54 +169,64 @@
have to buy another adapter that also handles converting the voltage and the
frequency of the AC current:
- >>> class GermanToUSSocketAdapterAndTransformer(object):
- ... implements(IUSSocket)
- ... __used_for__ = IGermanSocket
- ...
- ... def __init__(self, socket):
- ... self.context = socket
+.. doctest::
+ >>> class GermanToUSSocketAdapterAndTransformer(object):
+ ... implements(IUSSocket)
+ ... __used_for__ = IGermanSocket
+ ...
+ ... def __init__(self, socket):
+ ... self.context = socket
+
Now, we need a way to keep the two adapters apart. Thus we register them with
a name:
- >>> gsm.registerAdapter(GermanToUSSocketAdapter,
- ... (IGermanSocket,), IUSSocket, 'shaver',)
- >>> gsm.registerAdapter(GermanToUSSocketAdapterAndTransformer,
- ... (IGermanSocket,), IUSSocket, 'dvd')
+.. doctest::
+ >>> gsm.registerAdapter(GermanToUSSocketAdapter,
+ ... (IGermanSocket,), IUSSocket, 'shaver',)
+ >>> gsm.registerAdapter(GermanToUSSocketAdapterAndTransformer,
+ ... (IGermanSocket,), IUSSocket, 'dvd')
+
Now we simply look up the adapters using their labels (called *name*):
- >>> socket = zope.component.getAdapter(bathroomDE, IUSSocket, 'shaver')
- >>> socket.__class__ is GermanToUSSocketAdapter
- True
+.. doctest::
- >>> socket = zope.component.getAdapter(bathroomDE, IUSSocket, 'dvd')
- >>> socket.__class__ is GermanToUSSocketAdapterAndTransformer
- True
+ >>> socket = zope.component.getAdapter(bathroomDE, IUSSocket, 'shaver')
+ >>> socket.__class__ is GermanToUSSocketAdapter
+ True
+ >>> socket = zope.component.getAdapter(bathroomDE, IUSSocket, 'dvd')
+ >>> socket.__class__ is GermanToUSSocketAdapterAndTransformer
+ True
+
Clearly, we do not have an adapter for the MP3 player
- >>> zope.component.getAdapter(bathroomDE, IUSSocket, 'mp3') \
- ... #doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- ComponentLookupError: (<instance of GermanSocket>,
- <InterfaceClass __builtin__.IUSSocket>,
- 'mp3')
+.. doctest::
+ >>> zope.component.getAdapter(bathroomDE, IUSSocket, 'mp3') \
+ ... #doctest: +NORMALIZE_WHITESPACE
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError: (<instance of GermanSocket>,
+ <InterfaceClass __builtin__.IUSSocket>,
+ 'mp3')
+
but you could use the 'dvd' adapter in this case of course. ;)
Sometimes you want to know all adapters that are available. Let's say you want
to know about all the adapters that convert a German to a US socket type:
- >>> sockets = list(zope.component.getAdapters((bathroomDE,), IUSSocket))
- >>> len(sockets)
- 3
- >>> names = [name for name, socket in sockets]
- >>> names.sort()
- >>> names
- [u'', u'dvd', u'shaver']
+.. doctest::
+ >>> sockets = list(zope.component.getAdapters((bathroomDE,), IUSSocket))
+ >>> len(sockets)
+ 3
+ >>> names = [name for name, socket in sockets]
+ >>> names.sort()
+ >>> names
+ [u'', u'dvd', u'shaver']
+
`zope.component.getAdapters()` returns a list of tuples. The first
entry of the tuple is the name of the adapter and the second is the
adapter itself.
@@ -210,73 +240,93 @@
player plug has a ground pin and all the adapters you have do not support
that:
- >>> class IUSGroundedSocket(IUSSocket):
- ... pass
+.. doctest::
+ >>> class IUSGroundedSocket(IUSSocket):
+ ... pass
+
So you go out another time to buy an adapter. This time, however, you do not
buy yet another adapter, but a piece that provides the grounding plug:
- >>> class IGrounder(Interface):
- ... pass
+.. doctest::
- >>> class Grounder(object):
- ... implements(IGrounder)
- ... def __repr__(self):
- ... return '<instance of Grounder>'
+ >>> class IGrounder(Interface):
+ ... pass
+ >>> class Grounder(object):
+ ... implements(IGrounder)
+ ... def __repr__(self):
+ ... return '<instance of Grounder>'
+
Then together they will provided a grounded us socket:
- >>> class GroundedGermanToUSSocketAdapter(object):
- ... implements(IUSGroundedSocket)
- ... __used_for__ = (IGermanSocket, IGrounder)
- ... def __init__(self, socket, grounder):
- ... self.socket, self.grounder = socket, grounder
+.. doctest::
+ >>> class GroundedGermanToUSSocketAdapter(object):
+ ... implements(IUSGroundedSocket)
+ ... __used_for__ = (IGermanSocket, IGrounder)
+ ... def __init__(self, socket, grounder):
+ ... self.socket, self.grounder = socket, grounder
+
You now register the combination, so that you know you can create a
`IUSGroundedSocket`:
- >>> gsm.registerAdapter(GroundedGermanToUSSocketAdapter,
- ... (IGermanSocket, IGrounder), IUSGroundedSocket, 'mp3')
+.. doctest::
+ >>> gsm.registerAdapter(GroundedGermanToUSSocketAdapter,
+ ... (IGermanSocket, IGrounder), IUSGroundedSocket, 'mp3')
+
Given the grounder
- >>> grounder = Grounder()
+.. doctest::
+ >>> grounder = Grounder()
+
and a German socket
- >>> livingroom = GermanSocket()
+.. doctest::
+ >>> livingroom = GermanSocket()
+
we can now get a grounded US socket:
- >>> socket = zope.component.getMultiAdapter((livingroom, grounder),
- ... IUSGroundedSocket, 'mp3')
+.. doctest::
- >>> socket.__class__ is GroundedGermanToUSSocketAdapter
- True
- >>> socket.socket is livingroom
- True
- >>> socket.grounder is grounder
- True
+ >>> socket = zope.component.getMultiAdapter((livingroom, grounder),
+ ... IUSGroundedSocket, 'mp3')
+.. doctest::
+
+ >>> socket.__class__ is GroundedGermanToUSSocketAdapter
+ True
+ >>> socket.socket is livingroom
+ True
+ >>> socket.grounder is grounder
+ True
+
Of course, you do not have a 'dvd' grounded US socket available:
- >>> zope.component.getMultiAdapter((livingroom, grounder),
- ... IUSGroundedSocket, 'dvd') \
- ... #doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- ComponentLookupError: ((<instance of GermanSocket>,
- <instance of Grounder>),
- <InterfaceClass __builtin__.IUSGroundedSocket>,
- 'dvd')
+.. doctest::
+ >>> zope.component.getMultiAdapter((livingroom, grounder),
+ ... IUSGroundedSocket, 'dvd') \
+ ... #doctest: +NORMALIZE_WHITESPACE
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError: ((<instance of GermanSocket>,
+ <instance of Grounder>),
+ <InterfaceClass __builtin__.IUSGroundedSocket>,
+ 'dvd')
- >>> socket = zope.component.queryMultiAdapter(
- ... (livingroom, grounder), IUSGroundedSocket, 'dvd', marker)
- >>> socket is marker
- True
+.. doctest::
+
+ >>> socket = zope.component.queryMultiAdapter(
+ ... (livingroom, grounder), IUSGroundedSocket, 'dvd', marker)
+ >>> socket is marker
+ True
+
Again, you might want to read `adapter.txt` in `zope.interface` for a more
comprehensive coverage of multi-adapters.
@@ -290,60 +340,70 @@
Let's say one of our adapters overheated and caused a small fire:
- >>> class IFire(Interface):
- ... pass
+.. doctest::
- >>> class Fire(object):
- ... implements(IFire)
+ >>> class IFire(Interface):
+ ... pass
- >>> fire = Fire()
+ >>> class Fire(object):
+ ... implements(IFire)
+ >>> fire = Fire()
+
We want to use all available objects to put out the fire:
- >>> class IFireExtinguisher(Interface):
- ... def extinguish():
- ... pass
+.. doctest::
- >>> class FireExtinguisher(object):
- ... def __init__(self, fire):
- ... pass
- ... def extinguish(self):
- ... "Place extinguish code here."
- ... print 'Used ' + self.__class__.__name__ + '.'
+ >>> class IFireExtinguisher(Interface):
+ ... def extinguish():
+ ... pass
+ >>> class FireExtinguisher(object):
+ ... def __init__(self, fire):
+ ... pass
+ ... def extinguish(self):
+ ... "Place extinguish code here."
+ ... print 'Used ' + self.__class__.__name__ + '.'
+
Here some specific methods to put out the fire:
- >>> class PowderExtinguisher(FireExtinguisher):
- ... pass
- >>> gsm.registerSubscriptionAdapter(PowderExtinguisher,
- ... (IFire,), IFireExtinguisher)
+.. doctest::
- >>> class Blanket(FireExtinguisher):
- ... pass
- >>> gsm.registerSubscriptionAdapter(Blanket, (IFire,), IFireExtinguisher)
+ >>> class PowderExtinguisher(FireExtinguisher):
+ ... pass
+ >>> gsm.registerSubscriptionAdapter(PowderExtinguisher,
+ ... (IFire,), IFireExtinguisher)
- >>> class SprinklerSystem(FireExtinguisher):
- ... pass
- >>> gsm.registerSubscriptionAdapter(SprinklerSystem,
- ... (IFire,), IFireExtinguisher)
+ >>> class Blanket(FireExtinguisher):
+ ... pass
+ >>> gsm.registerSubscriptionAdapter(Blanket, (IFire,), IFireExtinguisher)
+ >>> class SprinklerSystem(FireExtinguisher):
+ ... pass
+ >>> gsm.registerSubscriptionAdapter(SprinklerSystem,
+ ... (IFire,), IFireExtinguisher)
+
Now let use all these things to put out the fire:
- >>> extinguishers = zope.component.subscribers((fire,), IFireExtinguisher)
- >>> extinguishers.sort()
- >>> for extinguisher in extinguishers:
- ... extinguisher.extinguish()
- Used Blanket.
- Used PowderExtinguisher.
- Used SprinklerSystem.
+.. doctest::
+ >>> extinguishers = zope.component.subscribers((fire,), IFireExtinguisher)
+ >>> extinguishers.sort()
+ >>> for extinguisher in extinguishers:
+ ... extinguisher.extinguish()
+ Used Blanket.
+ Used PowderExtinguisher.
+ Used SprinklerSystem.
+
If no subscribers are found for a particular object, then an empty list is
returned:
- >>> zope.component.subscribers((object(),), IFireExtinguisher)
- []
+.. doctest::
+ >>> zope.component.subscribers((object(),), IFireExtinguisher)
+ []
+
Utilities
---------
@@ -367,40 +427,50 @@
So you decide to go to your favorite hardware store and by a Diesel-powered
electric generator. The generator provides of course a US-style socket:
- >>> class Generator(object):
- ... implements(IUSSocket)
- ... def __repr__(self):
- ... return '<instance of Generator>'
+.. doctest::
- >>> generator = Generator()
+ >>> class Generator(object):
+ ... implements(IUSSocket)
+ ... def __repr__(self):
+ ... return '<instance of Generator>'
+ >>> generator = Generator()
+
Like for adapters, we now have to add the newly-acquired generator to our
inventory by registering it as a utility:
- >>> gsm.registerUtility(generator, IUSSocket)
+.. doctest::
+ >>> gsm.registerUtility(generator, IUSSocket)
+
We can now get the utility using
- >>> utility = zope.component.getUtility(IUSSocket)
- >>> utility is generator
- True
+.. doctest::
+ >>> utility = zope.component.getUtility(IUSSocket)
+ >>> utility is generator
+ True
+
As you can see, it is very simple to register and retrieve utilities. If a
utility does not exist for a particular interface, such as the German socket,
then the lookup fails
- >>> zope.component.getUtility(IGermanSocket)
- Traceback (most recent call last):
- ...
- ComponentLookupError: (<InterfaceClass __builtin__.IGermanSocket>, '')
+.. doctest::
+ >>> zope.component.getUtility(IGermanSocket)
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError: (<InterfaceClass __builtin__.IGermanSocket>, '')
+
or more gracefully when specifying a default value:
- >>> default = object()
- >>> utility = zope.component.queryUtility(IGermanSocket, default=default)
- >>> utility is default
- True
+.. doctest::
+ >>> default = object()
+ >>> utility = zope.component.queryUtility(IGermanSocket, default=default)
+ >>> utility is default
+ True
+
Note: The only difference between `getUtility()` and `queryUtility()` is the
fact that you can specify a default value for the latter function, so that it
will never cause a `ComponentLookupError`.
@@ -420,59 +490,73 @@
nice weather, so why not? Via the Web you order a set of 110V/120W solar
panels that provide a regular US-style socket as output:
- >>> class SolarPanel(object):
- ... implements(IUSSocket)
- ... def __repr__(self):
- ... return '<instance of Solar Panel>'
+.. doctest::
- >>> panel = SolarPanel()
+ >>> class SolarPanel(object):
+ ... implements(IUSSocket)
+ ... def __repr__(self):
+ ... return '<instance of Solar Panel>'
+ >>> panel = SolarPanel()
+
Once it arrives, we add it to our inventory:
- >>> gsm.registerUtility(panel, IUSSocket, 'Solar Panel')
+.. doctest::
+ >>> gsm.registerUtility(panel, IUSSocket, 'Solar Panel')
+
You can now access the solar panel using
- >>> utility = zope.component.getUtility(IUSSocket, 'Solar Panel')
- >>> utility is panel
- True
+.. doctest::
+ >>> utility = zope.component.getUtility(IUSSocket, 'Solar Panel')
+ >>> utility is panel
+ True
+
Of course, if a utility is not available, then the lookup will simply fail
- >>> zope.component.getUtility(IUSSocket, 'Wind Mill')
- Traceback (most recent call last):
- ...
- ComponentLookupError: (<InterfaceClass __builtin__.IUSSocket>, 'Wind Mill')
+.. doctest::
+ >>> zope.component.getUtility(IUSSocket, 'Wind Mill')
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError: (<InterfaceClass __builtin__.IUSSocket>, 'Wind Mill')
+
or more gracefully when specifying a default value:
- >>> default = object()
- >>> utility = zope.component.queryUtility(IUSSocket, 'Wind Mill',
- ... default=default)
- >>> utility is default
- True
+.. doctest::
+ >>> default = object()
+ >>> utility = zope.component.queryUtility(IUSSocket, 'Wind Mill',
+ ... default=default)
+ >>> utility is default
+ True
+
Now you want to look at all the utilities you have for a particular kind. The
following API function will return a list of name/utility pairs:
- >>> utils = list(zope.component.getUtilitiesFor(IUSSocket))
- >>> utils.sort()
- >>> utils #doctest: +NORMALIZE_WHITESPACE
- [(u'', <instance of Generator>),
- (u'Solar Panel', <instance of Solar Panel>)]
+.. doctest::
+ >>> utils = list(zope.component.getUtilitiesFor(IUSSocket))
+ >>> utils.sort()
+ >>> utils #doctest: +NORMALIZE_WHITESPACE
+ [(u'', <instance of Generator>),
+ (u'Solar Panel', <instance of Solar Panel>)]
+
Another method of looking up all utilities is by using
`getAllUtilitiesRegisteredFor(iface)`. This function will return an iterable
of utilities (without names); however, it will also return overridden
utilities. If you are not using multiple site managers, you will not actually
need this method.
- >>> utils = list(zope.component.getAllUtilitiesRegisteredFor(IUSSocket))
- >>> utils.sort()
- >>> utils
- [<instance of Generator>, <instance of Solar Panel>]
+.. doctest::
+ >>> utils = list(zope.component.getAllUtilitiesRegisteredFor(IUSSocket))
+ >>> utils.sort()
+ >>> utils
+ [<instance of Generator>, <instance of Solar Panel>]
+
Factories
~~~~~~~~~
@@ -490,36 +574,46 @@
the solar panel. To do this, we can use a standard implementation of the
`IFactory` interface:
- >>> from zope.component.factory import Factory
- >>> factory = Factory(SolarPanel,
- ... 'Solar Panel',
- ... 'This factory creates a solar panel.')
+.. doctest::
+ >>> from zope.component.factory import Factory
+ >>> factory = Factory(SolarPanel,
+ ... 'Solar Panel',
+ ... 'This factory creates a solar panel.')
+
Optionally, I could have also specified the interfaces that the created object
will provide, but the factory class is smart enough to determine the
implemented interface from the class. We now register the factory:
- >>> from zope.component.interfaces import IFactory
- >>> gsm.registerUtility(factory, IFactory, 'SolarPanel')
+.. doctest::
+ >>> from zope.component.interfaces import IFactory
+ >>> gsm.registerUtility(factory, IFactory, 'SolarPanel')
+
We can now get a list of interfaces the produced object will provide:
- >>> ifaces = zope.component.getFactoryInterfaces('SolarPanel')
- >>> IUSSocket in ifaces
- True
+.. doctest::
+ >>> ifaces = zope.component.getFactoryInterfaces('SolarPanel')
+ >>> IUSSocket in ifaces
+ True
+
By the way, this is equivalent to
- >>> ifaces2 = factory.getInterfaces()
- >>> ifaces is ifaces2
- True
+.. doctest::
+ >>> ifaces2 = factory.getInterfaces()
+ >>> ifaces is ifaces2
+ True
+
Of course you can also just create an object:
- >>> panel = zope.component.createObject('SolarPanel')
- >>> panel.__class__ is SolarPanel
- True
+.. doctest::
+ >>> panel = zope.component.createObject('SolarPanel')
+ >>> panel.__class__ is SolarPanel
+ True
+
Note: Ignore the first argument (`None`) for now; it is the context of the
utility lookup, which is usually an optional argument, but cannot be in this
case, since all other arguments beside the `name` are passed in as arguments
@@ -527,19 +621,23 @@
Once you register several factories
- >>> gsm.registerUtility(Factory(Generator), IFactory, 'Generator')
+.. doctest::
+ >>> gsm.registerUtility(Factory(Generator), IFactory, 'Generator')
+
you can also determine, which available factories will create objects
providing a certain interface:
- >>> factories = zope.component.getFactoriesFor(IUSSocket)
- >>> factories = [(name, factory.__class__) for name, factory in factories]
- >>> factories.sort()
- >>> factories #doctest: +NORMALIZE_WHITESPACE
- [(u'Generator', <class 'zope.component.factory.Factory'>),
- (u'SolarPanel', <class 'zope.component.factory.Factory'>)]
+.. doctest::
+ >>> factories = zope.component.getFactoriesFor(IUSSocket)
+ >>> factories = [(name, factory.__class__) for name, factory in factories]
+ >>> factories.sort()
+ >>> factories #doctest: +NORMALIZE_WHITESPACE
+ [(u'Generator', <class 'zope.component.factory.Factory'>),
+ (u'SolarPanel', <class 'zope.component.factory.Factory'>)]
+
Site Managers
-------------
@@ -552,46 +650,56 @@
commonly known as *global site manager*, since it is always available. You can
always get the global site manager using the API:
- >>> gsm = zope.component.getGlobalSiteManager()
+.. doctest::
- >>> from zope.component import globalSiteManager
- >>> gsm is globalSiteManager
- True
- >>> from zope.component.interfaces import IComponentLookup
- >>> IComponentLookup.providedBy(gsm)
- True
- >>> from zope.component.interfaces import IComponents
- >>> IComponents.providedBy(gsm)
- True
+ >>> gsm = zope.component.getGlobalSiteManager()
+ >>> from zope.component import globalSiteManager
+ >>> gsm is globalSiteManager
+ True
+ >>> from zope.component.interfaces import IComponentLookup
+ >>> IComponentLookup.providedBy(gsm)
+ True
+ >>> from zope.component.interfaces import IComponents
+ >>> IComponents.providedBy(gsm)
+ True
+
You can also lookup at site manager in a given context. The only requirement
is that the context can be adapted to a site manager. So let's create a
special site manager:
- >>> from zope.component.globalregistry import BaseGlobalComponents
- >>> sm = BaseGlobalComponents()
+.. doctest::
+ >>> from zope.component.globalregistry import BaseGlobalComponents
+ >>> sm = BaseGlobalComponents()
+
Now we create a context that adapts to the site manager via the `__conform__`
method as specified in PEP 246.
- >>> class Context(object):
- ... def __init__(self, sm):
- ... self.sm = sm
- ... def __conform__(self, interface):
- ... if interface.isOrExtends(IComponentLookup):
- ... return self.sm
+.. doctest::
+ >>> class Context(object):
+ ... def __init__(self, sm):
+ ... self.sm = sm
+ ... def __conform__(self, interface):
+ ... if interface.isOrExtends(IComponentLookup):
+ ... return self.sm
+
We now instantiate the `Context` with our special site manager:
- >>> context = Context(sm)
- >>> context.sm is sm
- True
+.. doctest::
+ >>> context = Context(sm)
+ >>> context.sm is sm
+ True
+
We can now ask for the site manager of this context:
- >>> lsm = zope.component.getSiteManager(context)
- >>> lsm is sm
- True
+.. doctest::
+ >>> lsm = zope.component.getSiteManager(context)
+ >>> lsm is sm
+ True
+
The site manager instance `lsm` is formally known as a *local site manager* of
`context`.
Modified: zope.component/tseaver-test_cleanup/docs/zcml.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/zcml.rst 2012-06-17 18:32:18 UTC (rev 126897)
+++ zope.component/tseaver-test_cleanup/docs/zcml.rst 2012-06-17 18:32:22 UTC (rev 126898)
@@ -13,69 +13,79 @@
This helper will let us easily execute ZCML snippets:
- >>> from cStringIO import StringIO
- >>> from zope.configuration.xmlconfig import xmlconfig
- >>> def runSnippet(snippet):
- ... template = """\
- ... <configure xmlns='http://namespaces.zope.org/zope'
- ... i18n_domain="zope">
- ... %s
- ... </configure>"""
- ... xmlconfig(StringIO(template % snippet))
+.. doctest::
+ >>> from cStringIO import StringIO
+ >>> from zope.configuration.xmlconfig import xmlconfig
+ >>> def runSnippet(snippet):
+ ... template = """\
+ ... <configure xmlns='http://namespaces.zope.org/zope'
+ ... i18n_domain="zope">
+ ... %s
+ ... </configure>"""
+ ... xmlconfig(StringIO(template % snippet))
+
adapter
-------
Adapters play a key role in the Component Architecture. In ZCML, they
are registered with the <adapter /> directive.
- >>> from zope.component.testfiles.adapter import A1, A2, A3, Handler
- >>> from zope.component.testfiles.adapter import I1, I2, I3, IS
- >>> from zope.component.testfiles.components import IContent, Content, Comp, comp
+.. doctest::
+ >>> from zope.component.testfiles.adapter import A1, A2, A3, Handler
+ >>> from zope.component.testfiles.adapter import I1, I2, I3, IS
+ >>> from zope.component.testfiles.components import IContent, Content, Comp, comp
+
Before we register the first test adapter, we can verify that adapter
lookup doesn't work yet:
- >>> from zope.component.tests.test_doctests import clearZCML
- >>> clearZCML()
- >>> from zope.component.testfiles.components import IApp
- >>> IApp(Content(), None) is None
- True
+.. doctest::
+ >>> from zope.component.tests.test_doctests import clearZCML
+ >>> clearZCML()
+ >>> from zope.component.testfiles.components import IApp
+ >>> IApp(Content(), None) is None
+ True
+
Then we register the adapter and see that the lookup works:
- >>> runSnippet('''
- ... <adapter
- ... factory="zope.component.testfiles.components.Comp"
- ... provides="zope.component.testfiles.components.IApp"
- ... for="zope.component.testfiles.components.IContent"
- ... />''')
+.. doctest::
- >>> IApp(Content()).__class__
- <class 'zope.component.testfiles.components.Comp'>
+ >>> runSnippet('''
+ ... <adapter
+ ... factory="zope.component.testfiles.components.Comp"
+ ... provides="zope.component.testfiles.components.IApp"
+ ... for="zope.component.testfiles.components.IContent"
+ ... />''')
+ >>> IApp(Content()).__class__
+ <class 'zope.component.testfiles.components.Comp'>
+
It is also possible to give adapters names. Then the combination of
required interface, provided interface and name makes the adapter
lookup unique. The name is supplied using the ``name`` argument to
the <adapter /> directive:
- >>> from zope.component.tests.test_doctests import clearZCML
- >>> clearZCML()
- >>> import zope.component
- >>> zope.component.queryAdapter(Content(), IApp, 'test') is None
- True
+.. doctest::
- >>> runSnippet('''
- ... <adapter
- ... factory="zope.component.testfiles.components.Comp"
- ... provides="zope.component.testfiles.components.IApp"
- ... for="zope.component.testfiles.components.IContent"
- ... name="test"
- ... />''')
+ >>> from zope.component.tests.test_doctests import clearZCML
+ >>> clearZCML()
+ >>> import zope.component
+ >>> zope.component.queryAdapter(Content(), IApp, 'test') is None
+ True
- >>> zope.component.getAdapter(Content(), IApp, 'test').__class__
- <class 'zope.component.testfiles.components.Comp'>
+ >>> runSnippet('''
+ ... <adapter
+ ... factory="zope.component.testfiles.components.Comp"
+ ... provides="zope.component.testfiles.components.IApp"
+ ... for="zope.component.testfiles.components.IContent"
+ ... name="test"
+ ... />''')
+ >>> zope.component.getAdapter(Content(), IApp, 'test').__class__
+ <class 'zope.component.testfiles.components.Comp'>
+
Adapter factories
~~~~~~~~~~~~~~~~~
@@ -84,207 +94,233 @@
will be given to the next factory. The return value of the last
factory is returned as the result of the adapter lookup. For examle:
- >>> clearZCML()
- >>> runSnippet('''
- ... <adapter
- ... factory="zope.component.testfiles.adapter.A1
- ... zope.component.testfiles.adapter.A2
- ... zope.component.testfiles.adapter.A3"
- ... provides="zope.component.testfiles.components.IApp"
- ... for="zope.component.testfiles.components.IContent"
- ... />''')
+.. doctest::
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <adapter
+ ... factory="zope.component.testfiles.adapter.A1
+ ... zope.component.testfiles.adapter.A2
+ ... zope.component.testfiles.adapter.A3"
+ ... provides="zope.component.testfiles.components.IApp"
+ ... for="zope.component.testfiles.components.IContent"
+ ... />''')
+
The resulting adapter is an A3, around an A2, around an A1, around the
adapted object:
- >>> content = Content()
- >>> a3 = IApp(content)
- >>> a3.__class__ is A3
- True
+.. doctest::
- >>> a2 = a3.context[0]
- >>> a2.__class__ is A2
- True
+ >>> content = Content()
+ >>> a3 = IApp(content)
+ >>> a3.__class__ is A3
+ True
- >>> a1 = a2.context[0]
- >>> a1.__class__ is A1
- True
+ >>> a2 = a3.context[0]
+ >>> a2.__class__ is A2
+ True
- >>> a1.context[0] is content
- True
+ >>> a1 = a2.context[0]
+ >>> a1.__class__ is A1
+ True
+ >>> a1.context[0] is content
+ True
+
Of course, if no factory is provided at all, we will get an error:
- >>> runSnippet('''
- ... <adapter
- ... factory=""
- ... provides="zope.component.testfiles.components.IApp"
- ... for="zope.component.testfiles.components.IContent"
- ... />''')
- Traceback (most recent call last):
- ...
- ZopeXMLConfigurationError: File "<string>", line 4.2-8.8
- ValueError: No factory specified
+.. doctest::
+ >>> runSnippet('''
+ ... <adapter
+ ... factory=""
+ ... provides="zope.component.testfiles.components.IApp"
+ ... for="zope.component.testfiles.components.IContent"
+ ... />''')
+ Traceback (most recent call last):
+ ...
+ ZopeXMLConfigurationError: File "<string>", line 4.2-8.8
+ ValueError: No factory specified
+
Declaring ``for`` and ``provides`` in Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The <adapter /> directive can figure out from the in-line Python
declaration (using ``zope.component.adapts()`` or
``zope.component.adapter()`` as well as ``zope.interface.implements``)
-what the adapter should be registered for and what it provides::
+what the adapter should be registered for and what it provides:
- >>> clearZCML()
- >>> IApp(Content(), None) is None
- True
+.. doctest::
- >>> runSnippet('''
- ... <adapter factory="zope.component.testfiles.components.Comp" />''')
+ >>> clearZCML()
+ >>> IApp(Content(), None) is None
+ True
- >>> IApp(Content()).__class__
- <class 'zope.component.testfiles.components.Comp'>
+ >>> runSnippet('''
+ ... <adapter factory="zope.component.testfiles.components.Comp" />''')
+ >>> IApp(Content()).__class__
+ <class 'zope.component.testfiles.components.Comp'>
+
Of course, if the adapter has no ``implements()`` declaration, ZCML
can't figure out what it provides:
- >>> runSnippet('''
- ... <adapter
- ... factory="zope.component.testfiles.adapter.A4"
- ... for="zope.component.testfiles.components.IContent"
- ... />''')
- Traceback (most recent call last):
- ...
- ZopeXMLConfigurationError: File "<string>", line 4.2-7.8
- TypeError: Missing 'provides' attribute
+.. doctest::
+ >>> runSnippet('''
+ ... <adapter
+ ... factory="zope.component.testfiles.adapter.A4"
+ ... for="zope.component.testfiles.components.IContent"
+ ... />''')
+ Traceback (most recent call last):
+ ...
+ ZopeXMLConfigurationError: File "<string>", line 4.2-7.8
+ TypeError: Missing 'provides' attribute
+
On the other hand, if the factory implements more than one interface,
ZCML can't figure out what it should provide either:
- >>> runSnippet('''
- ... <adapter
- ... factory="zope.component.testfiles.adapter.A5"
- ... for="zope.component.testfiles.components.IContent"
- ... />''')
- Traceback (most recent call last):
- ...
- ZopeXMLConfigurationError: File "<string>", line 4.2-7.8
- TypeError: Missing 'provides' attribute
+.. doctest::
+ >>> runSnippet('''
+ ... <adapter
+ ... factory="zope.component.testfiles.adapter.A5"
+ ... for="zope.component.testfiles.components.IContent"
+ ... />''')
+ Traceback (most recent call last):
+ ...
+ ZopeXMLConfigurationError: File "<string>", line 4.2-7.8
+ TypeError: Missing 'provides' attribute
+
A not so common edge case is registering adapters directly for
classes, not for interfaces. For example:
- >>> clearZCML()
- >>> runSnippet('''
- ... <adapter
- ... for="zope.component.testfiles.components.Content"
- ... provides="zope.component.testfiles.adapter.I1"
- ... factory="zope.component.testfiles.adapter.A1"
- ... />''')
+.. doctest::
- >>> content = Content()
- >>> a1 = zope.component.getAdapter(content, I1, '')
- >>> isinstance(a1, A1)
- True
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <adapter
+ ... for="zope.component.testfiles.components.Content"
+ ... provides="zope.component.testfiles.adapter.I1"
+ ... factory="zope.component.testfiles.adapter.A1"
+ ... />''')
+ >>> content = Content()
+ >>> a1 = zope.component.getAdapter(content, I1, '')
+ >>> isinstance(a1, A1)
+ True
+
This time, any object providing ``IContent`` won't work if it's not an
instance of the ``Content`` class:
- >>> import zope.interface
- >>> class MyContent:
- ... zope.interface.implements(IContent)
- >>> zope.component.getAdapter(MyContent(), I1, '') # doctest: +ELLIPSIS
- Traceback (most recent call last):
- ...
- ComponentLookupError: ...
+.. doctest::
+ >>> import zope.interface
+ >>> class MyContent:
+ ... zope.interface.implements(IContent)
+ >>> zope.component.getAdapter(MyContent(), I1, '') # doctest: +ELLIPSIS
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError: ...
+
Multi-adapters
~~~~~~~~~~~~~~
Conventional adapters adapt one object to provide another interface.
Multi-adapters adapt several objects at once:
- >>> clearZCML()
- >>> runSnippet('''
- ... <adapter
- ... for="zope.component.testfiles.components.IContent
- ... zope.component.testfiles.adapter.I1
- ... zope.component.testfiles.adapter.I2"
- ... provides="zope.component.testfiles.adapter.I3"
- ... factory="zope.component.testfiles.adapter.A3"
- ... />''')
+.. doctest::
- >>> content = Content()
- >>> a1 = A1()
- >>> a2 = A2()
- >>> a3 = zope.component.queryMultiAdapter((content, a1, a2), I3)
- >>> a3.__class__ is A3
- True
- >>> a3.context == (content, a1, a2)
- True
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <adapter
+ ... for="zope.component.testfiles.components.IContent
+ ... zope.component.testfiles.adapter.I1
+ ... zope.component.testfiles.adapter.I2"
+ ... provides="zope.component.testfiles.adapter.I3"
+ ... factory="zope.component.testfiles.adapter.A3"
+ ... />''')
+ >>> content = Content()
+ >>> a1 = A1()
+ >>> a2 = A2()
+ >>> a3 = zope.component.queryMultiAdapter((content, a1, a2), I3)
+ >>> a3.__class__ is A3
+ True
+ >>> a3.context == (content, a1, a2)
+ True
+
You can even adapt an empty list of objects (we call this a
null-adapter):
- >>> clearZCML()
- >>> runSnippet('''
- ... <adapter
- ... for=""
- ... provides="zope.component.testfiles.adapter.I3"
- ... factory="zope.component.testfiles.adapter.A3"
- ... />''')
+.. doctest::
- >>> a3 = zope.component.queryMultiAdapter((), I3)
- >>> a3.__class__ is A3
- True
- >>> a3.context == ()
- True
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <adapter
+ ... for=""
+ ... provides="zope.component.testfiles.adapter.I3"
+ ... factory="zope.component.testfiles.adapter.A3"
+ ... />''')
+ >>> a3 = zope.component.queryMultiAdapter((), I3)
+ >>> a3.__class__ is A3
+ True
+ >>> a3.context == ()
+ True
+
Even with multi-adapters, ZCML can figure out the ``for`` and
``provides`` parameters from the Python declarations:
- >>> clearZCML()
- >>> runSnippet('''
- ... <adapter factory="zope.component.testfiles.adapter.A3" />''')
+.. doctest::
- >>> a3 = zope.component.queryMultiAdapter((content, a1, a2), I3)
- >>> a3.__class__ is A3
- True
- >>> a3.context == (content, a1, a2)
- True
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <adapter factory="zope.component.testfiles.adapter.A3" />''')
+ >>> a3 = zope.component.queryMultiAdapter((content, a1, a2), I3)
+ >>> a3.__class__ is A3
+ True
+ >>> a3.context == (content, a1, a2)
+ True
+
Chained factories are not supported for multi-adapters, though:
- >>> clearZCML()
- >>> runSnippet('''
- ... <adapter
- ... for="zope.component.testfiles.components.IContent
- ... zope.component.testfiles.adapter.I1
- ... zope.component.testfiles.adapter.I2"
- ... provides="zope.component.testfiles.components.IApp"
- ... factory="zope.component.testfiles.adapter.A1
- ... zope.component.testfiles.adapter.A2"
- ... />''')
- Traceback (most recent call last):
- ...
- ZopeXMLConfigurationError: File "<string>", line 4.2-11.8
- ValueError: Can't use multiple factories and multiple for
+.. doctest::
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <adapter
+ ... for="zope.component.testfiles.components.IContent
+ ... zope.component.testfiles.adapter.I1
+ ... zope.component.testfiles.adapter.I2"
+ ... provides="zope.component.testfiles.components.IApp"
+ ... factory="zope.component.testfiles.adapter.A1
+ ... zope.component.testfiles.adapter.A2"
+ ... />''')
+ Traceback (most recent call last):
+ ...
+ ZopeXMLConfigurationError: File "<string>", line 4.2-11.8
+ ValueError: Can't use multiple factories and multiple for
+
And neither for null-adapters:
- >>> clearZCML()
- >>> runSnippet('''
- ... <adapter
- ... for=""
- ... provides="zope.component.testfiles.components.IApp"
- ... factory="zope.component.testfiles.adapter.A1
- ... zope.component.testfiles.adapter.A2"
- ... />''')
- Traceback (most recent call last):
- ...
- ZopeXMLConfigurationError: File "<string>", line 4.2-9.8
- ValueError: Can't use multiple factories and multiple for
+.. doctest::
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <adapter
+ ... for=""
+ ... provides="zope.component.testfiles.components.IApp"
+ ... factory="zope.component.testfiles.adapter.A1
+ ... zope.component.testfiles.adapter.A2"
+ ... />''')
+ Traceback (most recent call last):
+ ...
+ ZopeXMLConfigurationError: File "<string>", line 4.2-9.8
+ ValueError: Can't use multiple factories and multiple for
+
Protected adapters
~~~~~~~~~~~~~~~~~~
@@ -292,118 +328,130 @@
a permission for which we'll have to register the <permission />
directive:
- >>> clearZCML()
- >>> IApp(Content(), None) is None
- True
+.. doctest::
- >>> import zope.security
- >>> from zope.configuration.xmlconfig import XMLConfig
- >>> XMLConfig('meta.zcml', zope.security)()
- >>> runSnippet('''
- ... <permission
- ... id="y.x"
- ... title="XY"
- ... description="Allow XY."
- ... />
- ... <adapter
- ... factory="zope.component.testfiles.components.Comp"
- ... provides="zope.component.testfiles.components.IApp"
- ... for="zope.component.testfiles.components.IContent"
- ... permission="y.x"
- ... />''')
+ >>> clearZCML()
+ >>> IApp(Content(), None) is None
+ True
+ >>> import zope.security
+ >>> from zope.configuration.xmlconfig import XMLConfig
+ >>> XMLConfig('meta.zcml', zope.security)()
+ >>> runSnippet('''
+ ... <permission
+ ... id="y.x"
+ ... title="XY"
+ ... description="Allow XY."
+ ... />
+ ... <adapter
+ ... factory="zope.component.testfiles.components.Comp"
+ ... provides="zope.component.testfiles.components.IApp"
+ ... for="zope.component.testfiles.components.IContent"
+ ... permission="y.x"
+ ... />''')
+
We see that the adapter is a location proxy now so that the
appropriate permissions can be found from the context:
- >>> IApp(Content()).__class__
- <class 'zope.component.testfiles.components.Comp'>
- >>> type(IApp(Content()))
- <class 'zope.location.location.LocationProxy'>
+.. doctest::
+ >>> IApp(Content()).__class__
+ <class 'zope.component.testfiles.components.Comp'>
+ >>> type(IApp(Content()))
+ <class 'zope.location.location.LocationProxy'>
+
We can also go about it a different way. Let's make a public adapter
and wrap the adapter in a security proxy. That often happens when
an adapter is turned over to untrusted code:
- >>> clearZCML()
- >>> IApp(Content(), None) is None
- True
+.. doctest::
- >>> runSnippet('''
- ... <adapter
- ... factory="zope.component.testfiles.components.Comp"
- ... provides="zope.component.testfiles.components.IApp"
- ... for="zope.component.testfiles.components.IContent"
- ... permission="zope.Public"
- ... />''')
+ >>> clearZCML()
+ >>> IApp(Content(), None) is None
+ True
- >>> from zope.security.checker import ProxyFactory
- >>> adapter = ProxyFactory(IApp(Content()))
- >>> from zope.security.proxy import getTestProxyItems
- >>> items = [item[0] for item in getTestProxyItems(adapter)]
- >>> items
- ['a', 'f']
+ >>> runSnippet('''
+ ... <adapter
+ ... factory="zope.component.testfiles.components.Comp"
+ ... provides="zope.component.testfiles.components.IApp"
+ ... for="zope.component.testfiles.components.IContent"
+ ... permission="zope.Public"
+ ... />''')
- >>> from zope.security.proxy import removeSecurityProxy
- >>> removeSecurityProxy(adapter).__class__ is Comp
- True
+ >>> from zope.security.checker import ProxyFactory
+ >>> adapter = ProxyFactory(IApp(Content()))
+ >>> from zope.security.proxy import getTestProxyItems
+ >>> items = [item[0] for item in getTestProxyItems(adapter)]
+ >>> items
+ ['a', 'f']
+ >>> from zope.security.proxy import removeSecurityProxy
+ >>> removeSecurityProxy(adapter).__class__ is Comp
+ True
+
Of course, this still works when we let the ZCML directive handler
figure out ``for`` and ``provides`` from the Python declarations:
- >>> clearZCML()
- >>> runSnippet('''
- ... <adapter
- ... factory="zope.component.testfiles.components.Comp"
- ... permission="zope.Public"
- ... />''')
+.. doctest::
- >>> adapter = ProxyFactory(IApp(Content()))
- >>> [item[0] for item in getTestProxyItems(adapter)]
- ['a', 'f']
- >>> removeSecurityProxy(adapter).__class__ is Comp
- True
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <adapter
+ ... factory="zope.component.testfiles.components.Comp"
+ ... permission="zope.Public"
+ ... />''')
+ >>> adapter = ProxyFactory(IApp(Content()))
+ >>> [item[0] for item in getTestProxyItems(adapter)]
+ ['a', 'f']
+ >>> removeSecurityProxy(adapter).__class__ is Comp
+ True
+
It also works with multi adapters:
- >>> clearZCML()
- >>> runSnippet('''
- ... <adapter
- ... factory="zope.component.testfiles.adapter.A3"
- ... provides="zope.component.testfiles.adapter.I3"
- ... for="zope.component.testfiles.components.IContent
- ... zope.component.testfiles.adapter.I1
- ... zope.component.testfiles.adapter.I2"
- ... permission="zope.Public"
- ... />''')
+.. doctest::
- >>> content = Content()
- >>> a1 = A1()
- >>> a2 = A2()
- >>> a3 = ProxyFactory(zope.component.queryMultiAdapter((content, a1, a2), I3))
- >>> a3.__class__ == A3
- True
- >>> [item[0] for item in getTestProxyItems(a3)]
- ['f1', 'f2', 'f3']
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <adapter
+ ... factory="zope.component.testfiles.adapter.A3"
+ ... provides="zope.component.testfiles.adapter.I3"
+ ... for="zope.component.testfiles.components.IContent
+ ... zope.component.testfiles.adapter.I1
+ ... zope.component.testfiles.adapter.I2"
+ ... permission="zope.Public"
+ ... />''')
+ >>> content = Content()
+ >>> a1 = A1()
+ >>> a2 = A2()
+ >>> a3 = ProxyFactory(zope.component.queryMultiAdapter((content, a1, a2), I3))
+ >>> a3.__class__ == A3
+ True
+ >>> [item[0] for item in getTestProxyItems(a3)]
+ ['f1', 'f2', 'f3']
+
It's probably not worth mentioning, but when we try to protect an
adapter with a permission that doesn't exist, we'll obviously get an
error:
- >>> clearZCML()
- >>> runSnippet('''
- ... <adapter
- ... factory="zope.component.testfiles.components.Comp"
- ... provides="zope.component.testfiles.components.IApp"
- ... for="zope.component.testfiles.components.IContent"
- ... permission="zope.UndefinedPermission"
- ... />''')
- Traceback (most recent call last):
- ...
- ConfigurationExecutionError: exceptions.ValueError: ('Undefined permission id', 'zope.UndefinedPermission')
- in:
- File "<string>", line 4.2-9.8
- Could not read source.
+.. doctest::
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <adapter
+ ... factory="zope.component.testfiles.components.Comp"
+ ... provides="zope.component.testfiles.components.IApp"
+ ... for="zope.component.testfiles.components.IContent"
+ ... permission="zope.UndefinedPermission"
+ ... />''')
+ Traceback (most recent call last):
+ ...
+ ConfigurationExecutionError: exceptions.ValueError: ('Undefined permission id', 'zope.UndefinedPermission')
+ in:
+ File "<string>", line 4.2-9.8
+ Could not read source.
+
Trusted adapters
~~~~~~~~~~~~~~~~
@@ -412,126 +460,146 @@
They are registered using the ``trusted`` argument to the <adapter />
directive:
- >>> clearZCML()
- >>> runSnippet('''
- ... <adapter
- ... for="zope.component.testfiles.components.IContent"
- ... provides="zope.component.testfiles.adapter.I1"
- ... factory="zope.component.testfiles.adapter.A1"
- ... trusted="yes"
- ... />''')
+.. doctest::
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <adapter
+ ... for="zope.component.testfiles.components.IContent"
+ ... provides="zope.component.testfiles.adapter.I1"
+ ... factory="zope.component.testfiles.adapter.A1"
+ ... trusted="yes"
+ ... />''')
+
With an unproxied object, it's business as usual:
- >>> ob = Content()
- >>> type(I1(ob)) is A1
- True
+.. doctest::
+ >>> ob = Content()
+ >>> type(I1(ob)) is A1
+ True
+
With a security-proxied object, however, we get a security-proxied
adapter:
- >>> p = ProxyFactory(ob)
- >>> a = I1(p)
- >>> type(a)
- <type 'zope.security._proxy._Proxy'>
+.. doctest::
+ >>> p = ProxyFactory(ob)
+ >>> a = I1(p)
+ >>> type(a)
+ <type 'zope.security._proxy._Proxy'>
+
While the adapter is security-proxied, the object it adapts is now
proxy-free. The adapter has umlimited access to it:
- >>> a = removeSecurityProxy(a)
- >>> type(a) is A1
- True
- >>> a.context[0] is ob
- True
+.. doctest::
+ >>> a = removeSecurityProxy(a)
+ >>> type(a) is A1
+ True
+ >>> a.context[0] is ob
+ True
+
We can also protect the trusted adapter with a permission:
- >>> clearZCML()
- >>> XMLConfig('meta.zcml', zope.security)()
- >>> runSnippet('''
- ... <permission
- ... id="y.x"
- ... title="XY"
- ... description="Allow XY."
- ... />
- ... <adapter
- ... for="zope.component.testfiles.components.IContent"
- ... provides="zope.component.testfiles.adapter.I1"
- ... factory="zope.component.testfiles.adapter.A1"
- ... permission="y.x"
- ... trusted="yes"
- ... />''')
+.. doctest::
+ >>> clearZCML()
+ >>> XMLConfig('meta.zcml', zope.security)()
+ >>> runSnippet('''
+ ... <permission
+ ... id="y.x"
+ ... title="XY"
+ ... description="Allow XY."
+ ... />
+ ... <adapter
+ ... for="zope.component.testfiles.components.IContent"
+ ... provides="zope.component.testfiles.adapter.I1"
+ ... factory="zope.component.testfiles.adapter.A1"
+ ... permission="y.x"
+ ... trusted="yes"
+ ... />''')
+
Again, with an unproxied object, it's business as usual:
- >>> ob = Content()
- >>> type(I1(ob)) is A1
- True
+.. doctest::
+ >>> ob = Content()
+ >>> type(I1(ob)) is A1
+ True
+
With a security-proxied object, we again get a security-proxied
adapter:
- >>> p = ProxyFactory(ob)
- >>> a = I1(p)
- >>> type(a)
- <type 'zope.security._proxy._Proxy'>
+.. doctest::
+ >>> p = ProxyFactory(ob)
+ >>> a = I1(p)
+ >>> type(a)
+ <type 'zope.security._proxy._Proxy'>
+
Since we protected the adapter with a permission, we now encounter a
location proxy behind the security proxy:
- >>> a = removeSecurityProxy(a)
- >>> type(a)
- <class 'zope.location.location.LocationProxy'>
- >>> a.context[0] is ob
- True
+.. doctest::
+ >>> a = removeSecurityProxy(a)
+ >>> type(a)
+ <class 'zope.location.location.LocationProxy'>
+ >>> a.context[0] is ob
+ True
+
There's one exception to all of this: When you use the public
permission (``zope.Public``), there will be no location proxy:
- >>> clearZCML()
- >>> runSnippet('''
- ... <adapter
- ... for="zope.component.testfiles.components.IContent"
- ... provides="zope.component.testfiles.adapter.I1"
- ... factory="zope.component.testfiles.adapter.A1"
- ... permission="zope.Public"
- ... trusted="yes"
- ... />''')
+.. doctest::
- >>> ob = Content()
- >>> p = ProxyFactory(ob)
- >>> a = I1(p)
- >>> type(a)
- <type 'zope.security._proxy._Proxy'>
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <adapter
+ ... for="zope.component.testfiles.components.IContent"
+ ... provides="zope.component.testfiles.adapter.I1"
+ ... factory="zope.component.testfiles.adapter.A1"
+ ... permission="zope.Public"
+ ... trusted="yes"
+ ... />''')
- >>> a = removeSecurityProxy(a)
- >>> type(a) is A1
- True
+ >>> ob = Content()
+ >>> p = ProxyFactory(ob)
+ >>> a = I1(p)
+ >>> type(a)
+ <type 'zope.security._proxy._Proxy'>
+ >>> a = removeSecurityProxy(a)
+ >>> type(a) is A1
+ True
+
We can also explicitply pass the ``locate`` argument to make sure we
get location proxies:
- >>> clearZCML()
- >>> runSnippet('''
- ... <adapter
- ... for="zope.component.testfiles.components.IContent"
- ... provides="zope.component.testfiles.adapter.I1"
- ... factory="zope.component.testfiles.adapter.A1"
- ... trusted="yes"
- ... locate="yes"
- ... />''')
+.. doctest::
- >>> ob = Content()
- >>> p = ProxyFactory(ob)
- >>> a = I1(p)
- >>> type(a)
- <type 'zope.security._proxy._Proxy'>
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <adapter
+ ... for="zope.component.testfiles.components.IContent"
+ ... provides="zope.component.testfiles.adapter.I1"
+ ... factory="zope.component.testfiles.adapter.A1"
+ ... trusted="yes"
+ ... locate="yes"
+ ... />''')
- >>> a = removeSecurityProxy(a)
- >>> type(a)
- <class 'zope.location.location.LocationProxy'>
+ >>> ob = Content()
+ >>> p = ProxyFactory(ob)
+ >>> a = I1(p)
+ >>> type(a)
+ <type 'zope.security._proxy._Proxy'>
+ >>> a = removeSecurityProxy(a)
+ >>> type(a)
+ <class 'zope.location.location.LocationProxy'>
+
subscriber
----------
@@ -539,61 +607,67 @@
adapters or event subscribers with the adapter registry. Consider
this very typical example of a <subscriber /> directive:
- >>> clearZCML()
- >>> runSnippet('''
- ... <subscriber
- ... provides="zope.component.testfiles.adapter.IS"
- ... factory="zope.component.testfiles.adapter.A3"
- ... for="zope.component.testfiles.components.IContent
- ... zope.component.testfiles.adapter.I1"
- ... />''')
+.. doctest::
- >>> content = Content()
- >>> a1 = A1()
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <subscriber
+ ... provides="zope.component.testfiles.adapter.IS"
+ ... factory="zope.component.testfiles.adapter.A3"
+ ... for="zope.component.testfiles.components.IContent
+ ... zope.component.testfiles.adapter.I1"
+ ... />''')
- >>> subscribers = zope.component.subscribers((content, a1), IS)
- >>> a3 = subscribers[0]
- >>> a3.__class__ is A3
- True
- >>> a3.context == (content, a1)
- True
+ >>> content = Content()
+ >>> a1 = A1()
+ >>> subscribers = zope.component.subscribers((content, a1), IS)
+ >>> a3 = subscribers[0]
+ >>> a3.__class__ is A3
+ True
+ >>> a3.context == (content, a1)
+ True
+
Note how ZCML provides some additional information when registering
components, such as the ZCML filename and line numbers:
- >>> sm = zope.component.getSiteManager()
- >>> doc = [reg.info for reg in sm.registeredSubscriptionAdapters()
- ... if reg.provided is IS][0]
- >>> print doc
- File "<string>", line 4.2-9.8
- Could not read source.
+.. doctest::
+ >>> sm = zope.component.getSiteManager()
+ >>> doc = [reg.info for reg in sm.registeredSubscriptionAdapters()
+ ... if reg.provided is IS][0]
+ >>> print doc
+ File "<string>", line 4.2-9.8
+ Could not read source.
+
The "fun" behind subscription adapters/subscribers is that when
several ones are declared for the same for/provides, they are all
found. With regular adapters, the most specific one (and in doubt the
one registered last) wins. Consider these two subscribers:
- >>> clearZCML()
- >>> runSnippet('''
- ... <subscriber
- ... provides="zope.component.testfiles.adapter.IS"
- ... factory="zope.component.testfiles.adapter.A3"
- ... for="zope.component.testfiles.components.IContent
- ... zope.component.testfiles.adapter.I1"
- ... />
- ... <subscriber
- ... provides="zope.component.testfiles.adapter.IS"
- ... factory="zope.component.testfiles.adapter.A2"
- ... for="zope.component.testfiles.components.IContent
- ... zope.component.testfiles.adapter.I1"
- ... />''')
+.. doctest::
- >>> subscribers = zope.component.subscribers((content, a1), IS)
- >>> len(subscribers)
- 2
- >>> sorted([a.__class__.__name__ for a in subscribers])
- ['A2', 'A3']
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <subscriber
+ ... provides="zope.component.testfiles.adapter.IS"
+ ... factory="zope.component.testfiles.adapter.A3"
+ ... for="zope.component.testfiles.components.IContent
+ ... zope.component.testfiles.adapter.I1"
+ ... />
+ ... <subscriber
+ ... provides="zope.component.testfiles.adapter.IS"
+ ... factory="zope.component.testfiles.adapter.A2"
+ ... for="zope.component.testfiles.components.IContent
+ ... zope.component.testfiles.adapter.I1"
+ ... />''')
+ >>> subscribers = zope.component.subscribers((content, a1), IS)
+ >>> len(subscribers)
+ 2
+ >>> sorted([a.__class__.__name__ for a in subscribers])
+ ['A2', 'A3']
+
Declaring ``for`` and ``provides`` in Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -602,56 +676,64 @@
``zope.component.adapts()`` or ``zope.component.adapter()``) what the
subscriber should be registered for:
- >>> clearZCML()
- >>> runSnippet('''
- ... <subscriber
- ... provides="zope.component.testfiles.adapter.IS"
- ... factory="zope.component.testfiles.adapter.A3"
- ... />''')
+.. doctest::
- >>> content = Content()
- >>> a2 = A2()
- >>> subscribers = zope.component.subscribers((content, a1, a2), IS)
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <subscriber
+ ... provides="zope.component.testfiles.adapter.IS"
+ ... factory="zope.component.testfiles.adapter.A3"
+ ... />''')
- >>> a3 = subscribers[0]
- >>> a3.__class__ is A3
- True
- >>> a3.context == (content, a1, a2)
- True
+ >>> content = Content()
+ >>> a2 = A2()
+ >>> subscribers = zope.component.subscribers((content, a1, a2), IS)
+ >>> a3 = subscribers[0]
+ >>> a3.__class__ is A3
+ True
+ >>> a3.context == (content, a1, a2)
+ True
+
In the same way the directive can figure out what a subscriber
provides:
- >>> clearZCML()
- >>> runSnippet('''
- ... <subscriber handler="zope.component.testfiles.adapter.A3" />''')
+.. doctest::
- >>> sm = zope.component.getSiteManager()
- >>> a3 = sm.adapters.subscriptions((IContent, I1, I2), None)[0]
- >>> a3 is A3
- True
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <subscriber handler="zope.component.testfiles.adapter.A3" />''')
+ >>> sm = zope.component.getSiteManager()
+ >>> a3 = sm.adapters.subscriptions((IContent, I1, I2), None)[0]
+ >>> a3 is A3
+ True
+
A not so common edge case is declaring subscribers directly for
classes, not for interfaces. For example:
- >>> clearZCML()
- >>> runSnippet('''
- ... <subscriber
- ... for="zope.component.testfiles.components.Content"
- ... provides="zope.component.testfiles.adapter.I1"
- ... factory="zope.component.testfiles.adapter.A1"
- ... />''')
+.. doctest::
- >>> subs = list(zope.component.subscribers((Content(),), I1))
- >>> isinstance(subs[0], A1)
- True
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <subscriber
+ ... for="zope.component.testfiles.components.Content"
+ ... provides="zope.component.testfiles.adapter.I1"
+ ... factory="zope.component.testfiles.adapter.A1"
+ ... />''')
+ >>> subs = list(zope.component.subscribers((Content(),), I1))
+ >>> isinstance(subs[0], A1)
+ True
+
This time, any object providing ``IContent`` won't work if it's not an
instance of the ``Content`` class:
- >>> list(zope.component.subscribers((MyContent(),), I1))
- []
+.. doctest::
+ >>> list(zope.component.subscribers((MyContent(),), I1))
+ []
+
Protected subscribers
~~~~~~~~~~~~~~~~~~~~~
@@ -659,31 +741,33 @@
define a permission for which we'll have to register the <permission />
directive:
- >>> clearZCML()
- >>> XMLConfig('meta.zcml', zope.security)()
- >>> runSnippet('''
- ... <permission
- ... id="y.x"
- ... title="XY"
- ... description="Allow XY."
- ... />
- ... <subscriber
- ... provides="zope.component.testfiles.adapter.IS"
- ... factory="zope.component.testfiles.adapter.A3"
- ... for="zope.component.testfiles.components.IContent
- ... zope.component.testfiles.adapter.I1"
- ... permission="y.x"
- ... />''')
+.. doctest::
- >>> subscribers = zope.component.subscribers((content, a1), IS)
- >>> a3 = subscribers[0]
- >>> a3.__class__ is A3
- True
- >>> type(a3)
- <class 'zope.location.location.LocationProxy'>
- >>> a3.context == (content, a1)
- True
+ >>> clearZCML()
+ >>> XMLConfig('meta.zcml', zope.security)()
+ >>> runSnippet('''
+ ... <permission
+ ... id="y.x"
+ ... title="XY"
+ ... description="Allow XY."
+ ... />
+ ... <subscriber
+ ... provides="zope.component.testfiles.adapter.IS"
+ ... factory="zope.component.testfiles.adapter.A3"
+ ... for="zope.component.testfiles.components.IContent
+ ... zope.component.testfiles.adapter.I1"
+ ... permission="y.x"
+ ... />''')
+ >>> subscribers = zope.component.subscribers((content, a1), IS)
+ >>> a3 = subscribers[0]
+ >>> a3.__class__ is A3
+ True
+ >>> type(a3)
+ <class 'zope.location.location.LocationProxy'>
+ >>> a3.context == (content, a1)
+ True
+
Trusted subscribers
~~~~~~~~~~~~~~~~~~~
@@ -693,106 +777,126 @@
directive, they are registered using the ``trusted`` argument to the
<subscriber /> directive:
- >>> clearZCML()
- >>> runSnippet('''
- ... <subscriber
- ... provides="zope.component.testfiles.adapter.IS"
- ... factory="zope.component.testfiles.adapter.A3"
- ... for="zope.component.testfiles.components.IContent
- ... zope.component.testfiles.adapter.I1"
- ... trusted="yes"
- ... />''')
+.. doctest::
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <subscriber
+ ... provides="zope.component.testfiles.adapter.IS"
+ ... factory="zope.component.testfiles.adapter.A3"
+ ... for="zope.component.testfiles.components.IContent
+ ... zope.component.testfiles.adapter.I1"
+ ... trusted="yes"
+ ... />''')
+
With an unproxied object, it's business as usual:
- >>> subscribers = zope.component.subscribers((content, a1), IS)
- >>> a3 = subscribers[0]
- >>> a3.__class__ is A3
- True
- >>> a3.context == (content, a1)
- True
- >>> type(a3) is A3
- True
+.. doctest::
+ >>> subscribers = zope.component.subscribers((content, a1), IS)
+ >>> a3 = subscribers[0]
+ >>> a3.__class__ is A3
+ True
+ >>> a3.context == (content, a1)
+ True
+ >>> type(a3) is A3
+ True
+
Now with a proxied object. We will see that the subscriber has
unproxied access to it, but the subscriber itself is proxied:
- >>> p = ProxyFactory(content)
- >>> a3 = zope.component.subscribers((p, a1), IS)[0]
- >>> type(a3)
- <type 'zope.security._proxy._Proxy'>
+.. doctest::
+ >>> p = ProxyFactory(content)
+ >>> a3 = zope.component.subscribers((p, a1), IS)[0]
+ >>> type(a3)
+ <type 'zope.security._proxy._Proxy'>
+
There's no location proxy behind the security proxy:
- >>> removeSecurityProxy(a3).context[0] is content
- True
- >>> type(removeSecurityProxy(a3)) is A3
- True
+.. doctest::
+ >>> removeSecurityProxy(a3).context[0] is content
+ True
+ >>> type(removeSecurityProxy(a3)) is A3
+ True
+
If you want the trusted subscriber to be located, you'll also have to
use the ``locate`` argument:
- >>> clearZCML()
- >>> runSnippet('''
- ... <subscriber
- ... provides="zope.component.testfiles.adapter.IS"
- ... factory="zope.component.testfiles.adapter.A3"
- ... for="zope.component.testfiles.components.IContent
- ... zope.component.testfiles.adapter.I1"
- ... trusted="yes"
- ... locate="yes"
- ... />''')
+.. doctest::
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <subscriber
+ ... provides="zope.component.testfiles.adapter.IS"
+ ... factory="zope.component.testfiles.adapter.A3"
+ ... for="zope.component.testfiles.components.IContent
+ ... zope.component.testfiles.adapter.I1"
+ ... trusted="yes"
+ ... locate="yes"
+ ... />''')
+
Again, it's business as usual with an unproxied object:
- >>> subscribers = zope.component.subscribers((content, a1), IS)
- >>> a3 = subscribers[0]
- >>> a3.__class__ is A3
- True
- >>> a3.context == (content, a1)
- True
- >>> type(a3) is A3
- True
+.. doctest::
+ >>> subscribers = zope.component.subscribers((content, a1), IS)
+ >>> a3 = subscribers[0]
+ >>> a3.__class__ is A3
+ True
+ >>> a3.context == (content, a1)
+ True
+ >>> type(a3) is A3
+ True
+
With a proxied object, we again get a security-proxied subscriber:
- >>> p = ProxyFactory(content)
- >>> a3 = zope.component.subscribers((p, a1), IS)[0]
+.. doctest::
- >>> type(a3)
- <type 'zope.security._proxy._Proxy'>
+ >>> p = ProxyFactory(content)
+ >>> a3 = zope.component.subscribers((p, a1), IS)[0]
- >>> removeSecurityProxy(a3).context[0] is content
- True
+ >>> type(a3)
+ <type 'zope.security._proxy._Proxy'>
+ >>> removeSecurityProxy(a3).context[0] is content
+ True
+
However, thanks to the ``locate`` argument, we now have a location
proxy behind the security proxy:
- >>> type(removeSecurityProxy(a3))
- <class 'zope.location.location.LocationProxy'>
+.. doctest::
+ >>> type(removeSecurityProxy(a3))
+ <class 'zope.location.location.LocationProxy'>
+
Event subscriber (handlers)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sometimes, subscribers don't need to be adapters that actually provide
anything. It's enough that a callable is called for a certain event.
- >>> clearZCML()
- >>> runSnippet('''
- ... <subscriber
- ... for="zope.component.testfiles.components.IContent
- ... zope.component.testfiles.adapter.I1"
- ... handler="zope.component.testfiles.adapter.Handler"
- ... />''')
+.. doctest::
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <subscriber
+ ... for="zope.component.testfiles.components.IContent
+ ... zope.component.testfiles.adapter.I1"
+ ... handler="zope.component.testfiles.adapter.Handler"
+ ... />''')
+
In this case, simply getting the subscribers is enough to invoke them:
- >>> list(zope.component.subscribers((content, a1), None))
- []
- >>> content.args == ((a1,),)
- True
+.. doctest::
+ >>> list(zope.component.subscribers((content, a1), None))
+ []
+ >>> content.args == ((a1,),)
+ True
+
utility
-------
@@ -803,118 +907,136 @@
Before we register the first test utility, we can verify that utility
lookup doesn't work yet:
- >>> clearZCML()
- >>> zope.component.queryUtility(IApp) is None
- True
+.. doctest::
+ >>> clearZCML()
+ >>> zope.component.queryUtility(IApp) is None
+ True
+
Then we register the utility:
- >>> runSnippet('''
- ... <utility
- ... component="zope.component.testfiles.components.comp"
- ... provides="zope.component.testfiles.components.IApp"
- ... />''')
- >>> zope.component.getUtility(IApp) is comp
- True
+.. doctest::
+ >>> runSnippet('''
+ ... <utility
+ ... component="zope.component.testfiles.components.comp"
+ ... provides="zope.component.testfiles.components.IApp"
+ ... />''')
+ >>> zope.component.getUtility(IApp) is comp
+ True
+
Like adapters, utilities can also have names. There can be more than
one utility registered for a certain interface, as long as they each
have a different name.
First, we make sure that there's no utility yet:
- >>> clearZCML()
- >>> zope.component.queryUtility(IApp, 'test') is None
- True
+.. doctest::
+ >>> clearZCML()
+ >>> zope.component.queryUtility(IApp, 'test') is None
+ True
+
Then we register it:
- >>> runSnippet('''
- ... <utility
- ... component="zope.component.testfiles.components.comp"
- ... provides="zope.component.testfiles.components.IApp"
- ... name="test"
- ... />''')
- >>> zope.component.getUtility(IApp, 'test') is comp
- True
+.. doctest::
+ >>> runSnippet('''
+ ... <utility
+ ... component="zope.component.testfiles.components.comp"
+ ... provides="zope.component.testfiles.components.IApp"
+ ... name="test"
+ ... />''')
+ >>> zope.component.getUtility(IApp, 'test') is comp
+ True
+
Utilities can also be registered from a factory. In this case, the
ZCML handler calls the factory (without any arguments) and registers
the returned value as a utility. Typically, you'd pass a class for
the factory:
- >>> clearZCML()
- >>> zope.component.queryUtility(IApp) is None
- True
+.. doctest::
- >>> runSnippet('''
- ... <utility
- ... factory="zope.component.testfiles.components.Comp"
- ... provides="zope.component.testfiles.components.IApp"
- ... />''')
- >>> zope.component.getUtility(IApp).__class__ is Comp
- True
+ >>> clearZCML()
+ >>> zope.component.queryUtility(IApp) is None
+ True
+ >>> runSnippet('''
+ ... <utility
+ ... factory="zope.component.testfiles.components.Comp"
+ ... provides="zope.component.testfiles.components.IApp"
+ ... />''')
+ >>> zope.component.getUtility(IApp).__class__ is Comp
+ True
+
Declaring ``provides`` in Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Like other directives, <utility /> can also figure out which interface
a utility provides from the Python declaration:
- >>> clearZCML()
- >>> zope.component.queryUtility(IApp) is None
- True
+.. doctest::
- >>> runSnippet('''
- ... <utility component="zope.component.testfiles.components.comp" />''')
- >>> zope.component.getUtility(IApp) is comp
- True
+ >>> clearZCML()
+ >>> zope.component.queryUtility(IApp) is None
+ True
+ >>> runSnippet('''
+ ... <utility component="zope.component.testfiles.components.comp" />''')
+ >>> zope.component.getUtility(IApp) is comp
+ True
+
It won't work if the component that is to be registered doesn't
provide anything:
- >>> clearZCML()
- >>> runSnippet('''
- ... <utility component="zope.component.testfiles.adapter.a4" />''')
- Traceback (most recent call last):
- ...
- ZopeXMLConfigurationError: File "<string>", line 4.2-4.61
- TypeError: Missing 'provides' attribute
+.. doctest::
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <utility component="zope.component.testfiles.adapter.a4" />''')
+ Traceback (most recent call last):
+ ...
+ ZopeXMLConfigurationError: File "<string>", line 4.2-4.61
+ TypeError: Missing 'provides' attribute
+
Or if more than one interface is provided (then the ZCML directive
handler doesn't know under which the utility should be registered):
- >>> clearZCML()
- >>> runSnippet('''
- ... <utility component="zope.component.testfiles.adapter.a5" />''')
- Traceback (most recent call last):
- ...
- ZopeXMLConfigurationError: File "<string>", line 4.2-4.61
- TypeError: Missing 'provides' attribute
+.. doctest::
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <utility component="zope.component.testfiles.adapter.a5" />''')
+ Traceback (most recent call last):
+ ...
+ ZopeXMLConfigurationError: File "<string>", line 4.2-4.61
+ TypeError: Missing 'provides' attribute
+
We can repeat the same drill for utility factories:
- >>> clearZCML()
- >>> runSnippet('''
- ... <utility factory="zope.component.testfiles.components.Comp" />''')
- >>> zope.component.getUtility(IApp).__class__ is Comp
- True
+.. doctest::
- >>> runSnippet('''
- ... <utility factory="zope.component.testfiles.adapter.A4" />''')
- Traceback (most recent call last):
- ...
- ZopeXMLConfigurationError: File "<string>", line 4.2-4.59
- TypeError: Missing 'provides' attribute
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <utility factory="zope.component.testfiles.components.Comp" />''')
+ >>> zope.component.getUtility(IApp).__class__ is Comp
+ True
- >>> clearZCML()
- >>> runSnippet('''
- ... <utility factory="zope.component.testfiles.adapter.A5" />''')
- Traceback (most recent call last):
- ...
- ZopeXMLConfigurationError: File "<string>", line 4.2-4.59
- TypeError: Missing 'provides' attribute
+ >>> runSnippet('''
+ ... <utility factory="zope.component.testfiles.adapter.A4" />''')
+ Traceback (most recent call last):
+ ...
+ ZopeXMLConfigurationError: File "<string>", line 4.2-4.59
+ TypeError: Missing 'provides' attribute
+ >>> clearZCML()
+ >>> runSnippet('''
+ ... <utility factory="zope.component.testfiles.adapter.A5" />''')
+ Traceback (most recent call last):
+ ...
+ ZopeXMLConfigurationError: File "<string>", line 4.2-4.59
+ TypeError: Missing 'provides' attribute
+
Protected utilities
~~~~~~~~~~~~~~~~~~~
@@ -975,47 +1097,57 @@
First we provide a stub configuration context:
- >>> import re, pprint
- >>> atre = re.compile(' at [0-9a-fA-Fx]+')
- >>> class Context(object):
- ... actions = ()
- ... def action(self, discriminator, callable, args):
- ... self.actions += ((discriminator, callable, args), )
- ... def __repr__(self):
- ... stream = StringIO()
- ... pprinter = pprint.PrettyPrinter(stream=stream, width=60)
- ... pprinter.pprint(self.actions)
- ... r = stream.getvalue()
- ... return (''.join(atre.split(r))).strip()
- >>> context = Context()
+.. doctest::
+ >>> import re, pprint
+ >>> atre = re.compile(' at [0-9a-fA-Fx]+')
+ >>> class Context(object):
+ ... actions = ()
+ ... def action(self, discriminator, callable, args):
+ ... self.actions += ((discriminator, callable, args), )
+ ... def __repr__(self):
+ ... stream = StringIO()
+ ... pprinter = pprint.PrettyPrinter(stream=stream, width=60)
+ ... pprinter.pprint(self.actions)
+ ... r = stream.getvalue()
+ ... return (''.join(atre.split(r))).strip()
+ >>> context = Context()
+
Then we provide a test interface that we'd like to register:
- >>> from zope.interface import Interface
- >>> class I(Interface):
- ... pass
+.. doctest::
+ >>> from zope.interface import Interface
+ >>> class I(Interface):
+ ... pass
+
It doesn't yet provide ``ITestType``:
- >>> from zope.component.tests.test_doctests import ITestType
- >>> ITestType.providedBy(I)
- False
+.. doctest::
+ >>> from zope.component.tests.test_doctests import ITestType
+ >>> ITestType.providedBy(I)
+ False
+
However, after calling the directive handler...
- >>> from zope.component.zcml import interface
- >>> interface(context, I, ITestType)
- >>> context
- ((None,
- <function provideInterface>,
- ('',
- <InterfaceClass __builtin__.I>,
- <InterfaceClass zope.component.tests.test_doctests.ITestType>)),)
+.. doctest::
+ >>> from zope.component.zcml import interface
+ >>> interface(context, I, ITestType)
+ >>> context
+ ((None,
+ <function provideInterface>,
+ ('',
+ <InterfaceClass __builtin__.I>,
+ <InterfaceClass zope.component.tests.test_doctests.ITestType>)),)
+
...it does provide ``ITestType``:
- >>> from zope.interface.interfaces import IInterface
- >>> ITestType.extends(IInterface)
- True
- >>> IInterface.providedBy(I)
- True
+.. doctest::
+
+ >>> from zope.interface.interfaces import IInterface
+ >>> ITestType.extends(IInterface)
+ True
+ >>> IInterface.providedBy(I)
+ True
More information about the checkins
mailing list