[Checkins] SVN: zope.component/tseaver-test_cleanup/ The core registry stuff is documented in zope.interface.
Tres Seaver
cvs-admin at zope.org
Sun Jun 17 18:32:00 UTC 2012
Log message for revision 126892:
The core registry stuff is documented in zope.interface.
Changed:
_U zope.component/tseaver-test_cleanup/
U zope.component/tseaver-test_cleanup/docs/index.rst
D zope.component/tseaver-test_cleanup/docs/registry.rst
-=-
Modified: zope.component/tseaver-test_cleanup/docs/index.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/index.rst 2012-06-17 18:31:53 UTC (rev 126891)
+++ zope.component/tseaver-test_cleanup/docs/index.rst 2012-06-17 18:31:57 UTC (rev 126892)
@@ -10,7 +10,6 @@
socketexample
event
factory
- registry
persistentregistry
zcml
configure
Deleted: zope.component/tseaver-test_cleanup/docs/registry.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/registry.rst 2012-06-17 18:31:53 UTC (rev 126891)
+++ zope.component/tseaver-test_cleanup/docs/registry.rst 2012-06-17 18:31:57 UTC (rev 126892)
@@ -1,1117 +0,0 @@
-Component-Management objects
-============================
-
-Component-management objects provide a higher-level
-component-management API over the basic adapter-registration API
-provided by the zope.interface package. In particular, it provides:
-
-- utilities
-
-- support for computing adapters, rather than just looking up adapter
- factories.
-
-- management of registration comments
-
-The zope.component.registry.Components class provides an
-implementation of zope.component.interfaces.IComponents that provides
-these features.
-
- >>> from zope.component import registry
- >>> from zope.component import tests
- >>> components = registry.Components('comps')
-
-As components are registered, events are generated. Let's register
-an event subscriber, so we can see the events generated:
-
- >>> import zope.event
- >>> def logevent(event):
- ... print event
- >>> zope.event.subscribers.append(logevent)
-
-Utilities
----------
-
-You can register Utilities using registerUtility:
-
- >>> components.registerUtility(tests.U1(1))
- Registered event:
- UtilityRegistration(<Components comps>, I1, u'', 1, None, u'')
-
-Here we didn't specify an interface or name. An unnamed utility was
-registered for interface I1, since that is only interface implemented
-by the U1 class:
-
- >>> components.getUtility(tests.I1)
- U1(1)
-
-You can also register a utility using a factory instead of a utility instance:
-
- >>> def factory():
- ... return tests.U1(1)
- >>> components.registerUtility(factory=factory)
- Unregistered event:
- UtilityRegistration(<Components comps>, I1, u'', 1, None, u'')
- Registered event:
- UtilityRegistration(<Components comps>, I1, u'', 1, <function factory at <SOME ADDRESS>>, u'')
-
-
-If a component implements other than one interface or no interface,
-then an error will be raised:
-
- >>> components.registerUtility(tests.U12(2))
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The utility doesn't provide a single interface and
- no provided interface was specified.
-
- >>> components.registerUtility(tests.A)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The utility doesn't provide a single interface and
- no provided interface was specified.
-
-
-We can provide an interface if desired:
-
- >>> components.registerUtility(tests.U12(2), tests.I2)
- Registered event:
- UtilityRegistration(<Components comps>, I2, u'', 2, None, u'')
-
-and we can specify a name:
-
- >>> components.registerUtility(tests.U12(3), tests.I2, u'three')
- Registered event:
- UtilityRegistration(<Components comps>, I2, u'three', 3, None, u'')
-
- >>> components.getUtility(tests.I2)
- U12(2)
-
- >>> components.getUtility(tests.I2, 'three')
- U12(3)
-
-If you try to get a utility that doesn't exist, you'll get a component
-lookup error:
-
- >>> components.getUtility(tests.I3)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- ComponentLookupError:
- (<InterfaceClass zope.component.tests.I3>, u'')
-
-Unless you use queryUtility:
-
- >>> components.queryUtility(tests.I3)
- >>> components.queryUtility(tests.I3, default=42)
- 42
-
-You can get information about registered utilities with the
-registeredUtilities method:
-
- >>> for registration in sorted(components.registeredUtilities()):
- ... print registration.provided, registration.name
- ... print registration.component, registration.info
- <InterfaceClass zope.component.tests.I1>
- U1(1)
- <InterfaceClass zope.component.tests.I2>
- U12(2)
- <InterfaceClass zope.component.tests.I2> three
- U12(3)
-
-Duplicate registrations replace existing ones:
-
- >>> components.registerUtility(tests.U1(4), info=u'use 4 now')
- Unregistered event:
- UtilityRegistration(<Components comps>, I1, u'', 1, <function factory at <SOME ADDRESS>>, u'')
- Registered event:
- UtilityRegistration(<Components comps>, I1, u'', 4, None, u'use 4 now')
- >>> components.getUtility(tests.I1)
- U1(4)
-
- >>> for registration in sorted(components.registeredUtilities()):
- ... print registration.provided, registration.name
- ... print registration.component, registration.info
- <InterfaceClass zope.component.tests.I1>
- U1(4) use 4 now
- <InterfaceClass zope.component.tests.I2>
- U12(2)
- <InterfaceClass zope.component.tests.I2> three
- U12(3)
-
-As shown in the this example, you can provide an "info" argumemnt when
-registering utilities. This provides extra documentation about the
-registration itself that is shown when listing registrations.
-
-You can also unregister utilities:
-
- >>> components.unregisterUtility(provided=tests.I1)
- Unregistered event:
- UtilityRegistration(<Components comps>, I1, u'', 4, None, u'use 4 now')
- True
-
-A boolean is returned indicating whether anything changed:
-
- >>> components.queryUtility(tests.I1)
- >>> for registration in sorted(components.registeredUtilities()):
- ... print registration.provided, registration.name
- ... print registration.component, registration.info
- <InterfaceClass zope.component.tests.I2>
- U12(2)
- <InterfaceClass zope.component.tests.I2> three
- U12(3)
-
-When you unregister, you can specify a component. If the component
-doesn't match the one registered, then nothing happens:
-
- >>> u5 = tests.U1(5)
- >>> components.registerUtility(u5)
- Registered event:
- UtilityRegistration(<Components comps>, I1, u'', 5, None, u'')
- >>> components.unregisterUtility(tests.U1(6))
- False
- >>> components.queryUtility(tests.I1)
- U1(5)
- >>> components.unregisterUtility(u5)
- Unregistered event:
- UtilityRegistration(<Components comps>, I1, u'', 5, None, u'')
- True
- >>> components.queryUtility(tests.I1)
-
-You can get the name and utility for all of the utilities that provide
-an interface using getUtilitiesFor:
-
- >>> sorted(components.getUtilitiesFor(tests.I2))
- [(u'', U12(2)), (u'three', U12(3))]
-
-getAllUtilitiesRegisteredFor is similar to getUtilitiesFor except that
-it includes utilities that are overridden. For example, we'll
-register a utility that for an extending interface of I2:
-
- >>> util = tests.U('ext')
- >>> components.registerUtility(util, tests.I2e)
- Registered event:
- UtilityRegistration(<Components comps>, I2e, u'', ext, None, u'')
-
-We don't get the new utility for getUtilitiesFor:
-
- >>> sorted(components.getUtilitiesFor(tests.I2))
- [(u'', U12(2)), (u'three', U12(3))]
-
-but we do get it from getAllUtilitiesRegisteredFor:
-
- >>> sorted(map(str, components.getAllUtilitiesRegisteredFor(tests.I2)))
- ['U(ext)', 'U12(2)', 'U12(3)']
-
-Removing a utility also makes it disappear from getUtilitiesFor:
-
- >>> components.unregisterUtility(util, tests.I2e)
- Unregistered event:
- UtilityRegistration(<Components comps>, I2e, u'', ext, None, u'')
- True
- >>> list(components.getAllUtilitiesRegisteredFor(tests.I2e))
- []
-
-Adapters
---------
-
-You can register adapters with registerAdapter:
-
- >>> components.registerAdapter(tests.A12_1)
- Registered event:
- AdapterRegistration(<Components comps>, [I1, I2], IA1, u'', A12_1, u'')
-
-Here, we didn't specify required interfaces, a provided interface, or
-a name. The required interfaces were determined from the factory
-s __component_adapts__ attribute and the provided interface was
-determined by introspecting what the factory implements.
-
- >>> components.getMultiAdapter((tests.U1(6), tests.U12(7)), tests.IA1)
- A12_1(U1(6), U12(7))
-
-If a factory implements more than one interface, an exception will be
-raised:
-
- >>> components.registerAdapter(tests.A1_12)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The adapter factory doesn't implement a single
- interface and no provided interface was specified.
-
-Unless the provided interface is specified:
-
- >>> components.registerAdapter(tests.A1_12, provided=tests.IA2)
- Registered event:
- AdapterRegistration(<Components comps>, [I1], IA2, u'', A1_12, u'')
-
-If a factory doesn't declare an implemented interface, an exception will be
-raised:
-
- >>> components.registerAdapter(tests.A12_)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The adapter factory doesn't implement a single
- interface and no provided interface was specified.
-
-Unless the provided interface is specified:
-
- >>> components.registerAdapter(tests.A12_, provided=tests.IA2)
- Registered event:
- AdapterRegistration(<Components comps>, [I1, I2], IA2, u'', A12_, u'')
-
-The required interface needs to be specified in the registration if
-the factory doesn't have a __component_adapts__ attribute:
-
- >>> components.registerAdapter(tests.A_2)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The adapter factory doesn't have a __component_adapts__
- attribute and no required specifications were specified
-
-Unless the required specifications specified:
-
- >>> components.registerAdapter(tests.A_2, required=[tests.I3])
- Registered event:
- AdapterRegistration(<Components comps>, [I3], IA2, u'', A_2, u'')
-
-Classes can be specified in place of specifications, in which case the
-implementedBy specification for the class is used:
-
- >>> components.registerAdapter(tests.A_3, required=[tests.U],
- ... info="Really class specific")
- ... # doctest: +NORMALIZE_WHITESPACE
- Registered event:
- AdapterRegistration(<Components comps>, [zope.component.tests.U], IA3, u'',
- A_3, 'Really class specific')
-
-We can see the adapters that have been registered using the
-registeredAdapters method:
-
- >>> for registration in sorted(components.registeredAdapters()):
- ... print registration.required
- ... print registration.provided, registration.name
- ... print registration.factory, registration.info
- ... # doctest: +NORMALIZE_WHITESPACE
- (<InterfaceClass zope.component.tests.I1>,
- <InterfaceClass zope.component.tests.I2>)
- <InterfaceClass zope.component.tests.IA1>
- zope.component.tests.A12_1
- (<InterfaceClass zope.component.tests.I1>,
- <InterfaceClass zope.component.tests.I2>)
- <InterfaceClass zope.component.tests.IA2>
- zope.component.tests.A12_
- (<InterfaceClass zope.component.tests.I1>,)
- <InterfaceClass zope.component.tests.IA2>
- zope.component.tests.A1_12
- (<InterfaceClass zope.component.tests.I3>,)
- <InterfaceClass zope.component.tests.IA2>
- zope.component.tests.A_2
- (<implementedBy zope.component.tests.U>,)
- <InterfaceClass zope.component.tests.IA3>
- zope.component.tests.A_3 Really class specific
-
-As with utilities, we can provide registration information when
-registering adapters.
-
-If you try to fetch an adapter that isn't registered, you'll get a
-component-lookup error:
-
- >>> components.getMultiAdapter((tests.U(8), ), tests.IA1)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- ComponentLookupError: ((U(8),),
- <InterfaceClass zope.component.tests.IA1>, u'')
-
-unless you use queryAdapter:
-
- >>> components.queryMultiAdapter((tests.U(8), ), tests.IA1)
- >>> components.queryMultiAdapter((tests.U(8), ), tests.IA1, default=42)
- 42
-
-When looking up an adapter for a single object, you can use the
-slightly simpler getAdapter and queryAdapter calls:
-
- >>> components.getAdapter(tests.U1(9), tests.IA2)
- A1_12(U1(9))
-
- >>> components.queryAdapter(tests.U1(9), tests.IA2)
- A1_12(U1(9))
-
- >>> components.getAdapter(tests.U(8), tests.IA1)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- ComponentLookupError: (U(8),
- <InterfaceClass zope.component.tests.IA1>, u'')
-
- >>> components.queryAdapter(tests.U(8), tests.IA2)
- >>> components.queryAdapter(tests.U(8), tests.IA2, default=42)
- 42
-
-You can unregister an adapter. If a factory is provided and if the
-rewuired and provided interfaces, can be infered, then they need not
-be provided:
-
- >>> components.unregisterAdapter(tests.A12_1)
- Unregistered event:
- AdapterRegistration(<Components comps>, [I1, I2], IA1, u'', A12_1, u'')
- True
-
- >>> for registration in sorted(components.registeredAdapters()):
- ... print registration.required
- ... print registration.provided, registration.name
- ... print registration.factory, registration.info
- ... # doctest: +NORMALIZE_WHITESPACE
- (<InterfaceClass zope.component.tests.I1>,
- <InterfaceClass zope.component.tests.I2>)
- <InterfaceClass zope.component.tests.IA2>
- zope.component.tests.A12_
- (<InterfaceClass zope.component.tests.I1>,)
- <InterfaceClass zope.component.tests.IA2>
- zope.component.tests.A1_12
- (<InterfaceClass zope.component.tests.I3>,)
- <InterfaceClass zope.component.tests.IA2>
- zope.component.tests.A_2
- (<implementedBy zope.component.tests.U>,)
- <InterfaceClass zope.component.tests.IA3>
- zope.component.tests.A_3 Really class specific
-
-A boolean is returned indicating whether a change was made.
-
-If a factory implements more than one interface, an exception will be
-raised:
-
- >>> components.unregisterAdapter(tests.A1_12)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The adapter factory doesn't implement a single
- interface and no provided interface was specified.
-
-Unless the provided interface is specified:
-
- >>> components.unregisterAdapter(tests.A1_12, provided=tests.IA2)
- Unregistered event:
- AdapterRegistration(<Components comps>, [I1], IA2, u'', A1_12, u'')
- True
-
-If a factory doesn't declare an implemented interface, an exception will be
-raised:
-
- >>> components.unregisterAdapter(tests.A12_)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The adapter factory doesn't implement a single
- interface and no provided interface was specified.
-
-Unless the provided interface is specified:
-
- >>> components.unregisterAdapter(tests.A12_, provided=tests.IA2)
- Unregistered event:
- AdapterRegistration(<Components comps>, [I1, I2], IA2, u'', A12_, u'')
- True
-
-The required interface needs to be specified if the factory doesn't
-have a __component_adapts__ attribute:
-
- >>> components.unregisterAdapter(tests.A_2)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The adapter factory doesn't have a __component_adapts__
- attribute and no required specifications were specified
-
- >>> components.unregisterAdapter(tests.A_2, required=[tests.I3])
- Unregistered event:
- AdapterRegistration(<Components comps>, [I3], IA2, u'', A_2, u'')
- True
-
- >>> for registration in sorted(components.registeredAdapters()):
- ... print registration.required
- ... print registration.provided, registration.name
- ... print registration.factory, registration.info
- ... # doctest: +NORMALIZE_WHITESPACE
- (<implementedBy zope.component.tests.U>,)
- <InterfaceClass zope.component.tests.IA3>
- zope.component.tests.A_3 Really class specific
-
-If a factory is unregistered that is not registered, False is
-returned:
-
-
- >>> components.unregisterAdapter(tests.A_2, required=[tests.I3])
- False
- >>> components.unregisterAdapter(tests.A12_1, required=[tests.U])
- False
-
-The factory can be omitted, to unregister *any* factory that matches
-specified required and provided interfaces:
-
- >>> components.unregisterAdapter(required=[tests.U], provided=tests.IA3)
- ... # doctest: +NORMALIZE_WHITESPACE
- Unregistered event:
- AdapterRegistration(<Components comps>, [zope.component.tests.U],
- IA3, u'', A_3, 'Really class specific')
- True
-
- >>> for registration in sorted(components.registeredAdapters()):
- ... print registration
-
-Adapters can be named:
-
- >>> components.registerAdapter(tests.A1_12, provided=tests.IA2,
- ... name=u'test')
- Registered event:
- AdapterRegistration(<Components comps>, [I1], IA2, u'test', A1_12, u'')
-
- >>> components.queryMultiAdapter((tests.U1(9), ), tests.IA2)
- >>> components.queryMultiAdapter((tests.U1(9), ), tests.IA2, name=u'test')
- A1_12(U1(9))
-
- >>> components.queryAdapter(tests.U1(9), tests.IA2)
- >>> components.queryAdapter(tests.U1(9), tests.IA2, name=u'test')
- A1_12(U1(9))
- >>> components.getAdapter(tests.U1(9), tests.IA2, name=u'test')
- A1_12(U1(9))
-
-It is possible to look up all of the adapters that provide an
-interface:
-
- >>> components.registerAdapter(tests.A1_23, provided=tests.IA2,
- ... name=u'test 2')
- Registered event:
- AdapterRegistration(<Components comps>, [I1], IA2, u'test 2', A1_23, u'')
-
- >>> components.registerAdapter(tests.A1_12, provided=tests.IA2)
- Registered event:
- AdapterRegistration(<Components comps>, [I1], IA2, u'', A1_12, u'')
-
- >>> for name, adapter in sorted(components.getAdapters((tests.U1(9), ),
- ... tests.IA2)):
- ... print name, adapter
- A1_12(U1(9))
- test A1_12(U1(9))
- test 2 A1_23(U1(9))
-
-
-getAdapters is most commonly used as the basis of menu systems.
-
-If an adapter factory returns None, it is equivalent to there being no
-factory:
-
- >>> components.registerAdapter(tests.noop,
- ... required=[tests.IA1], provided=tests.IA2,
- ... name=u'test noop')
- ... # doctest: +NORMALIZE_WHITESPACE
- Registered event:
- AdapterRegistration(<Components comps>, [IA1], IA2, u'test noop',
- noop, u'')
- >>> components.queryAdapter(tests.U1(9), tests.IA2, name=u'test noop')
-
- >>> components.registerAdapter(tests.A1_12, provided=tests.IA2)
- Registered event:
- AdapterRegistration(<Components comps>, [I1], IA2, u'', A1_12, u'')
-
- >>> for name, adapter in sorted(components.getAdapters((tests.U1(9), ),
- ... tests.IA2)):
- ... print name, adapter
- A1_12(U1(9))
- test A1_12(U1(9))
- test 2 A1_23(U1(9))
-
-
- >>> components.unregisterAdapter(tests.A1_12, provided=tests.IA2,
- ... name=u'test')
- Unregistered event:
- AdapterRegistration(<Components comps>, [I1], IA2, u'test', A1_12, u'')
- True
- >>> components.unregisterAdapter(tests.A1_12, provided=tests.IA2)
- Unregistered event:
- AdapterRegistration(<Components comps>, [I1], IA2, u'', A1_12, u'')
- True
- >>> for registration in sorted(components.registeredAdapters()):
- ... print registration.required
- ... print registration.provided, registration.name
- ... print registration.factory, registration.info
- ... # doctest: +NORMALIZE_WHITESPACE
- (<InterfaceClass zope.component.tests.I1>,)
- <InterfaceClass zope.component.tests.IA2> test 2
- zope.component.tests.A1_23
- (<InterfaceClass zope.component.tests.IA1>,)
- <InterfaceClass zope.component.tests.IA2> test noop
- <function noop at 0xb79a1064>
-
-
-Subscribers
------------
-
-Subscribers provide a way to get multiple adapters of a given type.
-In this regard, subscribers are like named adapters, except that there
-isn't any concept of the most specific adapter for a given name.
-
-Subscribers are registered by calling registerSubscriptionAdapter:
-
- >>> components.registerSubscriptionAdapter(tests.A1_2)
- ... # doctest: +NORMALIZE_WHITESPACE
- Registered event:
- SubscriptionRegistration(<Components comps>, [I1], IA2, u'', A1_2, u'')
-
- >>> components.registerSubscriptionAdapter(
- ... tests.A1_12, provided=tests.IA2)
- ... # doctest: +NORMALIZE_WHITESPACE
- Registered event:
- SubscriptionRegistration(<Components comps>, [I1], IA2, u'', A1_12, u'')
-
- >>> components.registerSubscriptionAdapter(
- ... tests.A, [tests.I1], tests.IA2,
- ... info='a sample comment')
- ... # doctest: +NORMALIZE_WHITESPACE
- Registered event:
- SubscriptionRegistration(<Components comps>, [I1], IA2, u'',
- A, 'a sample comment')
-
-The same rules, with regard to when required and provided interfaces
-have to be specified apply as with adapters:
-
- >>> components.registerSubscriptionAdapter(tests.A1_12)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The adapter factory doesn't implement a single
- interface and no provided interface was specified.
-
- >>> components.registerSubscriptionAdapter(tests.A)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The adapter factory doesn't implement a single interface and
- no provided interface was specified.
-
- >>> components.registerSubscriptionAdapter(tests.A, required=[tests.IA1])
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The adapter factory doesn't implement a single interface
- and no provided interface was specified.
-
-Note that we provided the info argument as a keyword argument above.
-That's because there is a name argument that's reserved for future
-use. We can give a name, as long as it is an empty string:
-
- >>> components.registerSubscriptionAdapter(
- ... tests.A, [tests.I1], tests.IA2, u'', 'a sample comment')
- ... # doctest: +NORMALIZE_WHITESPACE
- Registered event:
- SubscriptionRegistration(<Components comps>, [I1], IA2, u'',
- A, 'a sample comment')
-
- >>> components.registerSubscriptionAdapter(
- ... tests.A, [tests.I1], tests.IA2, u'oops', 'a sample comment')
- Traceback (most recent call last):
- ...
- TypeError: Named subscribers are not yet supported
-
-Subscribers are looked up using the subscribers method:
-
- >>> for s in components.subscribers((tests.U1(1), ), tests.IA2):
- ... print s
- A1_2(U1(1))
- A1_12(U1(1))
- A(U1(1),)
- A(U1(1),)
-
-Note that, because we created multiple subscriptions for A, we got multiple
-subscriber instances.
-
-As with normal adapters, if a factory returns None, the result is skipped:
-
- >>> components.registerSubscriptionAdapter(
- ... tests.noop, [tests.I1], tests.IA2)
- Registered event:
- SubscriptionRegistration(<Components comps>, [I1], IA2, u'', noop, u'')
-
- >>> for s in components.subscribers((tests.U1(1), ), tests.IA2):
- ... print s
- A1_2(U1(1))
- A1_12(U1(1))
- A(U1(1),)
- A(U1(1),)
-
-We can get registration information for subscriptions:
-
- >>> for registration in sorted(
- ... components.registeredSubscriptionAdapters()):
- ... print registration.required
- ... print registration.provided, registration.name
- ... print registration.factory, registration.info
- (<InterfaceClass zope.component.tests.I1>,)
- <InterfaceClass zope.component.tests.IA2>
- zope.component.tests.A a sample comment
- (<InterfaceClass zope.component.tests.I1>,)
- <InterfaceClass zope.component.tests.IA2>
- zope.component.tests.A a sample comment
- (<InterfaceClass zope.component.tests.I1>,)
- <InterfaceClass zope.component.tests.IA2>
- zope.component.tests.A1_12
- (<InterfaceClass zope.component.tests.I1>,)
- <InterfaceClass zope.component.tests.IA2>
- zope.component.tests.A1_2
- (<InterfaceClass zope.component.tests.I1>,)
- <InterfaceClass zope.component.tests.IA2>
- <function noop at 0xb796ff7c>
-
-We can also unregister subscriptions in much the same way we can for adapters:
-
- >>> components.unregisterSubscriptionAdapter(tests.A1_2)
- ... # doctest: +NORMALIZE_WHITESPACE
- Unregistered event:
- SubscriptionRegistration(<Components comps>, [I1], IA2, u'', A1_2, '')
- True
-
- >>> for s in components.subscribers((tests.U1(1), ), tests.IA2):
- ... print s
- A1_12(U1(1))
- A(U1(1),)
- A(U1(1),)
-
- >>> for registration in sorted(
- ... components.registeredSubscriptionAdapters()):
- ... print registration.required
- ... print registration.provided, registration.name
- ... print registration.factory, registration.info
- (<InterfaceClass zope.component.tests.I1>,)
- <InterfaceClass zope.component.tests.IA2>
- zope.component.tests.A a sample comment
- (<InterfaceClass zope.component.tests.I1>,)
- <InterfaceClass zope.component.tests.IA2>
- zope.component.tests.A a sample comment
- (<InterfaceClass zope.component.tests.I1>,)
- <InterfaceClass zope.component.tests.IA2>
- zope.component.tests.A1_12
- (<InterfaceClass zope.component.tests.I1>,)
- <InterfaceClass zope.component.tests.IA2>
- <function noop at 0xb796ff7c>
-
- >>> components.unregisterSubscriptionAdapter(
- ... tests.A, [tests.I1], tests.IA2)
- Unregistered event:
- SubscriptionRegistration(<Components comps>, [I1], IA2, u'', A, '')
- True
-
- >>> for s in components.subscribers((tests.U1(1), ), tests.IA2):
- ... print s
- A1_12(U1(1))
-
- >>> for registration in sorted(
- ... components.registeredSubscriptionAdapters()):
- ... print registration.required
- ... print registration.provided, registration.name
- ... print registration.factory, registration.info
- (<InterfaceClass zope.component.tests.I1>,)
- <InterfaceClass zope.component.tests.IA2>
- zope.component.tests.A1_12
- (<InterfaceClass zope.component.tests.I1>,)
- <InterfaceClass zope.component.tests.IA2>
- <function noop at 0xb796ff7c>
-
-Note here that both registrations for A were removed.
-
-If we omit the factory, we must specify the required and provided interfaces:
-
- >>> components.unregisterSubscriptionAdapter(required=[tests.I1])
- Traceback (most recent call last):
- ...
- TypeError: Must specify one of factory and provided
-
- >>> components.unregisterSubscriptionAdapter(provided=tests.IA2)
- Traceback (most recent call last):
- ...
- TypeError: Must specify one of factory and required
-
- >>> components.unregisterSubscriptionAdapter(
- ... required=[tests.I1], provided=tests.IA2)
- Unregistered event:
- SubscriptionRegistration(<Components comps>, [I1], IA2, u'', None, '')
- True
-
- >>> for s in components.subscribers((tests.U1(1), ), tests.IA2):
- ... print s
-
- >>> for registration in sorted(
- ... components.registeredSubscriptionAdapters()):
- ... print registration.factory
-
-As when registering, an error is raised if the registration
-information can't be determined from the factory and isn't specified:
-
- >>> components.unregisterSubscriptionAdapter(tests.A1_12)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The adapter factory doesn't implement a single
- interface and no provided interface was specified.
-
- >>> components.unregisterSubscriptionAdapter(tests.A)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The adapter factory doesn't implement a single interface and
- no provided interface was specified.
-
- >>> components.unregisterSubscriptionAdapter(tests.A, required=[tests.IA1])
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The adapter factory doesn't implement a single interface
- and no provided interface was specified.
-
-If you unregister something that's not registered, nothing will be
-changed and False will be returned:
-
-
- >>> components.unregisterSubscriptionAdapter(
- ... required=[tests.I1], provided=tests.IA2)
- False
-
-Handlers
---------
-
-Handlers are used when you want to perform some function in response
-to an event. Handlers aren't expected to return anything when called
-and are not registered to provide any interface.
-
- >>> from zope import component
- >>> @component.adapter(tests.I1)
- ... def handle1(x):
- ... print 'handle1', x
-
- >>> components.registerHandler(handle1, info="First handler")
- ... # doctest: +NORMALIZE_WHITESPACE
- Registered event:
- HandlerRegistration(<Components comps>, [I1], u'',
- handle1, 'First handler')
- >>> components.handle(tests.U1(1))
- handle1 U1(1)
-
- >>> @component.adapter(tests.I1, tests.I2)
- ... def handle12(x, y):
- ... print 'handle12', x, y
-
- >>> components.registerHandler(handle12)
- Registered event:
- HandlerRegistration(<Components comps>, [I1, I2], u'', handle12, u'')
- >>> components.handle(tests.U1(1), tests.U12(2))
- handle12 U1(1) U12(2)
-
-If a handler doesn't document interfaces it handles, then
-the required interfaces must be specified:
-
- >>> def handle(*objects):
- ... print 'handle', objects
-
- >>> components.registerHandler(handle)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The adapter factory doesn't have a __component_adapts__
- attribute and no required specifications were specified
-
- >>> components.registerHandler(handle, required=[tests.I1],
- ... info="a comment")
- Registered event:
- HandlerRegistration(<Components comps>, [I1], u'', handle, 'a comment')
-
-Handlers can also be registered for classes:
-
- >>> components.registerHandler(handle, required=[tests.U],
- ... info="handle a class")
- ... # doctest: +NORMALIZE_WHITESPACE
- Registered event:
- HandlerRegistration(<Components comps>, [zope.component.tests.U], u'',
- handle, 'handle a class')
-
-
- >>> components.handle(tests.U1(1))
- handle (U1(1),)
- handle1 U1(1)
- handle (U1(1),)
-
-We can list the handler registrations:
-
- >>> for registration in components.registeredHandlers():
- ... print registration.required
- ... print registration.handler, registration.info
- ... # doctest: +NORMALIZE_WHITESPACE
- (<InterfaceClass zope.component.tests.I1>,)
- <function handle1 at 0xb78f5bfc> First handler
- (<InterfaceClass zope.component.tests.I1>,
- <InterfaceClass zope.component.tests.I2>)
- <function handle12 at 0xb78f5c34>
- (<InterfaceClass zope.component.tests.I1>,)
- <function handle at 0xb78f5ca4> a comment
- (<implementedBy zope.component.tests.U>,)
- <function handle at 0xb78f5ca4> handle a class
-
-and we can unregister handlers:
-
- >>> components.unregisterHandler(required=[tests.U])
- ... # doctest: +NORMALIZE_WHITESPACE
- Unregistered event:
- HandlerRegistration(<Components comps>, [zope.component.tests.U], u'',
- None, '')
- True
-
- >>> for registration in components.registeredHandlers():
- ... print registration.required
- ... print registration.handler, registration.info
- ... # doctest: +NORMALIZE_WHITESPACE
- (<InterfaceClass zope.component.tests.I1>,)
- <function handle1 at 0xb78f5bfc> First handler
- (<InterfaceClass zope.component.tests.I1>,
- <InterfaceClass zope.component.tests.I2>)
- <function handle12 at 0xb78f5c34>
- (<InterfaceClass zope.component.tests.I1>,)
- <function handle at 0xb78f5ca4> a comment
-
- >>> components.unregisterHandler(handle12)
- Unregistered event:
- HandlerRegistration(<Components comps>, [I1, I2], u'', handle12, '')
- True
-
- >>> for registration in components.registeredHandlers():
- ... print registration.required
- ... print registration.handler, registration.info
- (<InterfaceClass zope.component.tests.I1>,)
- <function handle1 at 0xb78f5bfc> First handler
- (<InterfaceClass zope.component.tests.I1>,)
- <function handle at 0xb78f5ca4> a comment
-
- >>> components.unregisterHandler(handle12)
- False
-
- >>> components.unregisterHandler()
- Traceback (most recent call last):
- ...
- TypeError: Must specify one of factory and required
-
- >>> components.registerHandler(handle)
- ... # doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- TypeError: The adapter factory doesn't have a __component_adapts__
- attribute and no required specifications were specified
-
-Extending
----------
-
-Component-management objects can extend other component-management
-objects.
-
- >>> c1 = registry.Components('1')
- >>> c1.__bases__
- ()
-
- >>> c2 = registry.Components('2', (c1, ))
- >>> c2.__bases__ == (c1, )
- True
-
- >>> c1.registerUtility(tests.U1(1))
- Registered event:
- UtilityRegistration(<Components 1>, I1, u'', 1, None, u'')
-
- >>> c1.queryUtility(tests.I1)
- U1(1)
- >>> c2.queryUtility(tests.I1)
- U1(1)
- >>> c1.registerUtility(tests.U1(2))
- Unregistered event:
- UtilityRegistration(<Components 1>, I1, u'', 1, None, u'')
- Registered event:
- UtilityRegistration(<Components 1>, I1, u'', 2, None, u'')
-
- >>> c2.queryUtility(tests.I1)
- U1(2)
-
-We can use multiple inheritence:
-
- >>> c3 = registry.Components('3', (c1, ))
- >>> c4 = registry.Components('4', (c2, c3))
- >>> c4.queryUtility(tests.I1)
- U1(2)
-
- >>> c1.registerUtility(tests.U12(1), tests.I2)
- Registered event:
- UtilityRegistration(<Components 1>, I2, u'', 1, None, u'')
-
- >>> c4.queryUtility(tests.I2)
- U12(1)
-
- >>> c3.registerUtility(tests.U12(3), tests.I2)
- Registered event:
- UtilityRegistration(<Components 3>, I2, u'', 3, None, u'')
- >>> c4.queryUtility(tests.I2)
- U12(3)
-
- >>> c1.registerHandler(handle1, info="First handler")
- Registered event:
- HandlerRegistration(<Components 1>, [I1], u'', handle1, 'First handler')
-
- >>> c2.registerHandler(handle, required=[tests.U])
- ... # doctest: +NORMALIZE_WHITESPACE
- Registered event:
- HandlerRegistration(<Components 2>, [zope.component.tests.U], u'',
- handle, u'')
-
- >>> @component.adapter(tests.I1)
- ... def handle3(x):
- ... print 'handle3', x
- >>> c3.registerHandler(handle3)
- Registered event:
- HandlerRegistration(<Components 3>, [I1], u'', handle3, u'')
-
- >>> @component.adapter(tests.I1)
- ... def handle4(x):
- ... print 'handle4', x
- >>> c4.registerHandler(handle4)
- Registered event:
- HandlerRegistration(<Components 4>, [I1], u'', handle4, u'')
-
- >>> c4.handle(tests.U1(1))
- handle1 U1(1)
- handle3 U1(1)
- handle (U1(1),)
- handle4 U1(1)
-
-Redispatch of registration events
----------------------------------
-
-Some handlers are available that, if registered, redispatch
-registration events to the objects being registered. They depend on
-being dispatched to by the object-event dispatcher:
-
- >>> from zope import component
- >>> import zope.component.event
- >>> zope.component.getGlobalSiteManager().registerHandler(
- ... zope.component.event.objectEventNotify)
- ... # doctest: +NORMALIZE_WHITESPACE
- Registered event:
- HandlerRegistration(<BaseGlobalComponents base>,
- [IObjectEvent], u'', objectEventNotify, u'')
-
-To see this, we'll first register a multi-handler to show is when
-handlers are called on 2 objects:
-
- >>> @zope.component.adapter(None, None)
- ... def double_handler(o1, o2):
- ... print 'Double dispatch:'
- ... print ' ', o1
- ... print ' ', o2
- >>> zope.component.getGlobalSiteManager().registerHandler(double_handler)
- ... # doctest: +NORMALIZE_WHITESPACE
- Double dispatch:
- HandlerRegistration(<BaseGlobalComponents base>,
- [Interface, Interface], u'', double_handler, u'')
- Registered event:
- HandlerRegistration(<BaseGlobalComponents base>,
- [Interface, Interface], u'', double_handler, u'')
- Registered event:
- HandlerRegistration(<BaseGlobalComponents base>,
- [Interface, Interface], u'', double_handler, u'')
-
-In the example above, the double_handler reported it's own registration. :)
-
-Now we'll register our handlers:
-
- >>> zope.component.getGlobalSiteManager().registerHandler(
- ... registry.dispatchUtilityRegistrationEvent)
- ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
- Double dispatch:
- ...
-
- >>> zope.component.getGlobalSiteManager().registerHandler(
- ... registry.dispatchAdapterRegistrationEvent)
- ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
- Double dispatch:
- ...
-
- >>> zope.component.getGlobalSiteManager().registerHandler(
- ... registry.dispatchSubscriptionAdapterRegistrationEvent)
- ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
- Double dispatch:
- ...
-
- >>> zope.component.getGlobalSiteManager().registerHandler(
- ... registry.dispatchHandlerRegistrationEvent)
- ... # doctest: +NORMALIZE_WHITESPACE
- Double dispatch:
- HandlerRegistration(<BaseGlobalComponents base>,
- [IHandlerRegistration, IRegistrationEvent], u'',
- dispatchHandlerRegistrationEvent, u'')
- Registered event:
- HandlerRegistration(<BaseGlobalComponents base>,
- [IHandlerRegistration, IRegistrationEvent], u'',
- dispatchHandlerRegistrationEvent, u'')
- Double dispatch:
- <function dispatchHandlerRegistrationEvent at 0xb799f72c>
- Registered event:
- HandlerRegistration(<BaseGlobalComponents base>,
- [IHandlerRegistration, IRegistrationEvent], u'',
- dispatchHandlerRegistrationEvent, u'')
- Registered event:
- HandlerRegistration(<BaseGlobalComponents base>,
- [IHandlerRegistration, IRegistrationEvent], u'',
- dispatchHandlerRegistrationEvent, u'')
-
-In the last example above, we can see that the registration of
-dispatchHandlerRegistrationEvent was handled by
-dispatchHandlerRegistrationEvent and redispatched. This can be seen
-in the second double-dispatch output, where the first argument is the
-object being registered, which is dispatchHandlerRegistrationEvent.
-
-If we change some other registrations, we can the double dispatch
-taking place:
-
- >>> components.registerUtility(u5)
- ... # doctest: +NORMALIZE_WHITESPACE
- Double dispatch:
- UtilityRegistration(<Components comps>, I1, u'', 5, None, u'')
- Registered event:
- UtilityRegistration(<Components comps>, I1, u'', 5, None, u'')
- Double dispatch:
- U1(5)
- Registered event:
- UtilityRegistration(<Components comps>, I1, u'', 5, None, u'')
- Registered event:
- UtilityRegistration(<Components comps>, I1, u'', 5, None, u'')
-
- >>> components.registerAdapter(tests.A12_1)
- ... # doctest: +NORMALIZE_WHITESPACE
- Double dispatch:
- AdapterRegistration(<Components comps>, [I1, I2], IA1, u'', A12_1, u'')
- Registered event:
- AdapterRegistration(<Components comps>, [I1, I2], IA1, u'', A12_1, u'')
- Double dispatch:
- zope.component.tests.A12_1
- Registered event:
- AdapterRegistration(<Components comps>, [I1, I2], IA1, u'', A12_1, u'')
- Registered event:
- AdapterRegistration(<Components comps>, [I1, I2], IA1, u'', A12_1, u'')
-
- >>> components.registerSubscriptionAdapter(tests.A1_2)
- ... # doctest: +NORMALIZE_WHITESPACE
- Double dispatch:
- SubscriptionRegistration(<Components comps>, [I1], IA2, u'', A1_2, u'')
- Registered event:
- SubscriptionRegistration(<Components comps>, [I1], IA2, u'', A1_2, u'')
- Double dispatch:
- zope.component.tests.A1_2
- Registered event:
- SubscriptionRegistration(<Components comps>, [I1], IA2, u'', A1_2, u'')
- Registered event:
- SubscriptionRegistration(<Components comps>, [I1], IA2, u'', A1_2, u'')
More information about the checkins
mailing list