[Twisted-Python] Pydoc parameter formatting and explaining interfaces

Clayton Daley clayton.daley at gmail.com
Tue Jul 26 17:41:54 MDT 2016


Speaking just from my own experience, I don't think it's a problem with the
docs per se.  Rather, I think there's often a disconnect between the
answers people are looking for and the nature of Twisted.  It's hard to
explain, but this is the best I can manage:

   - If you're used to using frameworks, interfaces reflect your motives
   when interacting with a library.  To use an audio-video (A/V) analogy, you
   have interfaces like IVolume, IPlayback (play, pause, stop, ff, rew), and
   IChannel. Documentation just "makes sense".
   - Twisted is like a box of electronics parts.  The docs are enough to
   see why IDigital and IAnalog are used by DigitalToAnalogConverter, but
   that's a long way from understanding when you'd even need/care to consume
   something using an IAnalog.
   - There are several layers of architecture between a LineReader and a
   REST library.  If you don't realize these layers exist, it's not obvious
   that you'd need to find/create them in a Twisted app.
   - The (excellent) krondo tutorial is like a small kit that shows you how
   to build a model piece of electronics.  If you want to build a complete A/V
   device, where do you go next?

To make it more concrete for twisted, here's a example of that next step:

   - Start with the chat server example (
   https://twistedmatrix.com/documents/current/_downloads/chatserver.py)
   - To add rooms, you need to introduce a layer of commands (minimally
   JOIN and SEND).  This requires a complete rewrite of the Protocol and I'm
   not aware of any tutorial that helps you make this architectural leap.
   - Maybe Twisted has a class for this so one might search the docs, spend
   lots of time, get really confused, and (tentatively) conclude it's not
   there.  Figuring out that something doesn't exist is especially hard.
   - The authentication example (
   https://twistedmatrix.com/documents/current/core/howto/cred.html)
   actually has a command layer, but key parts of it (i.e. the lineReceived
   call) are buried in the ellipses.  How do you intuit the missing code if
   you don't even realize that you need a commands layer?
   - Of course, to combine auth with chat, you also need to figure out how
   to rewrite the business logic as an IMailbox implementing avatars.  That's
   a LOT of moving pieces to get right at the same time.

When I decided to try out Zend Framework (PHP), their full-stack skeleton
application (
https://docs.zendframework.com/tutorials/getting-started/skeleton-application/)
showed you how everything fit together. Maybe twisted would benefit from
something similar... especially if it emphasized the various architectural
layers by putting the protocol, command handler, and actual business logic
into separate classes.

Clayton Daley

On Tue, Jul 26, 2016 at 12:58 PM, Glyph Lefkowitz <glyph at twistedmatrix.com>
wrote:

>
> On Jul 26, 2016, at 9:37 AM, Daniel Sank <sank.daniel at gmail.com> wrote:
>
> This is a branch from the thread with subject "Request for help with
> Twisted bindings in M2Crypt".
>
> Regarding my inability to read documentation:
>
> > This does at least point to a real problem with pydoctor in the way it
> presents types.
> > It should probably put them in their own colored box, not use the string
> 'type' or
> > parentheses to offset them, and put the type closer to (rather than
> farther from) the
> > parameter name.  Would you mind filing a bug on pydoctor?  Or commenting
> on
> > one if it already exists? :)
>
> Done: https://github.com/twisted/pydoctor/issues/121
>
>
> Thanks!  I especially appreciate the screen shot :).
>
> >> Some years ago when I tried to understand Twisted's use of interfaces
> via Twisted's
> >> own documentation (which included something about hair dryers and
> voltage standards)
> >> I was puzzled by the fact that the examples didn't really show me how
> to solve a useful
> >> problem (or I was too stupid to understand that the examples did in
> fact do that) despite
> >> the fact that I knew what an interface was in general terms. It was a
> case of
> >> understanding the intent but none of the examples.
>
> > OK... it's a fair cop.
>
> I'm unfamiliar with that term.
>
>
> For *me* it's a monty python reference, but I suspect for most speakers
> of British English, it's just an idiom :).  It roughly means "mea culpa",
> although, more specifically, I believe it means "you've caught me doing
> something bad".
>
> > Among other things, it's mainly trying to explain adaptation, which sort
> of puts the cart before
> > the horse
>
> Yes! That is definitely a big part of the problem. When I think
> "interface" I think "methods and their signatures an object promises to
> provided". Adaptation is a detail, so to speak. It's also somewhat
> confusing that the discussion begins with shapes as it goes over the basic
> idea of interfaces, and then switches to hair dryers when it comes time for
> an example. It would be easier to read if the examples were more consistent.
>
> > and automatic adaptation is increasingly considered spooky
> action-at-a-distance within
> > Twisted code.
>
> All the more reason to not use adaptation as the in-your-face example.
>
> > You're the perfect person to submit patches against this doc, by the
> way, since you have a
> > firm grasp of the whole "abstract interface" thing but also found it
> confusing.
>
> Perhaps. On the other hand I think it might be better to replace Twisted's
> own documentation with a link to zope's, or at least put the link at the
> top and say "read this before reading our examples about adaptation." We'll
> see if such a patch receives any love.
>
>
> Please direct my attention to it when one exists :).
>
> -glyph
>
> _______________________________________________
> Twisted-Python mailing list
> Twisted-Python at twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20160726/a9e58af9/attachment-0002.html>


More information about the Twisted-Python mailing list