[Grok-dev] Feedback: A Grok-Centric Explanation of Adaptation

[Danny Navarro]

Hi Philipp,

On 20 Jul 2008, at 12:20, Philipp von Weitershausen wrote:

> Thanks to whomever wrote http://grok.zope.org/documentation/tutorial/a-grok-centric-explanation-of-adaptation 
> . It's good to see more tutorials explaining adaption out there.

As I am learning Grok I was missing some more documentation filling  
the gap between the introductory tutorial and the rest of the  
documentation, specially some introduction to interfaces and adapters.  
So I suggested Kevin's entry to be put on http://grok.zope.org.

http://www.bud.ca/blog/adaptation-explained

I mentioned in the last page of the tutorial, in further reading, that  
the tutorial was taken from Kevin's blog but perhaps I should mention  
it in the beginning of the tutorial. I don't know what is the credit  
policy to follow for Grok documentation.

>
>
> I only skimmed the article, mostly looked at the code. May I suggest  
> a few improvements? The VGA port example could be improved a lot if
>
> * IVGAPort would gain a description for that 'connect()' method  
> that's used in plugLaptopIntoProjecter.
>
>
> * The two models and the adapter implementation were removed. They  
> don't seem to add any value to the understanding of adaption at this  
> point. In particular, the emtpy adapter implementation is just plain  
> confusing since it doesn't at all describe what an adapter really  
> has to do.
>
>
> * plugLaptopIntoProjecter were more concise and written in a  
> realistic way. Here's how I would have written it:
>
>
>  def plugLaptopIntoProjecter(laptop, projector):
>      "Display your presentation on the wall!"
>
>      vga_capable = IVGAPort(laptop, None):
>      if vga_capable is None:
>          print "You should get a MacBook Pro."
>      vga_capable.connect(projector)
>
>
>
> There's no need for that I...Port.providedBy() business. In fact,  
> the whole point of adaption is to NOT care about the object you have  
> at hadn and and simply trying to adapt it to something you DO care  
> about instead. Whether or not this yield the identity relation (iow,  
> getting the same object back) is irrelevant at that point.

I agree that the first example should be as simple as possible. We can  
substitute then the first example with something like this:

     from zope.interface import Interface

     class IVGAPort(Interface):
         """Video connection using VGA"""

         def connect(display):
             """Connect display to VGA port"""

     class IDVIPort(Interface):
         """Video connection using DVI"""

         def connect(display):
             """Connect display to DVI port"""

     def plugLaptopIntoProjector(laptop, projector):
         """Display your presentation on the wall"""

         vga_capable = IVGAPort(laptop, None):
             if vga_capable is None:
                 print "Get a laptop with VGA or DVI port"
             vga_capable.connect(projector)

However I think it will help to give next a implementation example of  
a laptop with VGA, a laptop with DVI and an  adapter from DVI to VGA.  
Just to explain what would happen in the above example if you had a  
laptop with DVI port.

     class LaptopWithVGA(object):
         """Laptop with VGA port"""
         implements(IVGAPort)

         def connect(display):
             if IVGAPort.providedBy(display) is None:
                 print "Can't connect VGA laptop, %s doesn't provide  
VGA port" % (display)
             print "Laptop connected to", display

     class DVItoVGAAdapter(Grok.Adapter):
          implements(IVGAport)
          adapts(IDVIport)

     class LaptopWithDVI(object):
         """Laptop with DVI port"""
         implements(IDVIPort)

        def connect(display):
            if IVGAPort.providedBy(display) is None:
                 print "Can't connect VGA laptop, %s doesn't provide  
VGA port" % (display)
             print "Laptop connected to", display

     class Projecter(object):

         def connect(display):
             """Projecter with VGA port"""
             implements (IVGAport)


It doesn't look good to use providedBy in the implementation but we  
can explain that in this case it is used for demonstration purposes.  
Without using providedBy I can't come now with a simple implementation  
of connect method so that the Laptop with DVI port fails when the  
projecter provides IVGA port and there is no DVI to VGA adapter.

Regards,

Danny Navarro