[Checkins] SVN: zope.component/tseaver-test_cleanup/ Document / test 'getUtilitiesFor' API.

[Tres Seaver]

Log message for revision 126905:
  Document / test 'getUtilitiesFor' API.

Changed:
  _U  zope.component/tseaver-test_cleanup/
  U   zope.component/tseaver-test_cleanup/docs/api.rst
  U   zope.component/tseaver-test_cleanup/src/zope/component/tests/test___init__.py

-=-
Modified: zope.component/tseaver-test_cleanup/docs/api.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/api.rst	2012-06-17 21:36:57 UTC (rev 126904)
+++ zope.component/tseaver-test_cleanup/docs/api.rst	2012-06-17 21:37:00 UTC (rev 126905)
@@ -164,12 +164,32 @@
 
 .. doctest::
 
-   >>> getGlobalSiteManager().registerUtility(ob, I1, name='foo')
-   >>> getUtility(I1, 'foo') is ob
+   >>> ob2 = object()
+   >>> getGlobalSiteManager().registerUtility(ob2, I1, name='foo')
+   >>> getUtility(I1, 'foo') is ob2
    True
-   >>> queryUtility(I1, 'foo') is ob
+   >>> queryUtility(I1, 'foo') is ob2
    True
 
+Querying Multiple Utilities
+###########################
+
+Sometimes it may be useful to query all utilities, both anonymous and named
+for a given interface.  The :function:`~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
+
 Delegated Utility Lookup
 ########################
 

Modified: zope.component/tseaver-test_cleanup/src/zope/component/tests/test___init__.py
===================================================================
--- zope.component/tseaver-test_cleanup/src/zope/component/tests/test___init__.py	2012-06-17 21:36:57 UTC (rev 126904)
+++ zope.component/tseaver-test_cleanup/src/zope/component/tests/test___init__.py	2012-06-17 21:37:00 UTC (rev 126905)
@@ -191,6 +191,28 @@
         getGlobalSiteManager().registerUtility(obj1, IFoo)
         self.assertTrue(queryUtility(IFoo, context=context) is obj2)
 
+    def test_getUtiltiesFor_nonesuch(self):
+        from zope.interface import Interface
+        from zope.component import getUtilitiesFor
+        class IFoo(Interface):
+            pass
+        self.assertEqual(list(getUtilitiesFor(IFoo)), [])
+
+    def test_getUtiltiesFor_anonymous_hit(self):
+        from zope.interface import Interface
+        from zope.component import getGlobalSiteManager
+        from zope.component import getUtilitiesFor
+        class IFoo(Interface):
+            pass
+        obj = object()
+        obj1 = object()
+        getGlobalSiteManager().registerUtility(obj, IFoo)
+        getGlobalSiteManager().registerUtility(obj1, IFoo, name='bar')
+        tuples = list(getUtilitiesFor(IFoo))
+        self.assertEqual(len(tuples), 2)
+        self.assertTrue(('', obj) in tuples)
+        self.assertTrue(('bar', obj1) in tuples)
+
     def test_getNextUtility_global(self):
         from zope.component import getGlobalSiteManager
         from zope.component import getNextUtility