Terry J. Reedy added the comment:
Serhiy: I am not familiar with C PyStructSequence and how an instance of one
appears in Python code. I agree that more methods should have docstrings.
Guido:
1. I posted on SO the simple Py 3 solution that replaces the previously posted
wrapper solutions needed for Py 2.
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>)". 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)
...
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. 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.
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 ;-).
---
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.
If the general problem were solved, I would choose Serhiy's option B for
namedtuple.
----------
_______________________________________
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
