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

M.-A. Lemburg mal@lemburg.com
Mon, 28 Aug 2000 19:36:06 +0200

Aahz Maruch wrote:

[p&e] In article <39AA22A0.D533598A@lemburg.com>, M.-A. Lemburg <mal@lemburg.com> wrote: > >> >>> 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. Could you provide an example explaining this? Using a dict seems like a good idea to me, too.

class A: " Base class for database "

x = "???"
" name of the database; override in subclasses ! "

y = 1
" run in auto-commit ? "

class D(A):

x = "mydb"
""" name of the attached database; note that this must support
    transactions 
"""

This will give you:

A.doc__x == " name of the database; override in subclasses ! " A.doc__y == " run in auto-commit ? " D.doc__x == """ name of the attached database; note that this must support transactions """ D.doc__y == " run in auto-commit ? "

There's no way you are going to achieve this using dictionaries.

Note: You can always build dictionaries of docstring by using the existing Python introspection features. This PEP is meant to provide the data -- not the extraction tools.

-- Marc-Andre Lemburg

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