[Python-Dev] Issues with PEP 526 Variable Notation at the class level (original) (raw)

Ivan Levkivskyi levkivskyi at gmail.com
Sat Dec 9 09:55:14 EST 2017

On 8 December 2017 at 19:28, Raymond Hettinger <raymond.hettinger at 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.

  1. 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 -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20171209/1d78db56/attachment.html>

More information about the Python-Dev mailing list