[Python-Dev] Re: [PEP 224] Attribute Docstrings

[Christian Tanzer]

"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__<attributename>__

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

>     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