[PyQt] Support for Keyword Arguments

[Phil Thompson]

PyQt v4.7 will (probably) support keyword arguments. I say "probably"
because there are some issues.

Unlike with C++ the names of arguments form part of the Python API. Quite
understandably the same quality control that has been applied to the Qt C++
API hasn't been applied to the naming of arguments - there are bad names
and there are inconsistent names (though I have no feeling as to how many
are well chosen and how many are not). The point being that once a name is
used for an argument then it can't be changed later without introducing an
incompatibility. However there is no problem about adding a name to an
unnamed argument at a later date. Starting from tonight's snapshot all
arguments are unnamed. The question is - how to move to the position where
all arguments are named and those names are well chosen and consistent?

There is also an impact on the documentation. At the moment the PyQt
documentation (and the argument names it uses) is generated from the Qt .h
files. The Qt documentation is generated from the Qt .cpp files - which are
not always consistent with the .h files. However PyQt v4.7 will include
accurate docstrings for all classes, functions and methods and these should
be used to determine the name of an argument to use as a keyword. (A future
version of PyQt will have documentation generated from these docstrings so
everything will eventually match up.)

At the very least I will do some automation based on some conventions...

- all copy constructors will have unnamed arguments

- all setters (eg. setFoo()) will have a correspondingly named argument
(ie. 'foo')

- any argument that has a type derived from QEvent will be called 'event'

...suggestions for any other conventions would be very welcome.

The next question is whether to name arguments based on manual inspection -
accepting that this will take a long time (possibly forever).

Alternatively, names that aren't covered by any conventions can be
automatically taken from the Qt documentation. That risks lower quality
names but means that everything will have a name in v4.7.

I'd appreciate any thoughts on this.

Thanks,
Phil