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

[M.-A. Lemburg]

[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.]

"Tony J Ibbs (Tibs)" wrote:
> 
> Hmm. I've finally had time to have a quick look at the PEP. I can't say I'm
> too keen on the *appearance* in Python code of using string attributes in
> this manner, but that's a matter for another debate[1].
> 
> Could I request that you add to the "Caveats" section a note along the
> following lines:
> 
>         Documenting a value which has just been assigned
>         a string may be slightly confusing to someone
>         "speed reading" Python code, as:
> 
>                 a = "fred"
>                 "Smith's forename"
> 
>         has a notably different effect than the (one
>         character different)
> 
>                 a = "fred"\
>                 "Smith's forename"

A smart editor could highlight the attribute doc string in a
special way to make situations like these easily noticable, e.g.
string literals could turn out blue and doc string green.

> Obviously not a show-stopper, but I bet it will be a FAQ at some time...
> 
> (will we also get a tool to tell us when we've accidentally overwritten the
> doc string for an attribute, class, whatever? I know I'm not going to have
> time to write it...)

Not sure I follow you here... attribute docstrings can't
overwrite class/function/module docstrings due to the different
processing of the two. Attribute docstrings will only be assigned
in case they *follow* an assignment.

BTW, the PEP comes with a patch which you can try out... the
size of the patch should make it clear that this is really
only a minor addition to Python.

> [1] OK - I think I'm going to find this makes Python code less compact to
> read (I bet Eddy Welbourne will grumble, if he's still writing Python in his
> new job). Somehow I want a delimiter in there somewhere. But that's
> individual esthetics, and difficult to argue about, especially when so many
> people whose opinion I respect are jumping up and down saying this is a good
> idea.
> 
> Personally, I think this issue belongs really strongly with the issue about
> optionally declaring values - after all, that is (in some sense) what one is
> doing - one is trying to *describe* them. I would have felt happier if it
> got folded in with that (and thus the types sig DOC thread).

This is a different topic: declarations will have much more
impact on Python than what this PEP is after.

> Or is this a
> quick way to get strings attached to values so that one can get a Python2.n
> which uses those strings to hold type info without having to change the
> Python syntax? Stupid minds want to know...

The target for this is Python 2.1. At the current pace,
we should be getting there early next year.

-- 
Marc-Andre Lemburg
______________________________________________________________________
Business:                                      http://www.lemburg.com/
Python Pages:                           http://www.lemburg.com/python/