On 8 December 2017 at 19:28, Raymond Hettinger <raymond.hettin...@gmail.com>
wrote:
>
> I'm hoping the typing experts will chime in here. The question is
> straight-forward. Where should we look for the signature and docstring for
> constructing instances? Should they be attached to the class, to
> __init__(), or to __new__() when it used.
>
> It would be nice to have an official position on that before, it gets set
> in stone through arbitrary choices made by pycharm, pydoc, mypy,
> typing.NamedTuple, and dataclasses.dataclass.
>
>
Here are some thoughts about this:
1. Instance variables are given very little attention in pydoc. Consider
this example:
>>> class C:
... x: int = 1
... def meth(self, y: int) -> None:
... ...
>>> help(C)
Help on class C in module __main__:
class C(builtins.object)
| Methods defined here:
|
| meth(self, y: int) -> None
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'x': <class 'int'>}
|
| x = 1
The methods defined are listed first and are nicely formatted, while
variables together with __annotations__ are
left at the very end. I think that a line like
x: int = 1
should appear for every instance variable should appear first, even before
methods, since this is how people write (and read) classes.
See also https://bugs.python.org/issue28519 for another problem with pydoc.
2. pydoc already extracts the signature of class from __init__ and __new__
(giving the preference to later if both are present) including
the type annotations. I think this can be kept as is, but the special
constructs like NamedTuple and dataclass that auto-generate methods should
add annotations to them. For example, there is an issue to add annotations
to __new__ by NamedTuple, see https://bugs.python.org/issue31006
and https://github.com/python/typing/issues/454
--
Ivan
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
