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

Christopher Armstrong radeex at gmail.com
Wed Jan 25 05:35:13 EST 2006


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

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

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




More information about the Twisted-Python mailing list