Implement introspection feature for PySide functions

PySide already has a quite useful introspection feature:

When you call a function with the right number of parameters, but the wrong argument types, you get a nice error display like so:

$ python3
Python 3.6.1 (default, Apr  4 2017, 09:40:21) 
[GCC 4.2.1 Compatible Apple LLVM 8.1.0 (clang-802.0.38)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from PySide2.QtWidgets import QApplication
>>> QApplication([]).palette(42)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'PySide2.QtWidgets.QApplication.palette' called with wrong argument types:
  PySide2.QtWidgets.QApplication.palette(int)
Supported signatures:
  PySide2.QtWidgets.QApplication.palette(PySide2.QtWidgets.QWidget)
  PySide2.QtWidgets.QApplication.palette()
  PySide2.QtWidgets.QApplication.palette(unicode)
>>> 

This is not bad at all, but could become much more useful.
Drawbacks:

• The signatures are only visible if you pass the (a) right number of arguments,
• the function must be called with wrong arguments,
• the function must be called at all. We would like a way to get this info without actually calling.

Based on this existing error reporting feature, we want to implement a better one which allows for a priori introspection. With such a tool, we could easily write systematic tests and catch all common and exotic functions, which would improve our product very quickly.

Some investigation has been done in order to evaluate prior work in Python that could be used here.
In Python 3, there are two introspection concepts:

• builtin_function.__text_signature__ is computed from the __doc__ string of functions. It extracts info in a special format to create this computed attribute. Unfortunately, this approach still does not support annotations which we urgently need, and it is limited to a single signature per function.
• function.__signature__ comes with much structure and is very well suited for introspection, but unfortunately
  the specification does also not provide multiple signatures per function. Also, function.__signature__ is only
  meant for Python functions, not builtin functions.

Because it is not clear what to do in this situation, also finding the best way to implement this is a part of this task.

Some open questions and considerations:

• Should signatures have true type objects as their annotation results, or should they be just strings? The question comes from those functions which are there formally, but cannot be instantiated, because they are purely abstract.
• Do we re-use the Python3 __signature__ objects for our purpose and extend them to allow them to return a sequence of signature objects? Or do we invent our own __signatures__ attribute as sequence?
• Currently, only Python3 supports signatures. But there is a re-implementation of signatures for Python2 as a module. Should we use this, or take an independent approach?
• For maximum compatibility, it is maybe not the best idea to invent something that extends Python's type system like above. We could instead build a shadow type which inherits from builtin_function and has the needed attributes freely, because such a shadow type is only used inside the introspection feature. The real function remains completely unchanged.

Literature:

• PEP 362 – Function Signature Object
• PEP 484 – Type Hints
• PEP 3107 – Function Annotations