[Checkins] SVN: zope.component/tseaver-test_cleanup/ Split out separate API sections.
Tres Seaver
cvs-admin at zope.org
Wed Jun 20 05:20:09 UTC 2012
Log message for revision 126977:
Split out separate API sections.
Changed:
_U zope.component/tseaver-test_cleanup/
A zope.component/tseaver-test_cleanup/docs/api/adapter.rst
A zope.component/tseaver-test_cleanup/docs/api/factory.rst
A zope.component/tseaver-test_cleanup/docs/api/interfaces.rst
A zope.component/tseaver-test_cleanup/docs/api/sitemanager.rst
A zope.component/tseaver-test_cleanup/docs/api/utility.rst
U zope.component/tseaver-test_cleanup/docs/api.rst
-=-
Added: zope.component/tseaver-test_cleanup/docs/api/adapter.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/api/adapter.rst (rev 0)
+++ zope.component/tseaver-test_cleanup/docs/api/adapter.rst 2012-06-20 05:20:05 UTC (rev 126977)
@@ -0,0 +1,406 @@
+Adapter Registration APIs
+=========================
+
+Conforming Adapter Lookup
+-------------------------
+
+.. testsetup::
+
+ from zope.component.testing import setUp
+ setUp()
+
+.. autofunction:: zope.component.getAdapterInContext
+
+.. autofunction:: zope.component.queryAdapterInContext
+
+The :func:`~zope.component.getAdapterInContext` and
+:func:`~zope.component.queryAdapterInContext` APIs first check the
+context object to see if it already conforms to the requested interface.
+If so, the object is returned immediately. Otherwise, the adapter factory
+is looked up in the site manager, and called.
+
+Let's start by creating a component that supports the `__conform__()` method:
+
+.. doctest::
+
+ >>> from zope.interface import implementer
+ >>> from zope.component.tests.test_doctests import I1
+ >>> from zope.component.tests.test_doctests import I2
+ >>> @implementer(I1)
+ ... class Component(object):
+ ... def __conform__(self, iface, default=None):
+ ... if iface == I2:
+ ... return 42
+ >>> ob = Component()
+
+We also gave the component a custom representation, so it will be easier
+to use in these tests.
+
+We now have to create a site manager (other than the default global one)
+with which we can register adapters for `I1`.
+
+.. doctest::
+
+ >>> from zope.component.globalregistry import BaseGlobalComponents
+ >>> sitemanager = BaseGlobalComponents()
+
+Now we create a new `context` that knows how to get to our custom site
+manager.
+
+.. doctest::
+
+ >>> from zope.component.tests.test_doctests \
+ ... import ConformsToIComponentLookup
+ >>> context = ConformsToIComponentLookup(sitemanager)
+
+If an object implements the interface you want to adapt to,
+`getAdapterInContext()` should simply return the object.
+
+.. doctest::
+
+ >>> from zope.component import getAdapterInContext
+ >>> from zope.component import queryAdapterInContext
+ >>> getAdapterInContext(ob, I1, context) is ob
+ True
+ >>> queryAdapterInContext(ob, I1, context) is ob
+ True
+
+If an object conforms to the interface you want to adapt to,
+`getAdapterInContext()` should simply return the conformed object.
+
+.. doctest::
+
+ >>> getAdapterInContext(ob, I2, context)
+ 42
+ >>> queryAdapterInContext(ob, I2, context)
+ 42
+
+If an adapter isn't registered for the given object and interface, and you
+provide no default, the `getAdapterInContext` API raises ComponentLookupError:
+
+.. doctest::
+
+ >>> from zope.interface import Interface
+ >>> class I4(Interface):
+ ... pass
+
+ >>> getAdapterInContext(ob, I4, context)
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError: (<Component implementing 'I1'>,
+ <InterfaceClass ...I4>)
+
+While the `queryAdapterInContext` API returns the default:
+
+.. doctest::
+
+ >>> queryAdapterInContext(ob, I4, context, 44)
+ 44
+
+If you ask for an adapter for which something's registered you get the
+registered adapter:
+
+.. doctest::
+
+ >>> from zope.component.tests.test_doctests import I3
+ >>> sitemanager.registerAdapter(lambda x: 43, (I1,), I3, '')
+ >>> getAdapterInContext(ob, I3, context)
+ 43
+ >>> queryAdapterInContext(ob, I3, context)
+ 43
+
+Named Adapter Lookup
+--------------------
+
+.. autofunction:: zope.component.getAdapter
+
+.. autofunction:: zope.component.queryAdapter
+
+The ``getAdapter`` and ``queryAdapter`` API functions are similar to
+``{get|query}AdapterInContext()`` functions, except that they do not care
+about the ``__conform__()`` but also handle named adapters. (Actually, the
+name is a required argument.)
+
+If no adapter is registered for the given object, interface, and name,
+``getAdapter`` raises ``ComponentLookupError``, while ``queryAdapter``
+returns the default:
+
+.. doctest::
+
+ >>> from zope.component import getAdapter
+ >>> from zope.component import queryAdapter
+ >>> from zope.component.tests.test_doctests import I2
+ >>> from zope.component.tests.test_doctests import ob
+ >>> getAdapter(ob, I2, '')
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError: (<instance Ob>,
+ <InterfaceClass zope.component.tests.test_doctests.I2>,
+ '')
+ >>> queryAdapter(ob, I2, '', '<default>')
+ '<default>'
+
+The 'requires' argument to `registerAdapter` must be a sequence, rather than
+a single interface:
+
+.. doctest::
+
+ >>> from zope.component import getGlobalSiteManager
+ >>> from zope.component.tests.test_doctests import Comp
+ >>> gsm = getGlobalSiteManager()
+ >>> gsm.registerAdapter(Comp, I1, I2, '')
+ Traceback (most recent call last):
+ ...
+ TypeError: the required argument should be a list of interfaces, not a single interface
+
+After register an adapter from `I1` to `I2` with the global site manager:
+
+.. doctest::
+
+ >>> from zope.component import getGlobalSiteManager
+ >>> from zope.component.tests.test_doctests import Comp
+ >>> gsm = getGlobalSiteManager()
+ >>> gsm.registerAdapter(Comp, (I1,), I2, '')
+
+We can access the adapter using the `getAdapter()` API:
+
+.. doctest::
+
+ >>> adapted = getAdapter(ob, I2, '')
+ >>> adapted.__class__ is Comp
+ True
+ >>> adapted.context is ob
+ True
+ >>> adapted = queryAdapter(ob, I2, '')
+ >>> adapted.__class__ is Comp
+ True
+ >>> adapted.context is ob
+ True
+
+If we search using a non-anonymous name, before registering:
+
+.. doctest::
+
+ >>> getAdapter(ob, I2, 'named')
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError: (<instance Ob>,
+ <InterfaceClass ....I2>,
+ 'named')
+ >>> queryAdapter(ob, I2, 'named', '<default>')
+ '<default>'
+
+After registering under that name:
+
+.. doctest::
+
+ >>> gsm.registerAdapter(Comp, (I1,), I2, 'named')
+ >>> adapted = getAdapter(ob, I2, 'named')
+ >>> adapted.__class__ is Comp
+ True
+ >>> adapted.context is ob
+ True
+ >>> adapted = queryAdapter(ob, I2, 'named')
+ >>> adapted.__class__ is Comp
+ True
+ >>> adapted.context is ob
+ True
+
+Invoking an Interface to Perform Adapter Lookup
+-----------------------------------------------
+
+:mod:`zope.component` registers an adapter hook with
+:mod:`zope.interface.interface`, allowing a convenient spelling for
+adapter lookup: just "call" the interface, passing the context:
+
+.. doctest::
+
+ >>> adapted = I2(ob)
+ >>> adapted.__class__ is Comp
+ True
+ >>> adapted.context is ob
+ True
+
+If the lookup fails, we get a `TypeError`:
+
+.. doctest::
+
+ >>> I2(object())
+ Traceback (most recent call last):
+ ...
+ TypeError: ('Could not adapt'...
+
+unless we pass a default:
+
+.. doctest::
+
+ >>> marker = object()
+ >>> adapted = I2(object(), marker)
+ >>> adapted is marker
+ True
+
+Registering Adapters For Arbitrary Objects
+------------------------------------------
+
+Providing an adapter for None says that your adapter can adapt anything
+to `I2`.
+
+.. doctest::
+
+ >>> gsm.registerAdapter(Comp, (None,), I2, '')
+ >>> adapter = I2(ob)
+ >>> adapter.__class__ is Comp
+ True
+ >>> adapter.context is ob
+ True
+
+It can really adapt any arbitrary object:
+
+.. doctest::
+
+ >>> something = object()
+ >>> adapter = I2(something)
+ >>> adapter.__class__ is Comp
+ True
+ >>> adapter.context is something
+ True
+
+Looking Up Adapters Using Multiple Objects
+------------------------------------------
+
+.. autofunction:: zope.component.getMultiAdapter
+
+.. autofunction:: zope.component.queryMultiAdapter
+
+Multi-adapters adapt one or more objects to another interface. To make
+this demonstration non-trivial, we need to create a second object to be
+adapted:
+
+.. doctest::
+
+ >>> from zope.component.tests.test_doctests import Ob2
+ >>> ob2 = Ob2()
+
+As with regular adapters, if an adapter isn't registered for the given
+objects and interface, the :func:`~zope.component.getMultiAdapter` API
+raises `ComponentLookupError`:
+
+.. doctest::
+
+ >>> from zope.component import getMultiAdapter
+ >>> getMultiAdapter((ob, ob2), I3)
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError:
+ ((<instance Ob>, <instance Ob2>),
+ <InterfaceClass zope.component.tests.test_doctests.I3>,
+ u'')
+
+while the :func:`~zope.component.queryMultiAdapter` API returns the default:
+
+.. doctest::
+
+ >>> from zope.component import queryMultiAdapter
+ >>> queryMultiAdapter((ob, ob2), I3, default='<default>')
+ '<default>'
+
+Note that ``name`` is not a required attribute here.
+
+To test multi-adapters, we also have to create an adapter class that
+handles to context objects:
+
+.. doctest::
+
+ >>> from zope.interface import implementer
+ >>> @implementer(I3)
+ ... class DoubleAdapter(object):
+ ... def __init__(self, first, second):
+ ... self.first = first
+ ... self.second = second
+
+Now we can register the multi-adapter:
+
+.. doctest::
+
+ >>> from zope.component import getGlobalSiteManager
+ >>> getGlobalSiteManager().registerAdapter(DoubleAdapter, (I1, I2), I3, '')
+
+Notice how the required interfaces are simply provided by a tuple.
+
+Now we can get the adapter:
+
+.. doctest::
+
+ >>> adapter = getMultiAdapter((ob, ob2), I3)
+ >>> adapter.__class__ is DoubleAdapter
+ True
+ >>> adapter.first is ob
+ True
+ >>> adapter.second is ob2
+ True
+
+
+Finding More Than One Adapter
+-----------------------------
+
+.. autofunction:: zope.component.getAdapters
+
+It is sometimes desireable to get a list of all adapters that are
+registered for a particular output interface, given a set of
+objects.
+
+Let's register some adapters first:
+
+.. doctest::
+
+ >>> class I5(I1):
+ ... pass
+ >>> gsm.registerAdapter(Comp, [I1], I5, '')
+ >>> gsm.registerAdapter(Comp, [None], I5, 'foo')
+
+Now we get all the adapters that are registered for ``ob`` that provide
+``I5``:
+
+.. doctest::
+
+ >>> from zope.component import getAdapters
+ >>> adapters = sorted(getAdapters((ob,), I5))
+ >>> [(name, adapter.__class__.__name__) for name, adapter in adapters]
+ [(u'', 'Comp'), (u'foo', 'Comp')]
+
+Note that the output doesn't include None values. If an adapter
+factory returns None, it is as if it wasn't present.
+
+.. doctest::
+
+ >>> gsm.registerAdapter(lambda context: None, [I1], I5, 'nah')
+ >>> adapters = sorted(getAdapters((ob,), I5))
+ >>> [(name, adapter.__class__.__name__) for name, adapter in adapters]
+ [(u'', 'Comp'), (u'foo', 'Comp')]
+
+
+Subscription Adapters
+---------------------
+
+.. autofunction:: zope.component.subscribers
+
+Event handlers
+--------------
+
+.. autofunction:: zope.component.handle
+
+Helpers for Declaring / Testing Adapters
+----------------------------------------
+
+.. autofunction:: zope.component.adapter
+
+.. autofunction:: zope.component.adaptedBy
+
+.. autofunction:: zope.component.adapts
+
+
+.. testcleanup::
+
+ from zope.component.testing import tearDown
+ tearDown()
+
Added: zope.component/tseaver-test_cleanup/docs/api/factory.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/api/factory.rst (rev 0)
+++ zope.component/tseaver-test_cleanup/docs/api/factory.rst 2012-06-20 05:20:05 UTC (rev 126977)
@@ -0,0 +1,9 @@
+Factory APIs
+============
+
+.. autofunction:: zope.component.createObject
+
+.. autofunction:: zope.component.getFactoryInterfaces
+
+.. autofunction:: zope.component.getFactoriesFor
+
Added: zope.component/tseaver-test_cleanup/docs/api/interfaces.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/api/interfaces.rst (rev 0)
+++ zope.component/tseaver-test_cleanup/docs/api/interfaces.rst 2012-06-20 05:20:05 UTC (rev 126977)
@@ -0,0 +1,31 @@
+Interface Definitions
+=====================
+
+.. automodule:: zope.component.interfaces
+
+ .. autointerface:: IComponentArchitecture
+ :members:
+ :member-order: bysource
+
+ .. autointerface:: IRegistry
+ :members:
+ :member-order: bysource
+
+ .. autointerface:: IComponentRegistrationConvenience
+ :members:
+ :member-order: bysource
+
+ .. autointerface:: IPossibleSite
+ :members:
+ :member-order: bysource
+
+ .. autointerface:: ISite
+ :members:
+ :member-order: bysource
+
+ .. autoexception:: Misused
+
+ .. autointerface:: IFactory
+ :members:
+ :member-order: bysource
+
Added: zope.component/tseaver-test_cleanup/docs/api/sitemanager.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/api/sitemanager.rst (rev 0)
+++ zope.component/tseaver-test_cleanup/docs/api/sitemanager.rst 2012-06-20 05:20:05 UTC (rev 126977)
@@ -0,0 +1,89 @@
+Site Manager APIs
+=================
+
+.. autofunction:: zope.component.getGlobalSiteManager
+
+ The API returns the module-scope global registry:
+
+ .. doctest::
+
+ >>> from zope.component.interfaces import IComponentLookup
+ >>> from zope.component.globalregistry import base
+ >>> from zope.component import getGlobalSiteManager
+ >>> gsm = getGlobalSiteManager()
+ >>> gsm is base
+ True
+
+ The registry implements the
+ :class:`~zope.component.interfaces.IComponentLookup` interface:
+
+ .. doctest::
+
+ >>> IComponentLookup.providedBy(gsm)
+ True
+
+ The same registry is returned each time we call the function:
+
+ .. doctest::
+
+ >>> getGlobalSiteManager() is gsm
+ True
+
+.. autofunction:: zope.component.getSiteManager(context=None)
+
+ We don't know anything about the default service manager, except that it
+ is an `IComponentLookup`.
+
+ .. doctest::
+
+ >>> from zope.component import getSiteManager
+ >>> from zope.component.interfaces import IComponentLookup
+ >>> IComponentLookup.providedBy(getSiteManager())
+ True
+
+ Calling `getSiteManager()` with no args is equivalent to calling it with a
+ context of `None`.
+
+ .. doctest::
+
+ >>> getSiteManager() is getSiteManager(None)
+ True
+
+ If the context passed to `getSiteManager()` is not `None`, it is
+ adapted to `IComponentLookup` and this adapter returned. So, we
+ create a context that can be adapted to `IComponentLookup` using
+ the `__conform__` API.
+
+ Let's create the simplest stub-implementation of a site manager possible:
+
+ .. doctest::
+
+ >>> sitemanager = object()
+
+ Now create a context that knows how to adapt to our newly created site
+ manager.
+
+ .. doctest::
+
+ >>> from zope.component.tests.test_doctests \
+ ... import ConformsToIComponentLookup
+ >>> context = ConformsToIComponentLookup(sitemanager)
+
+ Now make sure that the `getSiteManager()` API call returns the correct
+ site manager.
+
+ .. doctest::
+
+ >>> getSiteManager(context) is sitemanager
+ True
+
+ Using a context that is not adaptable to `IComponentLookup` should fail.
+
+ .. doctest::
+
+ >>> getSiteManager(sitemanager)
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError: ('Could not adapt', <instance Ob>,
+ <InterfaceClass zope...interfaces.IComponentLookup>)
+
Added: zope.component/tseaver-test_cleanup/docs/api/utility.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/api/utility.rst (rev 0)
+++ zope.component/tseaver-test_cleanup/docs/api/utility.rst 2012-06-20 05:20:05 UTC (rev 126977)
@@ -0,0 +1,291 @@
+Utility Registration APIs
+=========================
+
+.. autofunction:: zope.component.getUtility
+
+.. autofunction:: zope.component.queryUtility
+
+Utilities are components that simply provide an interface. They are
+instantiated at the time or before they are registered. Here we test the
+simple query interface.
+
+Before we register any utility, there is no utility available, of
+course. The pure instatiation of an object does not make it a utility. If
+you do not specify a default, you get a `ComponentLookupError`.
+
+.. testsetup::
+
+ from zope.component.testing import setUp
+ setUp()
+
+.. doctest::
+
+ >>> from zope.component import getUtility
+ >>> from zope.component import queryUtility
+ >>> from zope.component.tests.test_doctests import I1
+ >>> getUtility(I1) #doctest: +NORMALIZE_WHITESPACE
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError: \
+ (<InterfaceClass zope.component.tests.test_doctests.I1>, '')
+
+Otherwise, you get the default:
+
+.. doctest::
+
+ >>> queryUtility(I1, default='<default>')
+ '<default>'
+
+Now we declare `ob` to be the utility providing `I1`:
+
+.. doctest::
+
+ >>> ob = object()
+ >>> from zope.component import getGlobalSiteManager
+ >>> getGlobalSiteManager().registerUtility(ob, I1)
+
+Now the component is available:
+
+.. doctest::
+
+ >>> getUtility(I1) is ob
+ True
+ >>> queryUtility(I1) is ob
+ True
+
+
+
+Named Utilities
+---------------
+
+Registering a utility without a name does not mean that it is available
+when looking for the utility with a name:
+
+.. doctest::
+
+ >>> getUtility(I1, name='foo')
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError:
+ (<InterfaceClass zope.component.tests.test_doctests.I1>, 'foo')
+
+ >>> queryUtility(I1, name='foo', default='<default>')
+ '<default>'
+
+Registering the utility under the correct name makes it available:
+
+.. doctest::
+
+ >>> ob2 = object()
+ >>> getGlobalSiteManager().registerUtility(ob2, I1, name='foo')
+ >>> getUtility(I1, 'foo') is ob2
+ True
+ >>> queryUtility(I1, 'foo') is ob2
+ True
+
+Querying Multiple Utilities
+---------------------------
+
+.. autofunction:: zope.component.getUtilitiesFor
+
+.. autofunction:: zope.component.getAllUtilitiesRegisteredFor
+
+Sometimes it may be useful to query all utilities, both anonymous and named
+for a given interface. The :func:`~zope.component.getUtilitiesFor` API
+returns a sequence of ``(name, utility)`` tuples, where ``name`` is the
+empty string for the anonymous utility:
+
+.. doctest::
+
+ >>> from zope.component import getUtilitiesFor
+ >>> tuples = list(getUtilitiesFor(I1))
+ >>> len(tuples)
+ 2
+ >>> ('', ob) in tuples
+ True
+ >>> ('foo', ob2) in tuples
+ True
+
+The :func:`~zope.component.getAllUtilitiesRegisteredFor` API returns
+utilities that have been registered for a particular interface. Utilities
+providing a derived interface are also listed.
+
+.. doctest::
+
+ >>> from zope.interface import implementer
+ >>> from zope.component.tests.test_doctests import Comp
+ >>> from zope.component.tests.test_doctests import I2
+ >>> from zope.component.tests.test_doctests import Ob
+ >>> class I11(I1):
+ ... pass
+
+ >>> @implementer(I11)
+ ... class Ob11(Ob):
+ ... pass
+
+ >>> ob11 = Ob11()
+ >>> ob_bob = Ob()
+
+Now we register the new utilities:
+
+.. doctest::
+
+ >>> from zope.component import getGlobalSiteManager
+ >>> gsm = getGlobalSiteManager()
+ >>> gsm.registerUtility(ob, I1)
+ >>> gsm.registerUtility(ob11, I11)
+ >>> gsm.registerUtility(ob_bob, I1, name='bob')
+ >>> gsm.registerUtility(Comp(2), I2)
+
+We can now get all the utilities that provide interface `I1`:
+
+.. doctest::
+
+ >>> from zope.component import getAllUtilitiesRegisteredFor
+ >>> uts = list(getAllUtilitiesRegisteredFor(I1))
+ >>> len(uts)
+ 4
+ >>> ob in uts
+ True
+ >>> ob2 in uts
+ True
+ >>> ob_bob in uts
+ True
+ >>> ob11 in uts
+ True
+
+Note that `getAllUtilitiesRegisteredFor()` does not return the names of
+the utilities.
+
+
+Delegated Utility Lookup
+------------------------
+
+.. autofunction:: zope.component.getNextUtility
+
+.. autofunction:: zope.component.queryNextUtility
+
+It is common for a utility to delegate its answer to a utility
+providing the same interface in one of the component registry's
+bases. Let's first create a global utility:
+
+.. doctest::
+
+ >>> from zope.interface import Interface
+ >>> from zope.interface import implementer
+ >>> class IMyUtility(Interface):
+ ... pass
+
+ >>> from zope.component.tests.test_doctests \
+ ... import ConformsToIComponentLookup
+ >>> @implementer(IMyUtility)
+ ... class MyUtility(ConformsToIComponentLookup):
+ ... def __init__(self, id, sm):
+ ... self.id = id
+ ... self.sitemanager = sm
+ ... def __repr__(self):
+ ... return "%s('%s')" % (self.__class__.__name__, self.id)
+
+ >>> gutil = MyUtility('global', gsm)
+ >>> gsm.registerUtility(gutil, IMyUtility, 'myutil')
+
+Now, let's create two registries and set up the bases hierarchy:
+
+.. doctest::
+
+ >>> from zope.interface.registry import Components
+ >>> sm1 = Components('sm1', bases=(gsm, ))
+ >>> sm1_1 = Components('sm1_1', bases=(sm1, ))
+
+Now we create two utilities and insert them in our folder hierarchy:
+
+.. doctest::
+
+ >>> from zope.component.interfaces import IComponentLookup
+ >>> util1 = MyUtility('one', sm1)
+ >>> sm1.registerUtility(util1, IMyUtility, 'myutil')
+ >>> IComponentLookup(util1) is sm1
+ True
+
+ >>> util1_1 = MyUtility('one-one', sm1_1)
+ >>> sm1_1.registerUtility(util1_1, IMyUtility, 'myutil')
+ >>> IComponentLookup(util1_1) is sm1_1
+ True
+
+Now, if we ask `util1_1` for its next available utility we get the
+``one`` utility:
+
+.. doctest::
+
+ >>> from zope.component import getNextUtility
+ >>> getNextUtility(util1_1, IMyUtility, 'myutil')
+ MyUtility('one')
+
+Next we ask `util1` for its next utility and we should get the global version:
+
+.. doctest::
+
+ >>> getNextUtility(util1, IMyUtility, 'myutil')
+ MyUtility('global')
+
+However, if we ask the global utility for the next one, an error is raised
+
+.. doctest::
+
+ >>> getNextUtility(gutil, IMyUtility,
+ ... 'myutil') #doctest: +NORMALIZE_WHITESPACE
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError:
+ No more utilities for <InterfaceClass zope.component.tests.test_doctests.IMyUtility>,
+ 'myutil' have been found.
+
+You can also use `queryNextUtility` and specify a default:
+
+.. doctest::
+
+ >>> from zope.component import queryNextUtility
+ >>> queryNextUtility(gutil, IMyUtility, 'myutil', 'default')
+ 'default'
+
+Let's now ensure that the function also works with multiple registries. First
+we create another base registry:
+
+.. doctest::
+
+ >>> myregistry = Components()
+
+We now set up another utility into that registry:
+
+.. doctest::
+
+ >>> custom_util = MyUtility('my_custom_util', myregistry)
+ >>> myregistry.registerUtility(custom_util, IMyUtility, 'my_custom_util')
+
+We add it as a base to the local site manager:
+
+.. doctest::
+
+ >>> sm1.__bases__ = (myregistry,) + sm1.__bases__
+
+Both the ``myregistry`` and global utilities should be available:
+
+.. doctest::
+
+ >>> queryNextUtility(sm1, IMyUtility, 'my_custom_util')
+ MyUtility('my_custom_util')
+ >>> queryNextUtility(sm1, IMyUtility, 'myutil')
+ MyUtility('global')
+
+Note, if the context cannot be converted to a site manager, the default is
+retruned:
+
+.. doctest::
+
+ >>> queryNextUtility(object(), IMyUtility, 'myutil', 'default')
+ 'default'
+
+.. testcleanup::
+
+ from zope.component.testing import tearDown
+ tearDown()
Modified: zope.component/tseaver-test_cleanup/docs/api.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/api.rst 2012-06-19 13:51:28 UTC (rev 126976)
+++ zope.component/tseaver-test_cleanup/docs/api.rst 2012-06-20 05:20:05 UTC (rev 126977)
@@ -1,825 +1,12 @@
-:mod:`zope.component` API
-=========================
+:mod:`zope.component` API Reference
+===================================
-Site Manager APIs
------------------
+.. toctree::
+ :maxdepth: 2
-.. autofunction:: zope.component.getGlobalSiteManager
-
- The API returns the module-scope global registry:
-
- .. doctest::
-
- >>> from zope.component.interfaces import IComponentLookup
- >>> from zope.component.globalregistry import base
- >>> from zope.component import getGlobalSiteManager
- >>> gsm = getGlobalSiteManager()
- >>> gsm is base
- True
-
- The registry implements the
- :class:`~zope.component.interfaces.IComponentLookup` interface:
-
- .. doctest::
-
- >>> IComponentLookup.providedBy(gsm)
- True
-
- The same registry is returned each time we call the function:
-
- .. doctest::
-
- >>> getGlobalSiteManager() is gsm
- True
-
-.. autofunction:: zope.component.getSiteManager(context=None)
-
- We don't know anything about the default service manager, except that it
- is an `IComponentLookup`.
-
- .. doctest::
-
- >>> from zope.component import getSiteManager
- >>> from zope.component.interfaces import IComponentLookup
- >>> IComponentLookup.providedBy(getSiteManager())
- True
-
- Calling `getSiteManager()` with no args is equivalent to calling it with a
- context of `None`.
-
- .. doctest::
-
- >>> getSiteManager() is getSiteManager(None)
- True
-
- If the context passed to `getSiteManager()` is not `None`, it is
- adapted to `IComponentLookup` and this adapter returned. So, we
- create a context that can be adapted to `IComponentLookup` using
- the `__conform__` API.
-
- Let's create the simplest stub-implementation of a site manager possible:
-
- .. doctest::
-
- >>> sitemanager = object()
-
- Now create a context that knows how to adapt to our newly created site
- manager.
-
- .. doctest::
-
- >>> from zope.component.tests.test_doctests \
- ... import ConformsToIComponentLookup
- >>> context = ConformsToIComponentLookup(sitemanager)
-
- Now make sure that the `getSiteManager()` API call returns the correct
- site manager.
-
- .. doctest::
-
- >>> getSiteManager(context) is sitemanager
- True
-
- Using a context that is not adaptable to `IComponentLookup` should fail.
-
- .. doctest::
-
- >>> getSiteManager(sitemanager)
- Traceback (most recent call last):
- ...
- ComponentLookupError: ('Could not adapt', <instance Ob>,
- <InterfaceClass zope...interfaces.IComponentLookup>)
-
-
-Utility Registration APIs
--------------------------
-
-.. autofunction:: zope.component.getUtility
-
-.. autofunction:: zope.component.queryUtility
-
-Utilities are components that simply provide an interface. They are
-instantiated at the time or before they are registered. Here we test the
-simple query interface.
-
-Before we register any utility, there is no utility available, of
-course. The pure instatiation of an object does not make it a utility. If
-you do not specify a default, you get a `ComponentLookupError`.
-
-.. testsetup::
-
- from zope.component.testing import setUp
- setUp()
-
-.. doctest::
-
- >>> from zope.component import getUtility
- >>> from zope.component import queryUtility
- >>> from zope.component.tests.test_doctests import I1
- >>> getUtility(I1) #doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- ComponentLookupError: \
- (<InterfaceClass zope.component.tests.test_doctests.I1>, '')
-
-Otherwise, you get the default:
-
-.. doctest::
-
- >>> queryUtility(I1, default='<default>')
- '<default>'
-
-Now we declare `ob` to be the utility providing `I1`:
-
-.. doctest::
-
- >>> ob = object()
- >>> from zope.component import getGlobalSiteManager
- >>> getGlobalSiteManager().registerUtility(ob, I1)
-
-Now the component is available:
-
-.. doctest::
-
- >>> getUtility(I1) is ob
- True
- >>> queryUtility(I1) is ob
- True
-
-Named Utilities
-###############
-
-Registering a utility without a name does not mean that it is available
-when looking for the utility with a name:
-
-.. doctest::
-
- >>> getUtility(I1, name='foo')
- Traceback (most recent call last):
- ...
- ComponentLookupError:
- (<InterfaceClass zope.component.tests.test_doctests.I1>, 'foo')
-
- >>> queryUtility(I1, name='foo', default='<default>')
- '<default>'
-
-Registering the utility under the correct name makes it available:
-
-.. doctest::
-
- >>> ob2 = object()
- >>> getGlobalSiteManager().registerUtility(ob2, I1, name='foo')
- >>> getUtility(I1, 'foo') is ob2
- True
- >>> queryUtility(I1, 'foo') is ob2
- True
-
-Querying Multiple Utilities
-###########################
-
-.. autofunction:: zope.component.getUtilitiesFor
-
-.. autofunction:: zope.component.getAllUtilitiesRegisteredFor
-
-Sometimes it may be useful to query all utilities, both anonymous and named
-for a given interface. The :func:`~zope.component.getUtilitiesFor` API
-returns a sequence of ``(name, utility)`` tuples, where ``name`` is the
-empty string for the anonymous utility:
-
-.. doctest::
-
- >>> from zope.component import getUtilitiesFor
- >>> tuples = list(getUtilitiesFor(I1))
- >>> len(tuples)
- 2
- >>> ('', ob) in tuples
- True
- >>> ('foo', ob2) in tuples
- True
-
-The :func:`~zope.component.getAllUtilitiesRegisteredFor` API returns
-utilities that have been registered for a particular interface. Utilities
-providing a derived interface are also listed.
-
-.. doctest::
-
- >>> from zope.interface import implementer
- >>> from zope.component.tests.test_doctests import Comp
- >>> from zope.component.tests.test_doctests import I2
- >>> from zope.component.tests.test_doctests import Ob
- >>> class I11(I1):
- ... pass
-
- >>> @implementer(I11)
- ... class Ob11(Ob):
- ... pass
-
- >>> ob11 = Ob11()
- >>> ob_bob = Ob()
-
-Now we register the new utilities:
-
-.. doctest::
-
- >>> gsm.registerUtility(ob, I1)
- >>> gsm.registerUtility(ob11, I11)
- >>> gsm.registerUtility(ob_bob, I1, name='bob')
- >>> gsm.registerUtility(Comp(2), I2)
-
-We can now get all the utilities that provide interface `I1`:
-
-.. doctest::
-
- >>> from zope.component import getAllUtilitiesRegisteredFor
- >>> uts = list(getAllUtilitiesRegisteredFor(I1))
- >>> len(uts)
- 4
- >>> ob in uts
- True
- >>> ob2 in uts
- True
- >>> ob_bob in uts
- True
- >>> ob11 in uts
- True
-
-Note that `getAllUtilitiesRegisteredFor()` does not return the names of
-the utilities.
-
-
-Delegated Utility Lookup
-########################
-
-.. autofunction:: zope.component.getNextUtility
-
-.. autofunction:: zope.component.queryNextUtility
-
-It is common for a utility to delegate its answer to a utility
-providing the same interface in one of the component registry's
-bases. Let's first create a global utility:
-
-.. doctest::
-
- >>> from zope.interface import Interface
- >>> from zope.interface import implementer
- >>> class IMyUtility(Interface):
- ... pass
-
- >>> from zope.component.tests.test_doctests \
- ... import ConformsToIComponentLookup
- >>> @implementer(IMyUtility)
- ... class MyUtility(ConformsToIComponentLookup):
- ... def __init__(self, id, sm):
- ... self.id = id
- ... self.sitemanager = sm
- ... def __repr__(self):
- ... return "%s('%s')" % (self.__class__.__name__, self.id)
-
- >>> gutil = MyUtility('global', gsm)
- >>> gsm.registerUtility(gutil, IMyUtility, 'myutil')
-
-Now, let's create two registries and set up the bases hierarchy:
-
-.. doctest::
-
- >>> from zope.interface.registry import Components
- >>> sm1 = Components('sm1', bases=(gsm, ))
- >>> sm1_1 = Components('sm1_1', bases=(sm1, ))
-
-Now we create two utilities and insert them in our folder hierarchy:
-
-.. doctest::
-
- >>> util1 = MyUtility('one', sm1)
- >>> sm1.registerUtility(util1, IMyUtility, 'myutil')
- >>> IComponentLookup(util1) is sm1
- True
-
- >>> util1_1 = MyUtility('one-one', sm1_1)
- >>> sm1_1.registerUtility(util1_1, IMyUtility, 'myutil')
- >>> IComponentLookup(util1_1) is sm1_1
- True
-
-Now, if we ask `util1_1` for its next available utility we get the
-``one`` utility:
-
-.. doctest::
-
- >>> from zope.component import getNextUtility
- >>> getNextUtility(util1_1, IMyUtility, 'myutil')
- MyUtility('one')
-
-Next we ask `util1` for its next utility and we should get the global version:
-
-.. doctest::
-
- >>> getNextUtility(util1, IMyUtility, 'myutil')
- MyUtility('global')
-
-However, if we ask the global utility for the next one, an error is raised
-
-.. doctest::
-
- >>> getNextUtility(gutil, IMyUtility,
- ... 'myutil') #doctest: +NORMALIZE_WHITESPACE
- Traceback (most recent call last):
- ...
- ComponentLookupError:
- No more utilities for <InterfaceClass zope.component.tests.test_doctests.IMyUtility>,
- 'myutil' have been found.
-
-You can also use `queryNextUtility` and specify a default:
-
-.. doctest::
-
- >>> from zope.component import queryNextUtility
- >>> queryNextUtility(gutil, IMyUtility, 'myutil', 'default')
- 'default'
-
-Let's now ensure that the function also works with multiple registries. First
-we create another base registry:
-
-.. doctest::
-
- >>> myregistry = Components()
-
-We now set up another utility into that registry:
-
-.. doctest::
-
- >>> custom_util = MyUtility('my_custom_util', myregistry)
- >>> myregistry.registerUtility(custom_util, IMyUtility, 'my_custom_util')
-
-We add it as a base to the local site manager:
-
-.. doctest::
-
- >>> sm1.__bases__ = (myregistry,) + sm1.__bases__
-
-Both the ``myregistry`` and global utilities should be available:
-
-.. doctest::
-
- >>> queryNextUtility(sm1, IMyUtility, 'my_custom_util')
- MyUtility('my_custom_util')
- >>> queryNextUtility(sm1, IMyUtility, 'myutil')
- MyUtility('global')
-
-Note, if the context cannot be converted to a site manager, the default is
-retruned:
-
-.. doctest::
-
- >>> queryNextUtility(object(), IMyUtility, 'myutil', 'default')
- 'default'
-
-.. testcleanup::
-
- from zope.component.testing import tearDown
- tearDown()
-
-
-Adapter Registration APIs
--------------------------
-
-Conforming Adapter Lookup
-#########################
-
-.. testsetup::
-
- from zope.component.testing import setUp
- setUp()
-
-.. autofunction:: zope.component.getAdapterInContext
-
-.. autofunction:: zope.component.queryAdapterInContext
-
-The :func:`~zope.component.getAdapterInContext` and
-:func:`~zope.component.queryAdapterInContext` APIs first check the
-context object to see if it already conforms to the requested interface.
-If so, the object is returned immediately. Otherwise, the adapter factory
-is looked up in the site manager, and called.
-
-Let's start by creating a component that supports the `__conform__()` method:
-
-.. doctest::
-
- >>> from zope.interface import implementer
- >>> from zope.component.tests.test_doctests import I1
- >>> from zope.component.tests.test_doctests import I2
- >>> @implementer(I1)
- ... class Component(object):
- ... def __conform__(self, iface, default=None):
- ... if iface == I2:
- ... return 42
- >>> ob = Component()
-
-We also gave the component a custom representation, so it will be easier
-to use in these tests.
-
-We now have to create a site manager (other than the default global one)
-with which we can register adapters for `I1`.
-
-.. doctest::
-
- >>> from zope.component.globalregistry import BaseGlobalComponents
- >>> sitemanager = BaseGlobalComponents()
-
-Now we create a new `context` that knows how to get to our custom site
-manager.
-
-.. doctest::
-
- >>> from zope.component.tests.test_doctests \
- ... import ConformsToIComponentLookup
- >>> context = ConformsToIComponentLookup(sitemanager)
-
-If an object implements the interface you want to adapt to,
-`getAdapterInContext()` should simply return the object.
-
-.. doctest::
-
- >>> from zope.component import getAdapterInContext
- >>> from zope.component import queryAdapterInContext
- >>> getAdapterInContext(ob, I1, context) is ob
- True
- >>> queryAdapterInContext(ob, I1, context) is ob
- True
-
-If an object conforms to the interface you want to adapt to,
-`getAdapterInContext()` should simply return the conformed object.
-
-.. doctest::
-
- >>> getAdapterInContext(ob, I2, context)
- 42
- >>> queryAdapterInContext(ob, I2, context)
- 42
-
-If an adapter isn't registered for the given object and interface, and you
-provide no default, the `getAdapterInContext` API raises ComponentLookupError:
-
-.. doctest::
-
- >>> from zope.interface import Interface
- >>> class I4(Interface):
- ... pass
-
- >>> getAdapterInContext(ob, I4, context)
- Traceback (most recent call last):
- ...
- ComponentLookupError: (<Component implementing 'I1'>,
- <InterfaceClass ...I4>)
-
-While the `queryAdapterInContext` API returns the default:
-
-.. doctest::
-
- >>> queryAdapterInContext(ob, I4, context, 44)
- 44
-
-If you ask for an adapter for which something's registered you get the
-registered adapter:
-
-.. doctest::
-
- >>> from zope.component.tests.test_doctests import I3
- >>> sitemanager.registerAdapter(lambda x: 43, (I1,), I3, '')
- >>> getAdapterInContext(ob, I3, context)
- 43
- >>> queryAdapterInContext(ob, I3, context)
- 43
-
-Named Adapter Lookup
-####################
-
-.. autofunction:: zope.component.getAdapter
-
-.. autofunction:: zope.component.queryAdapter
-
-The ``getAdapter`` and ``queryAdapter`` API functions are similar to
-``{get|query}AdapterInContext()`` functions, except that they do not care
-about the ``__conform__()`` but also handle named adapters. (Actually, the
-name is a required argument.)
-
-If no adapter is registered for the given object, interface, and name,
-``getAdapter`` raises ``ComponentLookupError``, while ``queryAdapter``
-returns the default:
-
-.. doctest::
-
- >>> from zope.component import getAdapter
- >>> from zope.component import queryAdapter
- >>> from zope.component.tests.test_doctests import I2
- >>> from zope.component.tests.test_doctests import ob
- >>> getAdapter(ob, I2, '')
- Traceback (most recent call last):
- ...
- ComponentLookupError: (<instance Ob>,
- <InterfaceClass zope.component.tests.test_doctests.I2>,
- '')
- >>> queryAdapter(ob, I2, '', '<default>')
- '<default>'
-
-The 'requires' argument to `registerAdapter` must be a sequence, rather than
-a single interface:
-
-.. doctest::
-
- >>> gsm.registerAdapter(Comp, I1, I2, '')
- Traceback (most recent call last):
- ...
- TypeError: the required argument should be a list of interfaces, not a single interface
-
-After register an adapter from `I1` to `I2` with the global site manager:
-
-.. doctest::
-
- >>> from zope.component import getGlobalSiteManager
- >>> from zope.component.tests.test_doctests import Comp
- >>> gsm = getGlobalSiteManager()
- >>> gsm.registerAdapter(Comp, (I1,), I2, '')
-
-We can access the adapter using the `getAdapter()` API:
-
-.. doctest::
-
- >>> adapted = getAdapter(ob, I2, '')
- >>> adapted.__class__ is Comp
- True
- >>> adapted.context is ob
- True
- >>> adapted = queryAdapter(ob, I2, '')
- >>> adapted.__class__ is Comp
- True
- >>> adapted.context is ob
- True
-
-If we search using a non-anonymous name, before registering:
-
-.. doctest::
-
- >>> getAdapter(ob, I2, 'named')
- Traceback (most recent call last):
- ...
- ComponentLookupError: (<instance Ob>,
- <InterfaceClass ....I2>,
- 'named')
- >>> queryAdapter(ob, I2, 'named', '<default>')
- '<default>'
-
-After registering under that name:
-
-.. doctest::
-
- >>> gsm.registerAdapter(Comp, (I1,), I2, 'named')
- >>> adapted = getAdapter(ob, I2, 'named')
- >>> adapted.__class__ is Comp
- True
- >>> adapted.context is ob
- True
- >>> adapted = queryAdapter(ob, I2, 'named')
- >>> adapted.__class__ is Comp
- True
- >>> adapted.context is ob
- True
-
-Invoking an Interface to Perform Adapter Lookup
-###############################################
-
-:mod:`zope.component` registers an adapter hook with
-:mod:`zope.interface.interface`, allowing a convenient spelling for
-adapter lookup: just "call" the interface, passing the context:
-
-.. doctest::
-
- >>> adapted = I2(ob)
- >>> adapted.__class__ is Comp
- True
- >>> adapted.context is ob
- True
-
-If the lookup fails, we get a `TypeError`:
-
-.. doctest::
-
- >>> I2(object())
- Traceback (most recent call last):
- ...
- TypeError: ('Could not adapt'...
-
-unless we pass a default:
-
-.. doctest::
-
- >>> marker = object()
- >>> adapted = I2(object(), marker)
- >>> adapted is marker
- True
-
-Registering Adapters For Arbitrary Objects
-##########################################
-
-Providing an adapter for None says that your adapter can adapt anything
-to `I2`.
-
-.. doctest::
-
- >>> gsm.registerAdapter(Comp, (None,), I2, '')
- >>> adapter = I2(ob)
- >>> adapter.__class__ is Comp
- True
- >>> adapter.context is ob
- True
-
-It can really adapt any arbitrary object:
-
-.. doctest::
-
- >>> something = object()
- >>> adapter = I2(something)
- >>> adapter.__class__ is Comp
- True
- >>> adapter.context is something
- True
-
-Looking Up Adapters Using Multiple Objects
-##########################################
-
-.. autofunction:: zope.component.getMultiAdapter
-
-.. autofunction:: zope.component.queryMultiAdapter
-
-Multi-adapters adapt one or more objects to another interface. To make
-this demonstration non-trivial, we need to create a second object to be
-adapted:
-
-.. doctest::
-
- >>> from zope.component.tests.test_doctests import Ob2
- >>> ob2 = Ob2()
-
-As with regular adapters, if an adapter isn't registered for the given
-objects and interface, the :func:`~zope.component.getMultiAdapter` API
-raises `ComponentLookupError`:
-
-.. doctest::
-
- >>> from zope.component import getMultiAdapter
- >>> getMultiAdapter((ob, ob2), I3)
- Traceback (most recent call last):
- ...
- ComponentLookupError:
- ((<instance Ob>, <instance Ob2>),
- <InterfaceClass zope.component.tests.test_doctests.I3>,
- u'')
-
-while the :func:`~zope.component.queryMultiAdapter` API returns the default:
-
-.. doctest::
-
- >>> from zope.component import queryMultiAdapter
- >>> queryMultiAdapter((ob, ob2), I3, default='<default>')
- '<default>'
-
-Note that ``name`` is not a required attribute here.
-
-To test multi-adapters, we also have to create an adapter class that
-handles to context objects:
-
-.. doctest::
-
- >>> from zope.interface import implementer
- >>> @implementer(I3)
- ... class DoubleAdapter(object):
- ... def __init__(self, first, second):
- ... self.first = first
- ... self.second = second
-
-Now we can register the multi-adapter:
-
-.. doctest::
-
- >>> from zope.component import getGlobalSiteManager
- >>> getGlobalSiteManager().registerAdapter(DoubleAdapter, (I1, I2), I3, '')
-
-Notice how the required interfaces are simply provided by a tuple.
-
-Now we can get the adapter:
-
-.. doctest::
-
- >>> adapter = getMultiAdapter((ob, ob2), I3)
- >>> adapter.__class__ is DoubleAdapter
- True
- >>> adapter.first is ob
- True
- >>> adapter.second is ob2
- True
-
-
-Finding More Than One Adapter
-#############################
-
-.. autofunction:: zope.component.getAdapters
-
-It is sometimes desireable to get a list of all adapters that are
-registered for a particular output interface, given a set of
-objects.
-
-Let's register some adapters first:
-
-.. doctest::
-
- >>> class I5(I1):
- ... pass
- >>> gsm.registerAdapter(Comp, [I1], I5, '')
- >>> gsm.registerAdapter(Comp, [None], I5, 'foo')
-
-Now we get all the adapters that are registered for ``ob`` that provide
-``I5``:
-
-.. doctest::
-
- >>> from zope.component import getAdapters
- >>> adapters = sorted(getAdapters((ob,), I5))
- >>> [(name, adapter.__class__.__name__) for name, adapter in adapters]
- [(u'', 'Comp'), (u'foo', 'Comp')]
-
-Note that the output doesn't include None values. If an adapter
-factory returns None, it is as if it wasn't present.
-
-.. doctest::
-
- >>> gsm.registerAdapter(lambda context: None, [I1], I5, 'nah')
- >>> adapters = sorted(getAdapters((ob,), I5))
- >>> [(name, adapter.__class__.__name__) for name, adapter in adapters]
- [(u'', 'Comp'), (u'foo', 'Comp')]
-
-
-Subscription Adapters
-#####################
-
-.. autofunction:: zope.component.subscribers
-
-Event handlers
-##############
-
-.. autofunction:: zope.component.handle
-
-Helpers for Declaring / Testing Adapters
-########################################
-
-.. autofunction:: zope.component.adapter
-
-.. autofunction:: zope.component.adaptedBy
-
-.. autofunction:: zope.component.adapts
-
-
-.. testcleanup::
-
- from zope.component.testing import tearDown
- tearDown()
-
-Factory APIs
-------------
-
-.. autofunction:: zope.component.createObject
-
-.. autofunction:: zope.component.getFactoryInterfaces
-
-.. autofunction:: zope.component.getFactoriesFor
-
-
-:mod:`zope.component.interfaces`
-================================
-
-.. automodule:: zope.component.interfaces
-
- .. autointerface:: IComponentArchitecture
- :members:
- :member-order: bysource
-
- .. autointerface:: IRegistry
- :members:
- :member-order: bysource
-
- .. autointerface:: IComponentRegistrationConvenience
- :members:
- :member-order: bysource
-
- .. autointerface:: IPossibleSite
- :members:
- :member-order: bysource
-
- .. autointerface:: ISite
- :members:
- :member-order: bysource
-
- .. autoexception:: Misused
-
- .. autointerface:: IFactory
- :members:
- :member-order: bysource
+ api/interfaces
+ api/sitemanager
+ api/utility
+ api/adapter
+ api/factory
More information about the checkins
mailing list