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

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

Christian Tanzer wrote:

"M.-A. Lemburg" <mal@lemburg.com> wrote: > This PEP proposes a small addition to the way Python currently > handles docstrings embedded in Python code. (snip) > Here is an example: > > class C: > "class C doc-string" > > a = 1 > "attribute C.a doc-string (1)" > > b = 2 > "attribute C.b doc-string (2)" > > The docstrings (1) and (2) are currently being ignored by the > Python byte code compiler, but could obviously be put to good use > for documenting the named assignments that precede them. > > This PEP proposes to also make use of these cases by proposing > semantics for adding their content to the objects in which they > appear under new generated attribute names. Great proposal. This would make docstrings even more useful.

Right :-)

> In order to preserve features like inheritance and hiding of > Python's special attributes (ones with leading and trailing double > underscores), a special name mangling has to be applied which > uniquely identifies the docstring as belonging to the name > assignment and allows finding the docstring later on by inspecting > the namespace. > > The following name mangling scheme achieves all of the above: > > doc_

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.

> To keep track of the last assigned name, the byte code compiler > stores this name in a variable of the compiling structure. This > variable defaults to NULL. When it sees a docstring, it then > checks the variable and uses the name as basis for the above name > mangling to produce an implicit assignment of the docstring to the > mangled name. It then resets the variable to NULL to avoid > duplicate assignments.

Normally, Python concatenates adjacent strings. It doesn't do this with docstrings. I think Python's behavior would be more consistent if docstrings were concatenated like any other strings.

Huh ? It does...

class C: ... "first line"
... "second line" ... C.doc 'first linesecond line'

And the same works for the attribute doc strings too.

> Since the implementation does not reset the compiling structure > variable when processing a non-expression, e.g. a function > definition, the last assigned name remains active until either the > next assignment or the next occurrence of a docstring. > > This can lead to cases where the docstring and assignment may be > separated by other expressions: > > class C: > "C doc string" > > b = 2 > > def x(self): > "C.x doc string" > y = 3 > return 1 > > "b's doc string" > > Since the definition of method "x" currently does not reset the > used assignment name variable, it is still valid when the compiler > reaches the docstring "b's doc string" and thus assigns the string > to doc_b.

This is rather surprising behavior. Does this mean that a string in the middle of a function definition would be interpreted as the docstring of the function?

No, since at the beginning of the function the name variable is set to NULL.

For instance,

def spam(): a = 3 "Is this spam's docstring? (not in 1.5.2)" return 1 Anyway, the behavior of Python should be the same for all kinds of docstrings. > A possible solution to this problem would be resetting the name > variable for all non-expression nodes. IMHO, David Goodger's proposal of indenting the docstring relative to the attribute it refers to is a better solution. If that requires too many changes to the parser, the name variable should be reset for all statement nodes.

See my other mail: indenting is only allowed for blocks of code and these are usually started with a colon -- doesn't work here.

-- Marc-Andre Lemburg

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