[PyQt] PyQt documentation where PyQt function is not same as Qt C++ function

[J Barchan]

​​
Dear PyQt developers/maintainers/documenters,

[Also cc'ed to "Florian Bruhin", as I believe you have indicated that you
are "The Man"!]

I'm getting a little peeved by the problems which arise when you seem to
have chosen to make a PyQt function differ somewhat (in return result, so
far) from the corresponding Qt C++ function, but no documentation to
explain can be found.  (This may apply only to PyQt5, not PyQt4, I don't
know.)

I was just trying to write an override in my own class for
QRegularExpression.validate().  The Qt documentation (
http://doc.qt.io/qt-5/qregularexpressionvalidator.html#validate) shows:

QValidator::State <http://doc.qt.io/qt-5/qvalidator.html#State-enum>
QRegularExpressionValidator::validate(QString
<http://doc.qt.io/qt-5/qstring.html> &*input*, int &*pos*) const
So I expect it to return a QValidator.State.  However, QtGui.pyi shows:

def validate(self, input: str, pos: int) ->
typing.Tuple[QValidator.State, str, int]: ...

So this is a tuple, with an extra str & int returned.

Apart from the fact that it's a tuple instead of a plain enum returned, I
have *no idea* what the extra str & int might be, what to do with them, etc.

Googling around, the only thing I found was
https://github.com/pycom/EricShort/blob/master/Plugins/WizardPlugins/QRegularExpressionWizard/QRegularExpressionWizardServer.py,
which shows me:

@return tuple of flag indicating validity (boolean), error string (string)
> and error offset (integer)
>

While not the same class, I hazard a guess that this tells me what the str
& int are about(?)  But without that I would have been lost if they
mattered.

Previously I have come across this issue with
QFileDialog.getOpen/SaveFileName(), which returns a tuple of the filename
*plus* some further information.  (Necessitating me to write an
"intermediate" function which just returned the filename, as this is what
the calling code expected).  This I had to track down via:

# (see https://riverbankcomputing.com/pipermail/pyqt/2014-March/033923.html,
#  http://pyqt.sourceforge.net/Docs/PyQt5/pyqt4_differences.html#qfiledialog,
#  also http://pyqt.sourceforge.net/Docs/PyQt5/gotchas.html)

If you *really* need to return different information from the C++ function
(why?  to do with overloading not working the same??), could this not be
documented somewhere reliable?  I can't find the PyQt5
QRegularExpressionValidator.validate() anywhere.  *Much* better still would
be if the function definition in the .pyi file could explain, but you'll
probably say that's auto-generated....

PyQt is great, and thank you for your efforts!  Just can anything be done
about this (I have no idea how many other cases might be like this)?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://www.riverbankcomputing.com/pipermail/pyqt/attachments/20171127/ecde1c05/attachment-0001.html>