[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