<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On 8 December 2017 at 19:28, Raymond Hettinger <span dir="ltr"><<a href="mailto:raymond.hettinger@gmail.com" target="_blank">raymond.hettinger@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span class="gmail-"><br>
</span>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.<br>
<br>
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.<br>
<span class="gmail-HOEnZb"><font color="#888888"><br></font></span></blockquote><div><br></div><div>Here are some thoughts about this:</div><div><br></div><div>1. Instance variables are given very little attention in pydoc. Consider this example:</div><div><br></div><div>>>> class C:<br>...     x: int = 1<br>...     def meth(self, y: int) -> None:<br>...         ...<br>>>> help(C)<br><br></div><div></div><div>Help on class C in module __main__:<br><br>class C(builtins.object)<br> |  Methods defined here:<br> |  <br> |  meth(self, y: int) -> None<br> |  <br> |  ----------------------------------------------------------------------<br> |  Data descriptors defined here:<br> |  <br> |  __dict__<br> |      dictionary for instance variables (if defined)<br> |  <br> |  __weakref__<br> |      list of weak references to the object (if defined)<br> |  <br> |  ----------------------------------------------------------------------<br> |  Data and other attributes defined here:<br> |  <br> |  __annotations__ = {'x': <class 'int'>}<br> |  <br> |  x = 1</div><div><br></div><div>The methods defined are listed first and are nicely formatted, while variables together with __annotations__ are</div><div>left at the very end. I think that a line like</div><div><br></div><div>x: int = 1</div><div><br></div><div>should appear for every instance variable should appear first, even before methods, since this is how people write (and read) classes.</div><div>See also <a href="https://bugs.python.org/issue28519">https://bugs.python.org/issue28519</a> for another problem with pydoc.</div><div><br></div><div>2. pydoc already extracts the signature of class from __init__ and __new__ (giving the preference to later if both are present) including</div><div>the type annotations. I think this can be kept as is, but the special constructs like NamedTuple and dataclass that auto-generate methods should</div><div>add annotations to them. For example, there is an issue to add annotations to __new__ by NamedTuple, see <a href="https://bugs.python.org/issue31006">https://bugs.python.org/issue31006</a></div><div>and <a href="https://github.com/python/typing/issues/454">https://github.com/python/typing/issues/454</a></div><div><br></div><div>--</div><div>Ivan</div><div><br></div><div><br></div></div></div></div>