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

Michael Hudson mwh at python.net
Wed Jan 25 05:13:06 EST 2006


Jean-Paul Calderone <exarkun at divmod.com> writes:

> On Mon, 23 Jan 2006 17:14:32 +0000, Michael Hudson <mwh at python.net> wrote:
>>Andrew Bennetts <andrew-twisted at puzzling.org> writes:
>>
>>> [moving this to twisted-python, where it clearly belongs]
>>>
>>> Michael Hudson wrote:
>>> [...]
>>>>
>>>> Well, I've had a quick pop at the interesting bit of this task while
>>>> travelling over the weekend: using the compiler module I can extract
>>>> the docstrings and class hierachy of all the stuff in the Twisted
>>>> source.  It's a touch fragile, but seems to work for all the
>>>> constructions used by Twisted.
>>>>
>>>> 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 :)

>>
>>Hmm, that could work.  Although having the "official" name for a class
>>different from its __name__ is fairly horrible :)
>>
>>> 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.

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





More information about the Twisted-Python mailing list