Feedback: A Grok-Centric Explanation of Adaptation

[Philipp von Weitershausen]

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.

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.

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Danny Navarro-2]

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
_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Philipp von Weitershausen]

El 21 Jul 2008, a las 07:31 , Danny Navarro escribió:

>> 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):

The trailing colon and the following indention is wrong.

>            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.

Ok. However, I think this should then be separated from the above  
code. For instance, we could show the above example, then say "so  
let's implement such an adapter" and then do it. I don't think we need  
those Laptop and Project objects for those. In fact, they're  
absolutely irrelevant to the adapter implementation. If at all, they  
should be mentioned in a footnote.

>    class LaptopWithVGA(object):
>        """Laptop with VGA port"""
>        implements(IVGAPort)
>
>        def connect(display):
>            if IVGAPort.providedBy(display) is None:

This check doesn't make sense. You probably want to say:

   if not IVGAPort.providedBy(display):

>                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)

This adapter violates the IVGAPort interface because it doesn't  
implement the connect() method. It's also not a very useful example of  
adapters. I disagree that it would be helpful to see how adapters are  
implemented, but then let's please show a useful implementation. An  
empty adapter implementation could make people think that it all  
happens automagically.

Also, adapts(IDVIPort) is wrong. you want to say grok.context(IDVIPort).

>    class LaptopWithDVI(object):
>        """Laptop with DVI port"""
>        implements(IDVIPort)
>
>       def connect(display):
>           if IVGAPort.providedBy(display) is None:

Here you probably want to check for IDVIPort.providedBy()... And, as  
with above, the check doesn't make sense.

>                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)

The placement of this implements() directive is wrong. It needs to go  
one level up.

> 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.

If you can't come up with a simple enough example that explains  
things, perhaps the comparison we're trying to make is flawed :).  
That's why I suggested only to show those things that do make sense  
within this comparision and to forget about the rest. As far as I'm  
concerned, this piece is to make people understand the *concept*, not  
the specifics of the implementation.

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Danny Navarro-2]

Hi Philipp,

Sorry for the dummy mistakes in the code. Next time I'll make sure I  
can run the code in the interactive prompt before sending it.

In the end the DVI to VGA adapter might not be a good example to  
explain the adaptation concept. Better to focus on how to use the  
adapter without showing the implementation. I'll make the point that  
you don't care about the implementation of the adapter, you just use  
the adapter.

I will still think in another very visual and simple scenario where an  
example of an implementation makes sense. Just for whomever wants to  
check how a typical implementation looks like.

Thanks,

Danny

On 22 Jul 2008, at 11:05, Philipp von Weitershausen wrote:

> El 21 Jul 2008, a las 07:31 , Danny Navarro escribió:
>>> 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):
>
> The trailing colon and the following indention is wrong.
>
>>           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.
>
> Ok. However, I think this should then be separated from the above  
> code. For instance, we could show the above example, then say "so  
> let's implement such an adapter" and then do it. I don't think we  
> need those Laptop and Project objects for those. In fact, they're  
> absolutely irrelevant to the adapter implementation. If at all, they  
> should be mentioned in a footnote.
>
>>   class LaptopWithVGA(object):
>>       """Laptop with VGA port"""
>>       implements(IVGAPort)
>>
>>       def connect(display):
>>           if IVGAPort.providedBy(display) is None:
>
> This check doesn't make sense. You probably want to say:
>
>  if not IVGAPort.providedBy(display):
>
>>               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)
>
> This adapter violates the IVGAPort interface because it doesn't  
> implement the connect() method. It's also not a very useful example  
> of adapters. I disagree that it would be helpful to see how adapters  
> are implemented, but then let's please show a useful implementation.  
> An empty adapter implementation could make people think that it all  
> happens automagically.
>
> Also, adapts(IDVIPort) is wrong. you want to say  
> grok.context(IDVIPort).
>
>>   class LaptopWithDVI(object):
>>       """Laptop with DVI port"""
>>       implements(IDVIPort)
>>
>>      def connect(display):
>>          if IVGAPort.providedBy(display) is None:
>
> Here you probably want to check for IDVIPort.providedBy()... And, as  
> with above, the check doesn't make sense.
>
>>               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)
>
> The placement of this implements() directive is wrong. It needs to  
> go one level up.
>
>> 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.
>
> If you can't come up with a simple enough example that explains  
> things, perhaps the comparison we're trying to make is flawed :).  
> That's why I suggested only to show those things that do make sense  
> within this comparision and to forget about the rest. As far as I'm  
> concerned, this piece is to make people understand the *concept*,  
> not the specifics of the implementation.
>

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Kevin Teague]

Thanks for the feedback!

I've been tinkering with this document. I added a connectToVGA(display) method to IVGAPort, and cleaned up the plugLaptopIntoProjecter example function to remove the nasty providedBy check, and removed the Laptop and Projecter Models. Then I expanded upon the explanation of the DVIToVGAAdapter, and made a note about why one shouldn't care about object identity after performing adapation (which is an important point not made in the original example).

http://grok.zope.org/documentation/tutorial/a-grok-centric-explanation-of-adaptation/a-real-world-example-of-adaption

Overall this page still reads "a touch clunky" - it could be smoothed out to read a little more straightforward - so further edits and suggestions are still welcome.