Merge remote-tracking branch 'origin/5.11' into dev

Change-Id: I302543eef74bc1f3dc6340cdfab7510a66ea1b6a

10 files changed, 325 insertions, 183 deletions

diff --git a/sources/pyside2/PySide2/QtWidgets/typesystem_widgets_common.xml b/sources/pyside2/PySide2/QtWidgets/typesystem_widgets_common.xml
index 7394b121f..9da5c71d9 100644
--- a/sources/pyside2/PySide2/QtWidgets/typesystem_widgets_common.xml
+++ b/sources/pyside2/PySide2/QtWidgets/typesystem_widgets_common.xml
@@ -405,6 +405,11 @@
     <modify-function signature="wheelEvent(QGraphicsSceneWheelEvent*)">
       <modify-argument index="1" invalidate-after-use="yes"/>
     </modify-function>
+    <modify-function signature="setGraphicsEffect(QGraphicsEffect*)">
+      <modify-argument index="1">
+        <parent index="this" action="add"/>
+      </modify-argument>
+    </modify-function>
     <!-- ### These methods are internal on Qt. -->
     <modify-function signature="supportsExtension(QGraphicsItem::Extension)const" remove="all"/>
     <modify-function signature="setExtension(QGraphicsItem::Extension,QVariant)" remove="all"/>
diff --git a/sources/pyside2/PySide2/support/signature/backport_inspect.py b/sources/pyside2/PySide2/support/signature/backport_inspect.py
index 9fed3e82e..0eafe9caa 100644
--- a/sources/pyside2/PySide2/support/signature/backport_inspect.py
+++ b/sources/pyside2/PySide2/support/signature/backport_inspect.py
@@ -88,6 +88,10 @@ PSF LICENSE AGREEMENT FOR PYTHON 3.7.0
    to be bound by the terms and conditions of this License Agreement.
 """
 
+__doc__ = """
+    signature() - get a Signature object for the callable
+"""
+
 import sys
 from collections import OrderedDict
 
diff --git a/sources/pyside2/PySide2/support/signature/loader.py b/sources/pyside2/PySide2/support/signature/loader.py
index 1827ca454..f51bafe79 100644
--- a/sources/pyside2/PySide2/support/signature/loader.py
+++ b/sources/pyside2/PySide2/support/signature/loader.py
@@ -40,13 +40,18 @@
 from __future__ import print_function, absolute_import
 
 """
+loader.py
+
+The loader has to lazy-load the signature module and also provides a few
+Python modules to support Python 2.7 .
+
 This file was originally directly embedded into the C source.
 After it grew more and more, I now prefer to have it as Python file.
-The remaining stub loader is a short string now.
+The remaining stub loader in the C source is now only a short string.
 
-The loader has to lazy-load the signature module and also provides a few
-Python modules that I consider essential and therefore built-in.
-This version does not use an embedded .zip file.
+This version does no longer use an embedded .zip file but is a package.
+The old code without a package but with zip compression can still be found
+at https://codereview.qt-project.org/#/c/203533/ for reference.
 """
 
 import sys
@@ -64,7 +69,12 @@ else:
     import inspect
     namespace = inspect.__dict__
     from PySide2.support.signature import backport_inspect as inspect
+    _doc = inspect.__doc__
     inspect.__dict__.update(namespace)
+    inspect.__doc__ += _doc
+    # force inspect to find all attributes. See "heuristic" in pydoc.py!
+    inspect.__all__ = list(x for x in dir(inspect) if not x.startswith("_"))
+
 # name used in signature.cpp
 from PySide2.support.signature.parser import pyside_type_init
 sys.path.pop(0)
diff --git a/sources/pyside2/PySide2/support/signature/mapping.py b/sources/pyside2/PySide2/support/signature/mapping.py
index 7151af8bb..dd3df0988 100644
--- a/sources/pyside2/PySide2/support/signature/mapping.py
+++ b/sources/pyside2/PySide2/support/signature/mapping.py
@@ -40,7 +40,7 @@
 from __future__ import print_function, absolute_import
 
 """
-signature_mapping.py
+mapping.py
 
 This module has the mapping from the pyside C-modules view of signatures
 to the Python representation.
