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

Christian Tanzer tanzer@swing.co.at
Mon, 28 Aug 2000 08:32:17 +0200

"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 =3D 1 "attribute C.a doc-string (1)" =

b =3D 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.

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:

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.

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 =3D 2 =

def x(self): "C.x doc string" y =3D 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?

For instance,

def spam():
    a =3D 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.

Hoping-to-use-attribute-docstrings-soon ly, Christian

-- =

Christian Tanzer tanzer@swing.co.= at Glasauergasse 32 Tel: +43 1 876 62 = 36 A-1130 Vienna, Austria Fax: +43 1 877 66 = 92