[PyQt] About the automatically generated docstrings

[Elvis Stansvik]

2016-02-09 10:57 GMT+01:00 Phil Thompson <phil at riverbankcomputing.com>:
> 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.

Aha, that's good news. I'll mention this in the bug report with a
reference to this conversation. I've looked a bit at the PyCharm
parsing code, and I think it will still need some polishing (to handle
"Type1 foo = Type2()" default parameter values), but that's clearly a
PyCharm bug.

We're unfortunately tied to Python 2 for the time being (waiting for
VTK 7.0 to be packaged for Debian), but should be able to switch to
Python 3 soonish (which I guess is required for PEP 484).

Thanks for the info.

Elvis

>
> Phil