diff --git a/sources/pyside2/PySide2/support/signature/parser.py b/sources/pyside2/PySide2/support/signature/parser.py
index eb6453d3e..9313fb540 100644
--- a/sources/pyside2/PySide2/support/signature/parser.py
+++ b/sources/pyside2/PySide2/support/signature/parser.py
@@ -49,21 +49,24 @@ from .mapping import type_map, update_mapping, __dict__ as namespace
 
 _DEBUG = False
 
-TYPE_MAP_DOC = """
-    The type_map variable is central for the signature package.
+"""
+parser.py
+
+This module parses the signature text and creates properties for the
+signature objects.
 
-    PySide has a new function 'CppGenerator::writeSignatureInfo()'
-    that extracts the gathered information about the function arguments
-    and defaults as good as it can. But what PySide generates is still
-    very C-ish and has many constants that Python doesn't understand.
+PySide has a new function 'CppGenerator::writeSignatureInfo()'
+that extracts the gathered information about the function arguments
+and defaults as good as it can. But what PySide generates is still
+very C-ish and has many constants that Python doesn't understand.
 
-    The function 'try_to_guess()' below understands a lot of PySide's
-    peculiar way to assume local context. If it is able to do the guess,
-    then the result is inserted into the dict, so the search happens
-    not again. For everything that is not covered by these automatic
-    guesses, we provide an entry in 'type_map' that resolves it.
+The function 'try_to_guess()' below understands a lot of PySide's
+peculiar way to assume local context. If it is able to do the guess,
+then the result is inserted into the dict, so the search happens
+not again. For everything that is not covered by these automatic
+guesses, we provide an entry in 'type_map' that resolves it.
 
