Update missing bindings script

Fix the script to work with both Python2 and Python3.
Add usage documentation.
Include the command line invocation in the report.
Some small cosmetic changes to better visualize the data on the wiki.

Change-Id: If6dc474a3c46d8212503cf206f167cc137c5fbab
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>

1 files changed, 46 insertions, 9 deletions

diff --git a/missing_bindings.py b/missing_bindings.py
index dad4624d9..00202dccf 100644
--- a/missing_bindings.py
+++ b/missing_bindings.py
@@ -37,12 +37,32 @@
 ##
 #############################################################################
 
+# This script is used to generate a summary of missing types / classes which are present in C++ Qt5,
+# but are missing in PySide2.
+#
+# Required packages: bs4
+# Installed via: pip install bs4
+#
+# The script uses beautiful soup 4 to parse out the class names from the online Qt
+# documentation. It then tries to import the types from PySide2.
+#
+# Example invocation of script:
+# python missing_bindings.py --qt-version 5.9 -w all
+# --qt-version - specify which version of qt documentation to load.
+# -w           - if PyQt5 is an installed package, check if the tested class also exists there.
+
 from __future__ import print_function
 
-import urllib2
+try:
+    import urllib.request as urllib2
+except ImportError:
+    import urllib2
+
 import argparse
 from bs4 import BeautifulSoup
 from collections import OrderedDict
+import sys
+import os.path
 
 modules_to_test = OrderedDict()
 
@@ -197,7 +217,7 @@ def create_doc_url(module_doc_page_url, version):
 parser = argparse.ArgumentParser()
 parser.add_argument("module",
                     default='all',
-                    choices=modules_to_test.keys().append('all'),
+                    choices=list(modules_to_test.keys()).append('all'),
                     nargs='?',
                     type=str,
                     help="the Qt module for which to get the missing types")
@@ -242,11 +262,13 @@ def log(*pargs, **kw):
     for arg in pargs:
         computed_str += str(arg)
 
-    style = 'code'
+    style = 'text'
     if 'style' in kw:
         style = kw['style']
 
-    if style == 'heading5':
+    if style == 'heading1':
+        computed_str = '= ' + computed_str + ' ='
+    elif style == 'heading5':
         computed_str = '===== ' + computed_str + ' ====='
     elif style == 'with_newline':
         computed_str += '\n'
@@ -265,11 +287,23 @@ def log(*pargs, **kw):
 
     print(computed_str, file=wiki_file)
 
-log('Using Qt version ' + str(args.version) + ' documentation to find public API Qt types, to test '
+log('PySide2 bindings for Qt ' + str(args.version), style='heading1')
+
+log('\nUsing Qt version ' + str(args.version) + ' documentation to find public API Qt types, to test '
                                               'if they are present in PySide2.')
-log('\nSimilar report: https://gist.github.com/ethanhs/6c626ca4e291f3682589699296377d3a \n',
+
+log('\nResults are usually stored at https://wiki.qt.io/PySide2_Missing_Bindings so consider '
+    'taking the contents of the generated missing_bindings_for_wiki_qt_io.txt file and updating '
+    'the linked wiki page.', style='end')
+
+log('\nSimilar report: https://gist.github.com/ethanhs/6c626ca4e291f3682589699296377d3a',
     style='text_with_link')
 
+python_executable = os.path.basename(sys.executable or '')
+command_line_arguments = ' '.join(sys.argv)
+log('\nThis report was generated by running the following command: '
+    + python_executable + ' ' + command_line_arguments + '\n')
+
 for module_name in modules_to_test.keys():
     log(module_name, style='heading5')
 
@@ -283,7 +317,7 @@ for module_name in modules_to_test.keys():
     except Exception as e:
         log('\nCould not load ' + pyside_package_name + '.' + module_name + '. Received error: '
             + str(e).replace("'", '')
-            + ' Skipping.\n',
+            + '. Skipping.\n',
             style='error')
         total_missing_modules_count += 1
         continue
@@ -348,15 +382,18 @@ for module_name in modules_to_test.keys():
         log('Missing types in ' + module_name + ":", style='with_newline')
         missing_types.sort()
         for missing_type in missing_types:
-            log(missing_type)
+            log(missing_type, style='code')
+        log('')
 
     log('Number of missing types: ' + str(missing_types_count), style='bold_colon')
     if len(missing_types) > 0:
         log('Number of missing types that are present in PyQt5: '
             + str(missing_types_compared_to_pyqt), style='bold_colon')
         log('End of missing types for ' + module_name + '\n', style='end')
+    else:
+        log('', style='end')
 
-log('Totals', style='heading5')
+log('Summary', style='heading5')
 log('Total number of missing types: ' + str(total_missing_types_count), style='bold_colon')
 log('Total number of missing types that are present in PyQt5: '
     + str(total_missing_types_count_compared_to_pyqt), style='bold_colon')