[Twisted-Python] Pydoc parameter formatting and explaining interfaces

[Daniel Sank]

This is a branch from the thread with subject "Request for help with
Twisted bindings in M2Crypt".

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

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.

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.

--
Daniel Sank

[Glyph Lefkowitz]

This is a branch from the thread with subject "Request for help with Twisted bindings in M2Crypt".

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

[Clayton Daley]

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

Post by Daniel Sank
This is a branch from the thread with subject "Request for help with
Twisted bindings in M2Crypt".

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
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python