[Twisted-Python] Re: [Twisted-web] Re: Actual Useful Post
[moving this to twisted-python, where it clearly belongs] Michael Hudson wrote: [...]
See http://twistedmatrix.com/bugs/issue1143. It has the possibly useful suggestion of using __all__ to determine where an aliased thing should be documented. Another option is some sort of explicit hint to the doc extractor, e.g. a define no-op call like "alias('Serializable')" in the relevant module that the doc extractor could notice. Or keep an explicit list of overrides in a file... -Andrew.
Andrew Bennetts <andrew-twisted@puzzling.org> writes:
Hmm, that could work. Although having the "official" name for a class different from its __name__ is fairly horrible :)
These also could work, as could magic comments (though that would be marginally harder). Cheers, mwh -- What the semicolon's anxious supporters fret about is the tendency of contemporary writers to use a dash instead of a semicolon and thus precipitate the end of the world. -- Lynne Truss, "Eats, Shoots & Leaves"
Jean-Paul Calderone <exarkun@divmod.com> writes:
The pb classes are not in an __all__ currently. I also think that __all__ is an abomination, but I'll try to suppress that :)
There's going to need to be some magic/special casing at some level, to deal with twisted.python.components.Interface. Cheers, mwh -- Screaming 14-year-old boys attempting to prove to each other that they are more 3133t than j00. -- Reason #8 for quitting slashdot today, from http://www.cs.washington.edu/homes/klee/misc/slashdot.html
On 1/25/06, Michael Hudson <mwh@python.net> wrote:
I agree about __all__ being an abomination. I also don't see how we can use __all__ to determine where they're documented without doing something weird or hard. For example, from foo import bar __all__ == 'bar' with static analysis of Python code it is impossible to know what source 'bar' is from. Ok, we can at least have a best try at finding the source by trawling PYTHONPATH or something. Don't forget, we should *also* either prevent the object from being documented at its definition-source, or perhaps put a reference from there to the "official" name in the docs. Hence, I think it's better to have something more explicit to mark "official FQPNs", like aliases = {'twisted.spread.flavors.Referenceable': 'twisted.spread.pb.Referenceable'}.
Hmm, that could work. Although having the "official" name for a class different from its __name__ is fairly horrible :)
Is that a suggestion to hack the __name__ attribute, or to not do this kind of interface-different-from-implementation stuff?
I prefer something like __doc_alias__ = ... to alias(). It's faster! ;-) I also wouldn't mind just putting this in some file *outside* of the Python code, but I think I prefer slightly to have it next to where it's relevant (and easier to maintain). -- Twisted | Christopher Armstrong: International Man of Twistery Radix | -- http://radix.twistedmatrix.com | Release Manager, Twisted Project \\\V/// | -- http://twistedmatrix.com |o O| | w----v----w-+
Christopher Armstrong <radeex@gmail.com> writes:
Not really, no: this is part of the reason my code defines a "System" and shoves all the data into it. So long as 'foo' is one of the modules that gets fed to the extractor, you can resolve this kind of thing (I've done it before).
Yes, absolutely.
Well, it just strikes me that from twisted.mail.pop3client import POP3Client as AdvancedPOP3Client is a little weird. It will show up in reprs and so on as "POP3Client", which seems likely to confuse the poor user if it's "really" AdvancedPOP3Client.
Anything is possible :) Cheers, mwh -- The gripping hand is really that there are morons everywhere, it's just that the Americon morons are funnier than average. -- Pim van Riezen, alt.sysadmin.recovery
Jean-Paul Calderone <exarkun@divmod.com> writes:
This is really easy if bar really is "foo.bar". If foo is a local import, or if foo.py does from baz import quux as bar then it's harder, but still possible -- I wrote code last night to handle the latter case and will check it in soon-ish. Cheers, mwh -- I can't see a conspicuous evolutionary advantage in being good at higher mathematics. -- James Riden, asr
On 1/25/06, Michael Hudson <mwh@python.net> wrote:
There's going to need to be some magic/special casing at some level, to deal with twisted.python.components.Interface.
Oh right, I forgot to ask: what do you mean about this? extracting the docs from an Interface should really be the same as extracting it from a class... of course, it'd also be *hella* useful for the doc extractor to find implements() lines in the *implementations* of those Interfaces.. Is that what you're referring to? -- Twisted | Christopher Armstrong: International Man of Twistery Radix | -- http://radix.twistedmatrix.com | Release Manager, Twisted Project \\\V/// | -- http://twistedmatrix.com |o O| | w----v----w-+
Christopher Armstrong <radeex@gmail.com> writes:
Well, I'm not entirely sure what I meant :) I was somewhat assuming that you'd want to document interfaces differently from classes and that specifically you'd want to document t.p.c.Interface *somehow* and it's currently defined like this: Interface = MetaInterface("Interface", __module__="twisted.python.components") which doesn't look much like a class to my code.
No, but that could be done too. Cheers, mwh -- Well, you pretty much need Microsoft stuff to get misbehaviours bad enough to actually tear the time-space continuum. Luckily for you, MS Internet Explorer is available for Solaris. -- Calle Dybedahl, alt.sysadmin.recovery
Andrew Bennetts <andrew-twisted@puzzling.org> writes:
Hmm, that could work. Although having the "official" name for a class different from its __name__ is fairly horrible :)
These also could work, as could magic comments (though that would be marginally harder). Cheers, mwh -- What the semicolon's anxious supporters fret about is the tendency of contemporary writers to use a dash instead of a semicolon and thus precipitate the end of the world. -- Lynne Truss, "Eats, Shoots & Leaves"
Jean-Paul Calderone <exarkun@divmod.com> writes:
The pb classes are not in an __all__ currently. I also think that __all__ is an abomination, but I'll try to suppress that :)
There's going to need to be some magic/special casing at some level, to deal with twisted.python.components.Interface. Cheers, mwh -- Screaming 14-year-old boys attempting to prove to each other that they are more 3133t than j00. -- Reason #8 for quitting slashdot today, from http://www.cs.washington.edu/homes/klee/misc/slashdot.html
On 1/25/06, Michael Hudson <mwh@python.net> wrote:
I agree about __all__ being an abomination. I also don't see how we can use __all__ to determine where they're documented without doing something weird or hard. For example, from foo import bar __all__ == 'bar' with static analysis of Python code it is impossible to know what source 'bar' is from. Ok, we can at least have a best try at finding the source by trawling PYTHONPATH or something. Don't forget, we should *also* either prevent the object from being documented at its definition-source, or perhaps put a reference from there to the "official" name in the docs. Hence, I think it's better to have something more explicit to mark "official FQPNs", like aliases = {'twisted.spread.flavors.Referenceable': 'twisted.spread.pb.Referenceable'}.
Hmm, that could work. Although having the "official" name for a class different from its __name__ is fairly horrible :)
Is that a suggestion to hack the __name__ attribute, or to not do this kind of interface-different-from-implementation stuff?
I prefer something like __doc_alias__ = ... to alias(). It's faster! ;-) I also wouldn't mind just putting this in some file *outside* of the Python code, but I think I prefer slightly to have it next to where it's relevant (and easier to maintain). -- Twisted | Christopher Armstrong: International Man of Twistery Radix | -- http://radix.twistedmatrix.com | Release Manager, Twisted Project \\\V/// | -- http://twistedmatrix.com |o O| | w----v----w-+
Christopher Armstrong <radeex@gmail.com> writes:
Not really, no: this is part of the reason my code defines a "System" and shoves all the data into it. So long as 'foo' is one of the modules that gets fed to the extractor, you can resolve this kind of thing (I've done it before).
Yes, absolutely.
Well, it just strikes me that from twisted.mail.pop3client import POP3Client as AdvancedPOP3Client is a little weird. It will show up in reprs and so on as "POP3Client", which seems likely to confuse the poor user if it's "really" AdvancedPOP3Client.
Anything is possible :) Cheers, mwh -- The gripping hand is really that there are morons everywhere, it's just that the Americon morons are funnier than average. -- Pim van Riezen, alt.sysadmin.recovery
Jean-Paul Calderone <exarkun@divmod.com> writes:
This is really easy if bar really is "foo.bar". If foo is a local import, or if foo.py does from baz import quux as bar then it's harder, but still possible -- I wrote code last night to handle the latter case and will check it in soon-ish. Cheers, mwh -- I can't see a conspicuous evolutionary advantage in being good at higher mathematics. -- James Riden, asr
On 1/25/06, Michael Hudson <mwh@python.net> wrote:
There's going to need to be some magic/special casing at some level, to deal with twisted.python.components.Interface.
Oh right, I forgot to ask: what do you mean about this? extracting the docs from an Interface should really be the same as extracting it from a class... of course, it'd also be *hella* useful for the doc extractor to find implements() lines in the *implementations* of those Interfaces.. Is that what you're referring to? -- Twisted | Christopher Armstrong: International Man of Twistery Radix | -- http://radix.twistedmatrix.com | Release Manager, Twisted Project \\\V/// | -- http://twistedmatrix.com |o O| | w----v----w-+
Christopher Armstrong <radeex@gmail.com> writes:
Well, I'm not entirely sure what I meant :) I was somewhat assuming that you'd want to document interfaces differently from classes and that specifically you'd want to document t.p.c.Interface *somehow* and it's currently defined like this: Interface = MetaInterface("Interface", __module__="twisted.python.components") which doesn't look much like a class to my code.
No, but that could be done too. Cheers, mwh -- Well, you pretty much need Microsoft stuff to get misbehaviours bad enough to actually tear the time-space continuum. Luckily for you, MS Internet Explorer is available for Solaris. -- Calle Dybedahl, alt.sysadmin.recovery
participants (4)
-
Andrew Bennetts -
Christopher Armstrong -
Jean-Paul Calderone -
Michael Hudson