############################################################################# ## ## Copyright (C) 2020 The Qt Company Ltd. ## Contact: https://www.qt.io/licensing/ ## ## This file is part of Qt for Python. ## ## $QT_BEGIN_LICENSE:LGPL$ ## Commercial License Usage ## Licensees holding valid commercial Qt licenses may use this file in ## accordance with the commercial license agreement provided with the ## Software or, alternatively, in accordance with the terms contained in ## a written agreement between you and The Qt Company. For licensing terms ## and conditions see https://www.qt.io/terms-conditions. For further ## information use the contact form at https://www.qt.io/contact-us. ## ## GNU Lesser General Public License Usage ## Alternatively, this file may be used under the terms of the GNU Lesser ## General Public License version 3 as published by the Free Software ## Foundation and appearing in the file LICENSE.LGPL3 included in the ## packaging of this file. Please review the following information to ## ensure the GNU Lesser General Public License version 3 requirements ## will be met: https://www.gnu.org/licenses/lgpl-3.0.html. ## ## GNU General Public License Usage ## Alternatively, this file may be used under the terms of the GNU ## General Public License version 2.0 or (at your option) the GNU General ## Public license version 3 or any later version approved by the KDE Free ## Qt Foundation. The licenses are as published by the Free Software ## Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 ## included in the packaging of this file. Please review the following ## information to ensure the GNU General Public License requirements will ## be met: https://www.gnu.org/licenses/gpl-2.0.html and ## https://www.gnu.org/licenses/gpl-3.0.html. ## ## $QT_END_LICENSE$ ## ############################################################################# """ enum_sig.py Enumerate all signatures of a class. This module separates the enumeration process from the formatting. It is not easy to adhere to this protocol, but in the end, it paid off by producing a lot of clarity. """ import sys import types import inspect from shibokensupport.signature import get_signature as get_sig class ExactEnumerator(object): """ ExactEnumerator enumerates all signatures in a module as they are. This class is used for generating complete listings of all signatures. An appropriate formatter should be supplied, if printable output is desired. """ def __init__(self, formatter, result_type=dict): global EnumMeta try: # Lazy import from PySide6.QtCore import Qt EnumMeta = type(Qt.Key) except ImportError: EnumMeta = None self.fmt = formatter self.result_type = result_type self.fmt.level = 0 self.fmt.after_enum = self.after_enum self._after_enum = False self.fmt.is_method = self.is_method def is_method(self): """ Is this function a method? We check if it is a simple function. """ tp = type(self.func) return tp not in (types.BuiltinFunctionType, types.FunctionType) def after_enum(self): ret = self._after_enum self._after_enum = False def module(self, mod_name): __import__(mod_name) self.fmt.mod_name = mod_name with self.fmt.module(mod_name): module = sys.modules[mod_name] members = inspect.getmembers(module, inspect.isclass) functions = inspect.getmembers(module, inspect.isroutine) ret = self.result_type() self.fmt.class_name = None for class_name, klass in members: ret.update(self.klass(class_name, klass)) if isinstance(klass, EnumMeta): raise SystemError("implement enum instances at module level") for func_name, func in functions: ret.update(self.function(func_name, func)) return ret def klass(self, class_name, klass): ret = self.result_type() if "<" in class_name: # This is happening in QtQuick for some reason: ## class QSharedPointer: # We simply skip over this class. return ret bases_list = [] for base in klass.__bases__: name = base.__name__ if name not in ("object", "type"): name = base.__module__ + "." + name bases_list.append(name) bases_str = ', '.join(bases_list) class_str = f"{class_name}({bases_str})" # class_members = inspect.getmembers(klass) # gives us also the inherited things. class_members = sorted(list(klass.__dict__.items())) subclasses = [] functions = [] enums = [] for thing_name, thing in class_members: if inspect.isclass(thing): subclass_name = ".".join((class_name, thing_name)) subclasses.append((subclass_name, thing)) elif inspect.isroutine(thing): func_name = thing_name.split(".")[0] # remove ".overload" signature = getattr(thing, "__signature__", None) if signature is not None: functions.append((func_name, thing)) elif type(type(thing)) is EnumMeta: # take the real enum name, not what is in the dict enums.append((thing_name, type(thing).__qualname__, thing)) init_signature = getattr(klass, "__signature__", None) enums.sort(key=lambda tup: tup[1 : 3]) # sort by class then enum value self.fmt.have_body = bool(subclasses or functions or enums or init_signature) with self.fmt.klass(class_name, class_str): self.fmt.level += 1 self.fmt.class_name = class_name if hasattr(self.fmt, "enum"): # this is an optional feature for enum_name, enum_class_name, value in enums: with self.fmt.enum(enum_class_name, enum_name, int(value)): pass for subclass_name, subclass in subclasses: if klass == subclass: # this is a side effect of the typing module for Python 2.7 # via the "._gorg" property, which we can safely ignore. print(f"Warning: {class_name} points to itself via {subclass_name}, skipped!") continue ret.update(self.klass(subclass_name, subclass)) self.fmt.class_name = class_name ret.update(self.function("__init__", klass)) for func_name, func in functions: if func_name != "__init__": ret.update(self.function(func_name, func)) self.fmt.level -= 1 return ret @staticmethod def get_signature(func): return func.__signature__ def function(self, func_name, func): self.func = func # for is_method() ret = self.result_type() signature = self.get_signature(func) if signature is not None: with self.fmt.function(func_name, signature) as key: ret[key] = signature del self.func return ret def stringify(signature): if isinstance(signature, list): # remove duplicates which still sometimes occour: ret = set(stringify(sig) for sig in signature) return sorted(ret) if len(ret) > 1 else list(ret)[0] return tuple(str(pv) for pv in signature.parameters.values()) class SimplifyingEnumerator(ExactEnumerator): """ SimplifyingEnumerator enumerates all signatures in a module filtered. There are no default values, no variable names and no self parameter. Only types are present after simplification. The functions 'next' resp. '__next__' are removed to make the output identical for Python 2 and 3. An appropriate formatter should be supplied, if printable output is desired. """ def function(self, func_name, func): ret = self.result_type() signature = get_sig(func, 'existence') sig = stringify(signature) if signature is not None else None if sig is not None and func_name not in ("next", "__next__", "__div__"): with self.fmt.function(func_name, sig) as key: ret[key] = sig return ret class HintingEnumerator(ExactEnumerator): """ HintingEnumerator enumerates all signatures in a module slightly changed. This class is used for generating complete listings of all signatures for hinting stubs. Only default values are replaced by "...". """ @staticmethod def get_signature(func): return get_sig(func, "hintingstub")