[PyQt] About the automatically generated docstrings

[Phil Thompson]

On 9 Feb 2016, at 8:49 am, Elvis Stansvik <elvstone at gmail.com> wrote:
> 
> Hi all,
> 
> I'm following this PyCharm bug:
> 
>    https://youtrack.jetbrains.com/issue/PY-16818
> 
> The problem is that PyCharm is misparsing the automatically generated
> docstrings present in PyQt5 when it generates the stubs it uses for
> syntax checking, autocompletion et.c., which leads to false negatives
> in the checking and less than stellar autocompletion.
> 
> Looking at the stub generation output (which includes the original
> docstring from the PyQt5 library), one can see that PyQt5 is using a
> format for the docstrings that is slightly unorthodox:
> 
> Example from the stub for QAbstractItemModel:
> 
> def columnsMoved(self, *args, **kwargs): # real signature unknown
>    """ QAbstractItemModel.columnsMoved[QModelIndex, int, int,
> QModelIndex, int] [signal] """
>    pass
> 
> Here the docstring is using brackets ([ and ]) instead of parenthesis
> around the method signature.
> 
> And also:
> 
> def headerData(self, p_int, Qt_Orientation, int_role=None): # real
> signature unknown; restored from __doc__
>    """ QAbstractItemModel.headerData(int, Qt.Orientation, int
> role=Qt.DisplayRole) -> QVariant """
>    return QVariant
> 
> Here, for the first two parameters, the parameter name is missing. And
> PyCharm is also struggling to parse the "<type> <name>=<default>"
> convention that PyQt5 uses for the third argument.
> 
> My question is whether these formats that PyQt5 uses is used by other
> tools?

Unlikely - the format is deliberately undocumented and subject to change.

> If so, I guess it's out of the question to change it into
> something that PyCharm has an easier time parsing? If not, then maybe
> PyQt5 and PyCharm could meet halfway so to speak: PyQt5 could change
> some of the stranger formats it uses, such as the brackets around the
> signature of signals (is that a bug?) and missing parameter names, and
> PyCharm could improve its parsing algorithms to special-handle the
> other conventions that PyQt5 uses?

The next versions of PyQt4 and PyQt5 will come with PEP 484 stub files. The format of the docstrings has been changed (so far for PyQt4 only) to be a slightly more readable version of these. PyCharm should test with these stub files and report to me any problems.

Phil