-    In effect, 'type_map' maps text to real Python objects.
+In effect, 'type_map' maps text to real Python objects.
 """
 
 def dprint(*args, **kw):
diff --git a/sources/pyside2/tests/QtWidgets/CMakeLists.txt b/sources/pyside2/tests/QtWidgets/CMakeLists.txt
index 36f1ba80a..6d8645918 100644
--- a/sources/pyside2/tests/QtWidgets/CMakeLists.txt
+++ b/sources/pyside2/tests/QtWidgets/CMakeLists.txt
@@ -134,6 +134,7 @@ PYSIDE_TEST(qwidget_setlayout_test.py)
 PYSIDE_TEST(qwidget_test.py)
 PYSIDE_TEST(qcolormap_test.py)
 PYSIDE_TEST(reference_count_test.py)
+PYSIDE_TEST(signature_test.py)
 PYSIDE_TEST(standardpixmap_test.py)
 PYSIDE_TEST(test_module_template.py)
 PYSIDE_TEST(virtual_protected_inheritance_test.py)
diff --git a/sources/pyside2/tests/registry/signature_test.py b/sources/pyside2/tests/QtWidgets/signature_test.py
index ae5b9381e..15a9333b4 100644
--- a/sources/pyside2/tests/registry/signature_test.py
+++ b/sources/pyside2/tests/QtWidgets/signature_test.py
@@ -39,97 +39,13 @@
 
 from __future__ import print_function, absolute_import
 
-import sys
-import os
 import unittest
-from collections import OrderedDict
-from pprint import pprint
-from util import isolate_warnings, check_warnings
-import PySide2
-
-"""
-This test shows that we have over 14500 signatures,
-and that they all can be created.
-"""
-
-all_modules = list("PySide2." + x for x in PySide2.__all__)
-
-from PySide2.support.signature import parser, inspect
-
-_do_print = (True if os.isatty(sys.stdout.fileno()) or "-v" in sys.argv
-             else False)
-
-def dprint(*args, **kw):
-    if _do_print:
-        print(*args, **kw)
-
-def enum_module(mod_name):
-    __import__(mod_name)
-    count = 0
-    module = sys.modules[mod_name]
-    dprint()
-    dprint("Module", mod_name)
-    members = inspect.getmembers(module, inspect.isclass)
-    for class_name, klass in members:
-        signature = getattr(klass, '__signature__', None)
-        dprint()
-        # class_members = inspect.getmembers(klass)
-        # gives us also the inherited things.
-        dprint("  class {}:".format(class_name))
-        if signature is None:
-            pass # initialization not called?
-        elif isinstance(signature, list):
-            dprint("    with overloading():")
-            for overload in signature:
-                dprint("      def __init__" + str(overload))
-        else:
-            dprint("    def __init__" + str(signature))
-        count += 1
-        have_sig = signature is not None
-        have_members = 0
-        class_members = sorted(list(klass.__dict__.items()))
-        for func_name, func in class_members:
-            signature = getattr(func, '__signature__', None)
-            if signature is not None:
-                if isinstance(signature, list):
-                    dprint("    with overloading():")
-                    for overload in signature:
-                        dprint("      def", func_name + str(overload))
-                else:
-                    dprint("    def", func_name + str(signature))
-                count += 1
-                have_members = count
-        if not have_sig and not have_members:
-            # print at least "pass"
-            dprint("    pass")
-    return count
-
-def enum_all():
-    result = OrderedDict()
-    total = 0
-    for mod_name in all_modules:
-        result[mod_name] = enum_module(mod_name)
-        total += result[mod_name]
-    pprint(result if sys.version_info >= (3,) else list(result.items()),
-           stream=sys.stderr)
-    print("Total", total, file=sys.stderr)
-    return result
+import PySide2.QtCore
+import PySide2.QtWidgets
+from PySide2.support.signature import inspect
 
 
 class PySideSignatureTest(unittest.TestCase):
-    def testAllSignaturesCanBuild(self):
-        with isolate_warnings():
-            # This test touches all attributes
-            result = enum_all()
-            # We omit the number of functions test.
-            # That is replaced by existence_test.py .
-            for mod_name, count in result.items():
-                pass
-            # If an attribute could not be computed, then we will have a warning
-            # in the warningregistry.
-            if check_warnings():
-                raise RuntimeError("There are errors, see above.")
-
     def testSignatureExist(self):
         t1 = type(PySide2.QtCore.QObject.children.__signature__)
         self.assertEqual(t1, inspect.Signature)
@@ -158,7 +74,7 @@ class PySideSignatureTest(unittest.TestCase):
         self.assertTrue(ob1 is ob2)
 
     def testModuleIsInitialized(self):
-        assert PySide2.QtWidgets.QApplication.__signature__ is not None
+        self.assertTrue(PySide2.QtWidgets.QApplication.__signature__ is not None)
 
     def test_NotCalled_is_callable_and_correct(self):
         # A signature that has a default value with some "Default(...)"
diff --git a/sources/pyside2/tests/registry/CMakeLists.txt b/sources/pyside2/tests/registry/CMakeLists.txt
index 210219cb2..df50037e1 100644
--- a/sources/pyside2/tests/registry/CMakeLists.txt
+++ b/sources/pyside2/tests/registry/CMakeLists.txt
@@ -37,5 +37,4 @@
 ##
 #############################################################################
 
-PYSIDE_TEST(signature_test.py)
 PYSIDE_TEST(existence_test.py)
diff --git a/sources/shiboken2/libshiboken/signature.cpp b/sources/shiboken2/libshiboken/signature.cpp
index df49a4d29..f0bb8e609 100644
--- a/sources/shiboken2/libshiboken/signature.cpp
+++ b/sources/shiboken2/libshiboken/signature.cpp
@@ -42,77 +42,13 @@
 extern "C"
 {
 
-/***************************************************************************
- ***************************************************************************
-
-
- The signature C extension
- =========================
-
- This module is a C extension for CPython 3.4 and up, and CPython 2.7.
- It's purpose is to provide support for the __signature__ attribute
- of builtin PyCFunction objects.
-
-
- Short excursion on the topic
- ----------------------------
-
- Beginning with CPython 3.5, Python functions began to grow a __signature__
- attribute for normal Python functions. This is totally optional and just
- a nice-to-have feature in Python.
-
- PySide, on the other hand, could use __signature__ very much, because the
- typing info for the 14000+ PySide functions is really missing, and it
- would be nice to have this info available directly in Python.
-
-
- How this code works
- -------------------
-
- The basic idea is to create a dummy Python function and to use the inspect
- module to create a signature object. Then, this object is returned as the
- result of the __signature__ attribute of the real PyCFunction.
-
- There is one thing that really changes Python a bit:
-
-     I added the __signature__ attribute to every function.
-
- That is a little change to Python that does not harm, but it saves us
- tons of code, that was needed in the former versions.
-
- The internal work is done in two steps:
- All functions get their "signature text" when the module is imported.
- The actual signature is created later, when the attribute is really used.
-
- Example:
-
- The PyCFunction 'QtWidgets.QApplication.palette' is interrogated for its
- signature. That means 'pyside_sm_get___signature__()' is called.
- It calls GetSignature_Function which returns the signature if it is found.
-
- There are actually 2 locations where late initialization occurs:
- -  'dict' can be no dict but a tuple. That is the argument tuple that
-    was saved by 'PySide_BuildSignatureArgs' at module load time.
-    If so, then 'pyside_type_init' in 'signature.py' will be called,
-    which parses the string and creates the dict.
- -  'props' can be empty. Then 'create_signature' in 'signature_loader.py'
-    is called, which uses a dummy function to produce a signature instance
-    with the inspect module.
-
- This module is dedicated to our lovebird "Püppi", who died on 2017-09-15.
-
- ****************************************************************************
- ****************************************************************************/
+/*
+ * The documentation is located in file signature_doc.rst
+ */
 
 #include "signature.h"
 #include <structmember.h>
 
-#define EXTENSION_ENABLED \
-    PY_VERSION_HEX >= 0x03040000 || \
-    (PY_VERSION_HEX < 0x03000000 && PY_VERSION_HEX >= 0x02070000)
-
-#if EXTENSION_ENABLED
-
 // These constants were needed in former versions of the module:
 #define PYTHON_HAS_QUALNAME             (PY_VERSION_HEX >= 0x03030000)
 #define PYTHON_HAS_UNICODE              (PY_VERSION_HEX >= 0x03000000)
@@ -697,20 +633,14 @@ PySide_BuildSignatureProps(PyObject *classmod)
     return dict;
 }
 
-#endif // EXTENSION_ENABLED
-
 int
 SbkSpecial_Type_Ready(PyObject *module, PyTypeObject *type,
                       const char *signatures)
 {
     int ret;
-#if EXTENSION_ENABLED
     if (PySideType_Ready(type) < 0)
         return -1;
     ret = PySide_BuildSignatureArgs(module, (PyObject *)type, signatures);
-#else
-    ret = PyType_Ready(type);
-#endif
     if (ret < 0) {
         PyErr_Print();
         PyErr_SetNone(PyExc_ImportError);
@@ -718,7 +648,6 @@ SbkSpecial_Type_Ready(PyObject *module, PyTypeObject *type,
     return ret;
 }
 
-#if EXTENSION_ENABLED
 static int
 PySide_FinishSignatures(PyObject *module, const char *signatures)
 {
@@ -765,17 +694,14 @@ PySide_FinishSignatures(PyObject *module, const char *signatures)
     }
     return 0;
 }
-#endif // EXTENSION_ENABLED
 
 void
 FinishSignatureInitialization(PyObject *module, const char *signatures)
 {
-#if EXTENSION_ENABLED
     if (PySide_FinishSignatures(module, signatures) < 0) {
         PyErr_Print();
         PyErr_SetNone(PyExc_ImportError);
     }
-#endif
 }
 
 } //extern "C"
diff --git a/sources/shiboken2/libshiboken/signature_doc.rst b/sources/shiboken2/libshiboken/signature_doc.rst
new file mode 100644
index 000000000..5ad2ebd80
--- /dev/null
+++ b/sources/shiboken2/libshiboken/signature_doc.rst
@@ -0,0 +1,278 @@
+*************************
+The signature C extension
+*************************
+
+This module is a C extension for CPython 3.5 and up, and CPython 2.7.
+Its purpose is to provide support for the ``__signature__`` attribute
+of builtin PyCFunction objects.
+
+
+Short Introduction to the Topic
+===============================
+
+Beginning with CPython 3.5, Python functions began to grow a ``__signature__``
+attribute for normal Python functions. This is totally optional and just
+a nice-to-have feature in Python.
+
+PySide, on the other hand, could use ``__signature__`` very much, because the
+typing info for the 15000+ PySide functions is really missing, and it
+would be nice to have this info directly available.
+
+
+The Idea to Support Signatures
+==============================
+
+We want to have an additional ``__signature__`` attribute in all PySide
+methods, without changing lots of generated code.
+Therefore, we did not change any of the existing data structures,
+but supported the new attribute by a global dictionary.
+
+When the ``__signature__`` property is requested, a method is called that
+does a lookup in the global dict. This is a flexible approach with little impact
+to the rest of the project. It has very limited overhead compared to direct
+attribute access, but for the need of a signature access from time to time,
+this is an adequate compromise.
+
+
+How this Code Works
+-------------------
+
+Signatures are supported for regular Python functions, only. Creating signatures
+for ``PyCFunction`` objects would require quite some extra effort in Python.
+
+Fortunately, we found this special *stealth* technique, that saves us most of the
+needed effort:
+
+The basic idea is to create a dummy Python function with **varnames**, **defaults**
+and **annotations** properties, and then to use the inspect
+module to create a signature object. This object is returned as the computed
+result of the ``__signature__`` attribute of the real ``PyCFunction`` object.
+
+There is one thing that really changes Python a bit:
+
+*   I added the ``__signature__`` attribute to every function.
+
+That is a little change to Python that does not harm, but it saves us
+tons of code, that was needed in the early versions of the module.
+
+The internal work is done in two steps:
+
+*   All functions of a class get the *signature text* when the module is imported.
+    This is only a very small overhead added to the startup time. It is a single
+    string for the whole class.
+*   The actual signature object is created later, when the attribute is really
+    accessed. Signatures are cached and only created on first access.
+
+Example:
+
+The ``PyCFunction`` ``QtWidgets.QApplication.palette`` is interrogated for its
+signature. That means ``pyside_sm_get___signature__()`` is called.
+It calls ``GetSignature_Function`` which returns the signature if it is found.
+
+
+Why this Code is Fast
+---------------------
+
+It costs a little time (maybe 4 seconds) to run througs every single signature
+object, since these are more than 15000 Python objects. But all the signature
+objects will be rarely accessed but in special applications.
+The normal case are only a few accesses, and these work pretty fast.
+
+The key to make this signature module fast is to avoid computation as much as
+possible. When no signature objects are used, then no time is lost in initialization.
+When it comes to signature usage, then late initialization is used and cached.
+This technique is also known as *full laziness* in haskell.
+
+There are actually two locations where late initialization occurs:
+
+*   ``dict`` can be no dict but a tuple. That is the initial argument tuple that
+    was saved by ``PySide_BuildSignatureArgs`` at module load time.
+    If so, then ``pyside_type_init`` in parser.py will be called,
+    which parses the string and creates the dict.
+*   ``props`` can be empty. Then ``create_signature`` in loader.py
+    is called, which uses a dummy function to produce a signature instance
+    with the inspect module.
+
+The initialization that is always done is just two dictionary writes
+per class, and we have about 1000 classes.
+To measure the additional overhead, we have simulated what happens
+when ``from PySide2 import *`` is performed.
+It turned out that the overhead is below 0.5 ms.
+
+
+The Signature Package Structure
+-------------------------------
+
+The C++ code involved with the signature module is completely in the file
+shiboken2/libshiboken/signature.cpp . All other functionality is implemented in
+the ``signature`` Python package. It has the following structure::
+
+    pyside2/PySide2/support/signature/__init__.py
+                                      loader.py
+                                      parser.py
+                                      mapping.py
+                                      typing27.py
+                                      backport_inspect.py
+
+Really important are the **parser**, **mapping** and **loader** modules. The rest is
+needed to create Python 2 compatibility.
+
+
+loader.py
+~~~~~~~~~
+
+This module assembles and imports the ``inspect`` module, and then exports the
+``create_signature`` function. This function takes a fake function and some
+attributes and builds a ``__signature__`` object with the inspect module.
+
+
+parser.py
+~~~~~~~~~
+
+This module takes a class signatures string from C++ and parses it into the
+needed properties for the ``create_signature`` function. Its entry point is the
+``pyside_type_init`` function, which is called from the C module via ``loader.py``.
+
+
+mapping.py
+~~~~~~~~~~
+
+The purpose of the mapping module is maintaining a list of replacement strings
+that map from the *signature text* in C to the property strings that Python
+needs. A lot of mappings are resolved by rather complex expressions in ``parser.py``,
+but a few hundred cases are better to spell explicitly, here.
+
+
+*typing27.py*
+~~~~~~~~~~~~~
+
+Python 2 has no typing module at all. This is a backport of the minimum that is needed.
+
+
+*backport_inspect.py*
+~~~~~~~~~~~~~~~~~~~~~
+
+Python 2 has an inspect module, but lacks the signature functions, completely.
+This module adds the missing functionality, which is merged at runtime into
+the inspect module.
+
+
+Multiple Arities
+----------------
+
+One aspect that was ignored so far was *multiple arities*: How to handle it when
+a function has more than one signature?
+
+I did not find any note on how multiple signatures should be treated in Python,
+but this simple rules seem to work well:
+
+*   If there is a list, then it is a multi-signature.
+*   Otherwise, it is a simple signature.
+
+
+Impacts of The Signature Module
+===============================
+
+The signature module has a number of impacts to other PySide modules, which were
+created as a consequence of its existence, and there will be a few more in the
+future:
+
+
+existence_test.py
+-----------------
+
+The file ``pyside2/tests/registry/existence_test.py`` was written using the
+signatures from the signatures module. The idea is that there are some 15000
+functions with a certain signature.
+
+These functions should not get lost by some bad check-in. Therefore, a list
+of all existing signatures is kept as a module that assembles a
+dictionary. The function existence is checked, and also the exact arity.
+
+This module exists for every PySide release and every platform. The initial
+module is generated once and saved as ``exists_{plat}_{version}.py``.
+
+An error is normally only reported as a warning, but:
+
+
+Interaction With The Coin Module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When this test program is run in COIN, then the warnings are turned into
+errors. The reason is that only in COIN, we have a stable configuration
+of PySide modules that can reliably be compared.
+
+These modules have the name ``exists_{plat}_{version}_ci.py``, and as a big
+exception for generated code, these files are *intentionally* checked in.
+
+
+What Happens When a List is Missing?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a new version of PySide gets created, then the existence test files
+initially do not exist.
+
+When a COIN test is run, then it will complain about the error and create
+the missing module on standard output.
+But since COIN tests are run multiple times, the output that was generated
+by the first test will still exist at the subsequent runs.
+(If COIN was properly implemented, we could not take that advantage and
+would need to implement that as an extra exception.)
+
+As a result, a missing module will be reported as a test which partially
+succeeded (called "FLAKY"). To avoid further flaky tests and to activate as a real test,
+we can now capture the error output of COIN and check the generated module
+in.
+
+
+init_platform.py
+~~~~~~~~~~~~~~~~
+
+For generating the ``exists_{plat}_{version}.py`` modules, the module
+``pyside2/tests/registry/init_platform.py`` was written. It can be used
+standalone from the commandline, to check the compatibility of some
+changes, directly.
+
+
+generate_pyi.py
+---------------
+
+``pyside2/PySide2/support/generate_pyi.py`` is still under development.
+This module generates so-called hinting stubs for integration of PySide
+with diverse *Python IDEs*.
+
+Although this module creates the stubs as an add-on, the
+impact on the quality of the signature module is considerable:
+
+The module must create syntactically correct ``.pyi`` files which contain
+not only signatures but also constants and enums of all PySide modules.
+This serves as an extra challenge that has a very positive effect on
+the completeness and correctness of signatures.
+
+
+Future Extension
+----------------
+
+Before the signature module was written, there already existed the concept of
+signatures, but in a more C++ - centric way. From that time, there still exist
+the error messages, which are created when a function gets wrong argument types.
+
+These error messages should be replaced by text generated on demand by
+the signature module, in order to be more consistent and correct.
+
+Additionally, the ``__doc__`` attribute of PySide methods is not set, yet.
+It would be easy to get a nice ``help()`` feature by creating signatures
+as default content for docstrings.
+
+
+Literature
+==========
+
+    `PEP 362 – Function Signature Object <https://www.python.org/dev/peps/pep-0362/>`__
+
+    `PEP 484 – Type Hints <https://www.python.org/dev/peps/pep-0484/>`__
+
+    `PEP 3107 – Function Annotations <https://www.python.org/dev/peps/pep-3107/>`__
+
+
+*Personal Remark: This module is dedicated to our lovebird "Püppi", who died on 2017-09-15.*