[Python-Dev] Re: [PEP 224] Attribute Docstrings (original) (raw)

M.-A. Lemburg mal@lemburg.com
Tue, 29 Aug 2000 11:00:49 +0200

David Goodger wrote:

on 2000-08-28 15:35, M.-A. Lemburg (mal@lemburg.com) wrote: > Christian Tanzer wrote: >> >> "M.-A. Lemburg" <mal@lemburg.com> wrote: >> >>>> IMHO, David Goodger's (<dgoodger@bigfoot.com>) idea of using a >>>> docs dictionary is a better solution: >>>> >>>> - It provides all docstrings for the attributes of an object in a >>>> single place. >>>> >>>> * Handy in interactive mode. >>>> * This simplifies the generation of documentation considerably. >>>> >>>> - It is easier to explain in the documentation >>> >>> The downside is that it doesn't work well together with >>> class inheritance: docstrings of the above form can >>> be overridden or inherited just like any other class >>> attribute. >> >> Yep. That's why David also proposed a doc' function combining the_ _>> docs' of a class with all its ancestor's docs. > > The same can be done for doc style attributes:_ > a helper function would just need to look at dir(Class) and then > extract the attribute doc strings it finds. It could also do > a DFS search to find a complete API description of the class > by emulating attribute lookup and combine method and attribute > docstrings to produce some nice online documentation output. Using dir(Class) wouldn't find any inherited attributes of the class. A depth-first search would be required for any use of attribute docstrings.

Uhm, yes... that's what I wrote in the last paragraph.

The advantage of the doc_attribute name-mangling scheme (over docs dictionaries) would be that the attribute docstrings would be accessible from subclasses and class instances. But since "these attributes are meant for tools to use, not humans," this is not an issue.

I understand that you would rather like a "frozen" version of the class docs, but this simply doesn't work out for the common case of mixin classes and classes which are built at runtime.

The name mangling is meant for internal use and just to give the beast a name ;-)

Doc tools can then take whatever action they find necessary and apply the needed lookup, formatting and content extraction. They might even add a frozen docs attribute to classes which are known not to change after creation.

I use such a function which I call freeze() to optimize many static classes in my applications: the function scans all available attributes in the inheritance tree and adds them directly to the class in question. This gives some noticable speedups for deeply nested class structures or ones which use many mixin classes.

Just to find all attribute names, in order to extract the docstrings, you would have to go through a depth-first search of all base classes. Since you're doing that anyway, why not collect docstrings as you collect attributes? There would be no penalty. In fact, such an optimized function could be written and included in the standard distribution.

A perfectly good model exists in dict and dir(). Why not imitate it?

Sure, but let's do that in a doc() utility function.

I want to keep the implementation of this PEP clean and simple. All meta-logic should be applied by external helpers.

on 2000-08-28 04:28, M.-A. Lemburg (mal@lemburg.com) wrote: > This would not work well together with class inheritance.

It seems to me that it would work exactly as does class inheritance, cleanly and elegantly.

Right, and that's why I'm proposing to use attributes for the docstrings as well: the docstrings will then behave just like the attributes they describe.

The doc_attribute name-mangling scheme strikes me as un-Pythonic, to be honest.

It may look a bit strange, but it's certainly not un-Pythonic: just look at private name mangling or the many xxx hooks which Python uses.

Let me restate: I think the idea of attribute docstring is great. It brings a truly Pythonic, powerful auto-documentation system (a la POD or JavaDoc) closer. And I'm willing to help!

Thanks,

Marc-Andre Lemburg

Business: http://www.lemburg.com/ Python Pages: http://www.lemburg.com/python/