> On Jul 26, 2016, at 12:26 AM, Daniel Sank <sank.dan...@gmail.com> wrote: > > Glyph, > > >> 2. I have no idea what a "task" is. I realize this is python and yay > >> duck-typing but not > >> specifying the expected behavior of an argument seems like a big omission. > > > Did you miss the part where it said "type: 0-argument callable" in the > > documentation? > > Yes :( > > I can only guess that I missed it because the type is defined near the end of > the description line, whereas I'm used to seeing > > def foo(x, y): > """Do something. > > Args: > x (int): blah blah > y (banana): yadda yadda > """ > > FWIW, now that I look at the code, the type specification is way more > visually apparent there than it is in the generated HTML. > > tl,dr: I take it all back and thanks for pointing out the obvious.
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? :) > > An interface is a very simple concept - an abstract description of what an > > object is expected > > to provide if you're going to do something useful with it. > > Indeed, a general understanding of interfaces is not the problem. > > > In my view, interface definition is the primary activity of software > > development > > Agreed 100%. OK. Glad to hear it. > > The fact that so many people seem to find either the basic idea of an > > abstract type, or the concrete > > instantiation of that idea in the Zope Interface library, so horribly > > confusing, makes me despair of > > ever communicating the actually hard stuff that Twisted gets up to in its > > internals. > > > I would very much like to understand *what* is so confusing about > > "interfaces". Is it, as Cory posited, > > just that the documentation is not properly linked? Or is it that the > > average Python developer needs > > a gentle introduction to the entire idea of abstract rather than concrete > > types? If they do - is it really > > Twisted's responsibility to provide it to them? Should Zope Interface just > > have a snazzier website? > > 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. That documentation is not the best. Among other things, it's mainly trying to explain adaptation, which sort of puts the cart before the horse, and automatic adaptation is increasingly considered spooky action-at-a-distance within Twisted code. You can see it here: <http://twisted.readthedocs.io/en/latest/core/howto/components.html <http://twisted.readthedocs.io/en/latest/core/howto/components.html>>. 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. Personally, I find the examples very clear - I say the documentation is "not the best" because I could see how it could confuse somebody _else_, but it doesn't confuse _me_ at all, so it's a bit hard for me to improve it (especially incrementally). > A brief look at the zope documentation just now makes me think the situation > has improved. Well that's good, at least. perhaps we should link to it more prominently. > The other problem was that interfaces were sprinkled somewhat haphazardly > around the code I was trying to understand (perspective broker) and it was > just plain hard to keep navigating around the code files to understand who > was implementing what interfaces. This could have been my own fault for not > having a editor set up. I don't know. Setting up your editor to have a 'jump to definition' key definitely helps; but then, it generally helps with any large codebase. So, hard to say. > > Should Zope Interface just have a snazzier website? > > I think the real issue is the need for compelling and simple examples. Do you think it would be better to put things in terms of a concrete Twisted interface, like "IProtocol"? I am pretty sure these docs were trying to stay away from anything "real" because this is a highly abstract concept that could apply to anything, and when we drag a concrete example in > P.S. Everything below here is completely off topic of this thread and I > probably shouldn't have written it. In for a penny... (We may want to spin out into a different thread for talking about the PB issue, but it looks like this was unresolved for you, and I can definitely shed some more light.) > > Given that Twisted is often translating network protocol data into Python > > method calls, one needs both > > a working domain knowledge of the protocol involved and a robust > > understanding of Python > > metaprogramming constructs. It sounds here like where you fell down was > > mostly in the "Python > > metaprogramming" area, where PB is especially intense. > > > But it's also not really specific to Twisted either. This is another case > > where I'm not sure what to do > > except to refer people to the language reference and tell them to work > > through it slowly. > > > Unfortunately, framework code just looks like that > > I spent a considerable amount of time reading the PB code, reproducing parts > of it myself, and talking to people on IRC and the mailing list to understand > a particularly weird issue in PB. See here for the bug I was trying to fix > (note in particular my first comment to the one existing answer): > > http://stackoverflow.com/questions/23421423/why-are-dummy-objects-created-in-twisteds-pb-system > > <http://stackoverflow.com/questions/23421423/why-are-dummy-objects-created-in-twisteds-pb-system> > > I distinctly recall that near the end of my efforts you (Glyph) or someone > else more or less told me that the PB code was old, horrible, and that the > issues I was trying to understand were probably incidental complexity due to > poor design etc. You guys were joking around on IRC about how ridiculous all > the dummy object construction is. So, I think this particular incident was > less due a lack of understanding of python metaprogramming and more due to PB > having some bizarre warts. OK. Maybe I made this sound a bit too simple, but it's still not really Twisted's fault. The bizarre warts here - and they are definitely here - are mostly an outgrowth of the bizarre mismatch between old-style and new-style classes, and the mad shuffle of random API deprecations, often without suitable replacements, or without suitable portable replacements, within the standard library. In the old-style world, you had Class objects. Class objects could be created in a variety of ways, but the Right™ way to make a new, empty class that hadn't had its initializer run was 'new.instance'. Of course, new.instance doesn't work with new-style classes, because now the Right™ way to make a new, empty class that hadn't had its initializer run was yourclass.__new__(). Unless of course you overrode __new__, which is totally allowed, so the caller can't know what that signature is supposed to be. So then you use `object.__new__(yourclass)´ in order to get a known signature - but of course that won't work at all with old-style classes. PB is bridging the gap between these two worlds, and it has to find hacks which work in both and don't draw in any deprecated APIs that are gone in python 3 in order to do it. This means you can't use the Right™ way at all, and instead must resort to contortions which depend on implementation details that happen to be held in common between both new-style and old-style objects. -glyph
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
