[Twisted-Python] Re: [Twisted-web] Re: Actual Useful Post

Michael Hudson mwh at python.net
Wed Jan 25 07:17:12 EST 2006


Christopher Armstrong <radeex at gmail.com> writes:

> On 1/25/06, Michael Hudson <mwh at python.net> wrote:
>> Jean-Paul Calderone <exarkun at divmod.com> writes:
>> > On Mon, 23 Jan 2006 17:14:32 +0000, Michael Hudson <mwh at python.net> wrote:
>> >>>> One issue is classes that are defined in one file but generally used
>> >>>> from another, for example twisted.spread.jelly.Serializable is often
>> >>>> (always?) imported as twisted.spread.pb.Serializable.  Where should it
>> >>>> be documented it?
>> >>>
>> >>> See http://twistedmatrix.com/bugs/issue1143.  It has the possibly useful
>> >>> suggestion of using __all__ to determine where an aliased thing should be
>> >>> documented.
>> >
>> > +1 for using a mechanism associated with an existing Python idiom
>>
>> The pb classes are not in an __all__ currently.  I also think that
>> __all__ is an abomination, but I'll try to suppress that :)
>
> 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.

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

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

Yes, absolutely.

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

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.

>> >>> 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...
>> >>
>> >>These also could work, as could magic comments (though that would be
>> >>marginally harder).
>> >
>> > -1 for magic markup embedded in source files
>>
>> There's going to need to be some magic/special casing at some level,
>> to deal with twisted.python.components.Interface.
>
> 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).

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





More information about the Twisted-Python mailing list