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

Jean-Paul Calderone exarkun at divmod.com
Wed Jan 25 10:21:00 EST 2006


On Wed, 25 Jan 2006 12:17:12 +0000, Michael Hudson <mwh at python.net> wrote:
>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).

Besides, you *have* to do this anyway:

    from foo import bar

    def baz():
        """
        See L{bar}.
        """

Jean-Paul




More information about the Twisted-Python mailing list