Guido van Rossum added the comment: On Wed, Dec 4, 2013 at 5:40 PM, Terry J. Reedy <rep...@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! ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue16669> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
