[Zope3-dev] Need help with jargon

[Steve Alexander]

Hi Jim,

I'm following up on the conversation we had just now on the  #zope3-dev 
irc channel.

Steve wrote:
 >> So, compared to other languages / systems, utilities are a bit like 
 >> globals, multi-adapters are like multimethods and pep246 adapters 
are >> adapters.

Jim wrote:
 > That's a good summary, with the added twist that the parts are
 > configurable outside the program.
 > Pretty much the only thing that utilities add over, say modules, is:
 >
 > - Pluggability
 >
 > - Limited searchability/listability, which turns out to be useful.
 >   We can list them in UIs for example.

In that case, let's call utilities "singletons", as that's the role they 
play in an application.  Let's call multi-adapters "utilities" as PJE 
suggests, and let's call PEP 246 adapters "adapters" as PEP 246 suggests.

   Current                          Proposed

   adapter (PEP-246 style)          adapter

   multi-adapter / named adapter    utility

   utility                          singleton



I think what we currently call "utilities" should be called "singletons" 
because this aspect of their nature is currently important but rather 
subtle and easily missed by users of Zope 3 and the component architecture.

If they were called "singletons" then:

- Programmers who are familiar with design patterns would have a
   clue what they should consider using utilities for in their
   applications.

- There would be less need to explain the use of "factory" in the
   zcml "utility" directive.

- There would be less need to explain that a client of what is currently
   "getAdapter" owns the returned object, but a client of "getUtility"
   recieves a "shared" object.

- The term "utility" would be available to describe multi-adapters.


Consider the tutorial slides.  Here are some excerpts from the slides, 
with "utility" replaced with "singleton".  Excerpts from the tutorial 
slides are indented.

   In this example, we'll create an adapter for obtaining city and
   state information for buddies.
   * Use the buddy postal code
   * Use a singleton to look up the city and state information
     given the postal code.

   <content class=".stubpostal.Info">
     <allow interface=".interfaces.IPostalInfo" />
   </content>

   <singleton
       factory=".stubpostal.Lookup"
       provides=".interfaces.IPostalLookup"
       permission="zope.Public"
       />

(There, no more needing to explain the special rule about the factory 
being a convenience and being called only once.)

   class BuddyCityState:
       """Provide city and state information for a buddy

       The adapter needs a postal-lookup singleton.  For the
       sake of the example, we'll install one, but first,
       we have to set up the component architecture:

         >>> from zope.app.tests import placelesssetup, ztapi
         >>> placelesssetup.setUp()

       and then we can provide the singleton:

         >>> from stubpostal import Lookup
         >>> ztapi.provideSingleton(IPostalLookup, Lookup())


   zope.interface.implements(IPostalInfo)

   __used_for__ = IBuddy

   def __init__(self, buddy):
       lookup = zapi.getSingleton(buddy, IPostalLookup)
       info = lookup.lookup(buddy.postal_code)
       if info is None:
           self.city, self.state = '', ''
       else:
           self.city, self.state = info.city, info.state

--
Steve Alexander