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

[Hans-Peter Jansen]

On Montag, 27. November 2017 17:38:43 Hans-Peter Jansen wrote:
> On Montag, 27. November 2017 15:53:28 J Barchan wrote:
> > ​​
> > 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.
> This is due to the poor C++ way of dealing with multiple return values,
> while avoiding to define yet another typedef... You supply references to
> parameter values by the ampersand (&). Expect these values modified in the
> method call.
> 
> In Python, that concept translates to a tuple return value rather naturally.
> PyQt follows the pattern "return value", "1st reference value", "2nd..."
> for the returned tuple order.

QRegularExpressionValidator.validate has the ability to modify the input in 
order to make it fit. 

If the regexp matches, force the input to uppercase:

class ShortcutValidator(QRegExpValidator):
    def __init__(self, parent = None):
        regExp = QRegExp("[A-Z0-9]{0,1}", Qt.CaseInsensitive)
        super().__init__(regExp, parent)

    def validate(self, input, pos):
        result, input, pos = super().validate(input, pos)
        if result == QValidator.Acceptable:
            input = input.upper()
        return result, input, pos

pos is/can be used for QValidator.Intermediate results..

Cheers,
Pete