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

M.-A. Lemburg mal@lemburg.com
Mon, 28 Aug 2000 10:28:16 +0200

[Note: Please CC: all messages on this thread to me directly as I am the PEP maintainer. If you don't, then I might not read your comments.]

David Goodger wrote:

Some comments: 1. I think the idea of attribute docstrings is a great one. It would assist in the auto-documenting of code immeasurably.

Agreed ;-)

2. I second Frank Niessink (frankn=nuws@cs.vu.nl), who wrote:

> wouldn't the naming > scheme .doc be a better one? > > So if: > > class C: > a = 1 > """Description of a.""" > > then: > > C.a.doc == "Description of a." 'C.a.doc' is far more natural and Pythonic than 'C.doc_a'. The latter would also require ugly tricks to access.

This doesn't work, since Python objects cannot have arbitrary attributes. Also, I wouldn't want to modify attribute objects indirectly from the outside as the above implies.

I don't really see the argument of doc__a being hard to access: these attributes are meant for tools to use, not humans ;-), and these tools can easily construct the right lookup names by scanning the dir(obj) and then testing for the various doc__xxx strings.

3. However, what would happen to C.a.doc (or C.doc_a for that matter) when attribute 'a' is reassigned? For example:

class C: a = 1 # class attribute, default value for instance attribute """Description of a.""" def init(self, arg=None): if arg is not None: self.a = arg # instance attribute self.b = [] """Description of b.""" instance = C(2) What would instance.a.doc (instance.doc_a) be? Would the doc be wiped out by the reassignment, or magically remain unless overridden?

See above. This won't work.

4. How about instance attributes that are never class attributes? Like 'instance.b' in the example above?

I don't get the point... doc strings should always be considered constant and thus be defined in the class/module definition.

5. Since docstrings "belong" to the attribute preceeding them, wouldn't it be more Pythonic to write:

class C: a = 1 """Description of a.""" ? (In case of mail viewer problems, each line above is indented relative to the one before.) This emphasizes the relationship between the docstring and the attribute. Of course, such an approach may entail a more complicated modification to the Python source, but also more complete IMHO.

Note that Python's indents block and these are always preceeded by a line ending in a colon. The above idea would break this.

6. Instead of mangling names, how about an alternative approach? Each class, instance, module, and function gets a single special name (call it 'docs' for now), a dictionary of attribute-name to docstring mappings. docs would be the docstring equivalent to dict. These dictionary entries would not be affected by reassignment unless a new docstring is specified. So, in the example from (3) above, we would have:

>>> instance.docs {'b': 'Description of b.'} >>> C.docs {'a': 'Description of a.'} Just as there is a built-in function 'dir' to apply Inheritance rules to instance.dict, there would have to be a function 'docs' to apply inheritance to instance.docs: >>> docs(instance) {'a': 'Description of a.', 'b': 'Description of b.'} There are repercussions here. A module containing the example from (3) above would have a docs dictionary containing mappings for docstrings for each top-level class and function defined, in addition to docstrings for each global variable.

This would not work well together with class inheritance.

In conclusion, although this proposal has great promise, it still needs work. If it's is to be done at all, better to do it right.

This could be the first true test of the PEP system; getting input from the Python user community as well as the core PythonLabs and Python-Dev groups. Other PEPs have been either after-the-fact or, in the case of those features approved for inclusion in Python 2.0, too rushed for a significant discussion.

We'll see whether this "global" approach is a good one ;-) In any case, I think it'll give more awareness of the PEP system.

Thanks for the comments,

Marc-Andre Lemburg

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