Changeset 5820 for main

Timestamp:

9 Mar 2011, 13:41:27 (14 years ago)

Author:

uli

Message:

Add interface for applicants container providers.

File:

• main/waeup.sirp/trunk/src/waeup/sirp/applicants/interfaces.py (modified) (1 diff)

main/waeup.sirp/trunk/src/waeup/sirp/applicants/interfaces.py

@@ -771 +771 @@
     def getJAMBRegNo():
         """Return the JAMB registration no."""
+
+class IApplicantContainerProvider(Interface):
+    """A provider for applicants containers.
+
+    Applicants container providers are meant to be looked up as
+    utilities. This way we can find all applicant container types
+    defined somewhere.
+
+    Each applicants container provider registered as utility provides
+    one container type and one should be able to call the `factory`
+    attribute to create an instance of the requested container type.
+
+    .. THE FOLLOWING SHOULD GO INTO SPHINX DOCS (and be tested)
+    
+    Samples
+    *******
+    
+    Given, you had an IApplicantsContainer implementation somewhere
+    and you would like to make it findable on request, then you would
+    normally create an appropriate provider utility like this::
+
+      import grok
+      from waeup.sirp.applicants.interfaces import IApplicantContainerProvider
+
+      class MyContainerProvider(grok.GlobalUtility):
+          grok.implements(IApplicantContainerProvider)
+          grok.name('MyContainerProvider') # Must be unique
+          factory = MyContainer # A class implementing IApplicantsContainer
+                                # or derivations thereof.
+
+    This utility would be registered on startup and could then be used
+    like this:
+
+      >>> from zope.component import getAllUtilitiesRegisteredFor
+      >>> from waeup.sirp.applicants.interfaces import (
+      ...     IApplicantContainerProvider)
+      >>> all_providers = getAllUtilitiesRegisteredFor(
+      ...     IApplicantContainerProvider)
+      >>> all_providers
+      [<MyContainerProvider object at 0x...>]
+
+    You could look up this specific provider by name:
+
+      >>> from zope.component import getUtility
+      >>> p = getUtility(IApplicantContainerProvider, name='MyProvider')
+      >>> p
+      <MyContainerProvider object at 0x...>
+      
+    An applicants container would then be created like this:
+
+      >>> provider = all_providers[0]
+      >>> container = provider.factory()
+      >>> container
+      <MyContainer object at 0x...>
+
+    """
+    factory = Attribute("A class that can create instances of the "
+                        "requested container type")