On Wed, Dec 4, 2013 at 5:40 PM, Terry J. Reedy <report@bugs.python.org> wrote:
> 1. I posted on SO the simple Py 3 solution that replaces the previously posted wrapper solutions needed for Py 2.

Thanks, that will give people some pointers for Python 3. We need
folks to upvote it. :-)

> 2. Much of what you do not like is standard Sphinx/help behavior that would be unchanged by Serhiy's patch. The first line for a class is always "class <classname>(<base_classes>)".

Maybe for help(), but the Sphinx docs look better for most classes.
Compare my screen capture with the first class on this page:
https://www.dropbox.com/static/developers/dropbox-python-sdk-1.6-docs/index.html
The screen capture looks roughly like this (note this is two lines and
the word DatastoreInfo is repeated -- that wasn't line folding):

class dropbox.datastore.DatastoreInfo
    DatastoreInfo(id, handle, rev, title, mtime)

whereas for non-namedtuple classes it looks like this:

class dropbox.client.DropboxClient(oauth2_access_token, locale=None,
rest_client=None)¶

I understand that part of this is due to the latter class having an
__init__ with a reasonable docstring, but the fact remains that
namedtuple's default docstring produces poorly-looking documentation.

> The first line is followed by the docstring, so the class name is repeated if and only if it is repeated in the docstring (as for list, see below). The __new__/__init__ signature is given here if and only it is in the docstring. Otherwise, one has to look down for the method. The method signatures are never on the first line. Examples:
>
>>>> help(list)
> Help on class list in module builtins:
>
> class list(object)
>  |  list() -> new empty list
>  |  list(iterable) -> new list initialized from iterable's items
> ...
>>>> class C:
>         "doc string"
>         def __init__(self, a, b): pass
>
>>>> help(C)
> Help on class C in module __main__:
>
> class C(builtins.object)
>  |  doc string
>  |
>  |  Methods defined here:
>  |
>  |  __init__(self, a, b)
> ...

Yeah, help() is different than Sphinx. (As a general remark I find the
help() output way too verbose with its endless listing of all the
built-in behaviors.)

> 3. ?? Python 3 has many improvements and we will add more.
> ---
>
> I am still of the opinion that property usage should be a mostly transparent implementation detail.

What does that mean?

> Point classes could have 4 instance attributes: x, y, r, and theta, with a particular implementation using 0 to 4 properties.  All attributes should be documented regardless of the number of properties, which currently means listing them in the class docstring. A library could have more than one than one implementation.

For various reasons (like consistency with other classes) I *really*
want the property docstrings on the individual properties, not in the
class docstring. Here's a screenshot of what I want:

https://www.dropbox.com/s/70zfapz8pcz9476/Screenshot%202013-12-04%2019.57.36.png

I obtained this by abandoning the namedtuple and hand-coding
properties -- the resulting class uses 4 lines (+ 1 blank) of
boilerplate per property instead of just one line of docstring per
property.

>
> As for named tuples, I believe (without trying) that the name to index mapping could be done with __gettattr__ and a separate dict. If so, there would be no property docstrings and hence no field docstrings to worry about ;-).

I'm not sure what you are proposing here -- a patch to namedtuple or a
work-around? I think namedtuple is too valuable to abandon. It not
only saves a lot of code, it captures the regularity of the code. (If
I have a class with 5 similar-looking methods it's easy to overlook a
subtle difference in one of them.)

> ---
>
> There have been requests for data attribute docstrings (without the bother and inefficiency of replacing a simple attribute with a property). Since such a docstring would have to be attached to the fixed attribute name, rather than the variable attribute value, I believe a string subclass would suffice, to be used as needed. The main problem is a decent syntax to add a docstring to a simple (assignment) statement.

Sphinx actually has a syntax for this already. In fact, it has three:
it allwos a comment before or on the class variable starting with
"#:", or a docstring immediately following. Check out this
documentation for the autodoc extension:
http://sphinx-doc.org/ext/autodoc.html#directive-autoattribute

> If the general problem were solved, I would choose Serhiy's option B for namedtuple.

If you're referring to this:

    Point = namedtuple('Point', [('x', 'absciss'), ('y', 'ordinate')],
                       doc='Point: 2-dimensional coordinate')

I'd love it!