gstreamer-python 1.27.90__cp313-cp313-win32.whl

gstreamer_python/Lib/site-packages/gi/_signalhelper.py

@@ -0,0 +1,249 @@
+# -*- Mode: Python; py-indent-offset: 4 -*-
+# pygobject - Python bindings for the GObject library
+# Copyright (C) 2012 Simon Feltman
+#
+#   gi/_signalhelper.py: GObject signal binding decorator object
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, see <http://www.gnu.org/licenses/>.
+
+from . import _gi
+
+
+class Signal(str):
+    """Object which gives a nice API for creating and binding signals.
+
+    :param name:
+        Name of signal or callable closure when used as a decorator.
+    :type name: str or callable
+    :param callable func:
+        Callable closure method.
+    :param GObject.SignalFlags flags:
+        Flags specifying when to run closure.
+    :param type return_type:
+        Return type of the Signal.
+    :param list arg_types:
+        List of argument types specifying the signals function signature
+    :param str doc:
+        Documentation of signal object.
+    :param callable accumulator:
+        Accumulator method with the signature:
+        func(ihint, return_accu, handler_return, accu_data) -> boolean
+    :param object accu_data:
+        User data passed to the accumulator.
+
+    :Example:
+
+    .. code-block:: python
+
+        class Spam(GObject.Object):
+            velocity = 0
+
+            @GObject.Signal
+            def pushed(self):
+                self.velocity += 1
+
+            @GObject.Signal(flags=GObject.SignalFlags.RUN_LAST)
+            def pulled(self):
+                self.velocity -= 1
+
+            stomped = GObject.Signal('stomped', arg_types=(int,))
+
+            @GObject.Signal
+            def annotated_signal(self, a:int, b:str):
+                "Python3 annotation support for parameter types.
+
+        def on_pushed(obj):
+            print(obj)
+
+        spam = Spam()
+        spam.pushed.connect(on_pushed)
+        spam.pushed.emit()
+    """
+    class BoundSignal(str):
+        """
+        Temporary binding object which can be used for connecting signals
+        without specifying the signal name string to connect.
+        """
+        def __new__(cls, name, *args, **kargs):
+            return str.__new__(cls, name)
+
+        def __init__(self, signal, gobj):
+            str.__init__(self)
+            self.signal = signal
+            self.gobj = gobj
+
+        def __repr__(self):
+            return 'BoundSignal("%s")' % self
+
+        def __call__(self, *args, **kargs):
+            """Call the signals closure."""
+            return self.signal.func(self.gobj, *args, **kargs)
+
+        def connect(self, callback, *args, **kargs):
+            """Same as GObject.Object.connect except there is no need to specify
+            the signal name."""
+            return self.gobj.connect(self, callback, *args, **kargs)
+
+        def connect_detailed(self, callback, detail, *args, **kargs):
+            """Same as GObject.Object.connect except there is no need to specify
+            the signal name. In addition concats "::<detail>" to the signal name
+            when connecting; for use with notifications like "notify" when a property
+            changes.
+            """
+            return self.gobj.connect(self + '::' + detail, callback, *args, **kargs)
+
+        def disconnect(self, handler_id):
+            """Same as GObject.Object.disconnect."""
+            self.gobj.disconnect(handler_id)
+
+        def emit(self, *args, **kargs):
+            """Same as GObject.Object.emit except there is no need to specify
+            the signal name."""
+            return self.gobj.emit(str(self), *args, **kargs)
+
+    def __new__(cls, name='', *args, **kargs):
+        if callable(name):
+            name = name.__name__
+        return str.__new__(cls, name)
+
+    def __init__(self, name='', func=None, flags=_gi.SIGNAL_RUN_FIRST,
+                 return_type=None, arg_types=None, doc='', accumulator=None, accu_data=None):
+        if func is None and callable(name):
+            func = name
+
+        if func and not doc:
+            doc = func.__doc__
+
+        str.__init__(self)
+
+        if func and not (return_type or arg_types):
+            return_type, arg_types = get_signal_annotations(func)
+        if arg_types is None:
+            arg_types = tuple()
+
+        self.func = func
+        self.flags = flags
+        self.return_type = return_type
+        self.arg_types = arg_types
+        self.__doc__ = doc
+        self.accumulator = accumulator
+        self.accu_data = accu_data
+
+    def __get__(self, instance, owner=None):
+        """Returns a BoundSignal when accessed on an object instance."""
+        if instance is None:
+            return self
+        return self.BoundSignal(self, instance)
+
+    def __call__(self, obj, *args, **kargs):
+        """Allows for instantiated Signals to be used as a decorator or calling
+        of the underlying signal method."""
+
+        # If obj is a GObject, than we call this signal as a closure otherwise
+        # it is used as a re-application of a decorator.
+        if isinstance(obj, _gi.GObject):
+            self.func(obj, *args, **kargs)
+        else:
+            # If self is already an allocated name, use it otherwise create a new named
+            # signal using the closure name as the name.
+            if str(self):
+                name = str(self)
+            else:
+                name = obj.__name__
+            # Return a new value of this type since it is based on an immutable string.
+            return type(self)(name=name, func=obj, flags=self.flags,
+                              return_type=self.return_type, arg_types=self.arg_types,
+                              doc=self.__doc__, accumulator=self.accumulator, accu_data=self.accu_data)
+
+    def copy(self, newName=None):
+        """Returns a renamed copy of the Signal."""
+
+        return type(self)(name=newName, func=self.func, flags=self.flags,
+                          return_type=self.return_type, arg_types=self.arg_types,
+                          doc=self.__doc__, accumulator=self.accumulator, accu_data=self.accu_data)
+
+    def get_signal_args(self):
+        """Returns a tuple of: (flags, return_type, arg_types, accumulator, accu_data)"""
+        return (self.flags, self.return_type, self.arg_types, self.accumulator, self.accu_data)
+
+
+class SignalOverride(Signal):
+    """Specialized sub-class of Signal which can be used as a decorator for overriding
+    existing signals on GObjects.
+
+    :Example:
+
+    .. code-block:: python
+
+        class MyWidget(Gtk.Widget):
+            @GObject.SignalOverride
+            def configure_event(self):
+                pass
+    """
+    def get_signal_args(self):
+        """Returns the string 'override'."""
+        return 'override'
+
+
+def get_signal_annotations(func):
+    """Attempt pulling python 3 function annotations off of 'func' for
+    use as a signals type information. Returns an ordered nested tuple
+    of (return_type, (arg_type1, arg_type2, ...)). If the given function
+    does not have annotations then (None, tuple()) is returned.
+    """
+    arg_types = tuple()
+    return_type = None
+
+    if hasattr(func, '__annotations__'):
+        # import inspect only when needed because it takes ~10 msec to load
+        import inspect
+        spec = inspect.getfullargspec(func)
+        arg_types = tuple(spec.annotations[arg] for arg in spec.args
+                          if arg in spec.annotations)
+        if 'return' in spec.annotations:
+            return_type = spec.annotations['return']
+
+    return return_type, arg_types
+
+
+def install_signals(cls):
+    """Adds Signal instances on a GObject derived class into the '__gsignals__'
+    dictionary to be picked up and registered as real GObject signals.
+    """
+    gsignals = cls.__dict__.get('__gsignals__', {})
+    newsignals = {}
+    for name, signal in cls.__dict__.items():
+        if isinstance(signal, Signal):
+            signalName = str(signal)
+            # Fixup a signal which is unnamed by using the class variable name.
+            # Since Signal is based on string which immutable,
+            # we must copy and replace the class variable.
+            if not signalName:
+                signalName = name
+                signal = signal.copy(name)
+                setattr(cls, name, signal)
+            if signalName in gsignals:
+                raise ValueError('Signal "%s" has already been registered.' % name)
+            newsignals[signalName] = signal
+            gsignals[signalName] = signal.get_signal_args()
+
+    cls.__gsignals__ = gsignals
+
+    # Setup signal closures by adding the specially named
+    # method to the class in the form of "do_<signal_name>".
+    for name, signal in newsignals.items():
+        if signal.func is not None:
+            funcName = 'do_' + name.replace('-', '_')
+            if not hasattr(cls, funcName):
+                setattr(cls, funcName, signal.func)

gstreamer_python/Lib/site-packages/gi/docstring.py

@@ -0,0 +1,205 @@
+# -*- Mode: Python; py-indent-offset: 4 -*-
+# vim: tabstop=4 shiftwidth=4 expandtab
+#
+# Copyright (C) 2013 Simon Feltman <sfeltman@gnome.org>
+#
+#   docstring.py: documentation string generator for gi.
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
+# USA
+
+from ._gi import \
+    VFuncInfo, \
+    FunctionInfo, \
+    CallableInfo, \
+    ObjectInfo, \
+    StructInfo, \
+    Direction, \
+    TypeTag
+
+
+#: Module storage for currently registered doc string generator function.
+_generate_doc_string_func = None
+
+
+def set_doc_string_generator(func):
+    """Set doc string generator function
+
+    :param callable func:
+        Callable which takes a GIInfoStruct and returns documentation for it.
+    """
+    global _generate_doc_string_func
+    _generate_doc_string_func = func
+
+
+def get_doc_string_generator():
+    """Returns the currently registered doc string generator."""
+    return _generate_doc_string_func
+
+
+def generate_doc_string(info):
+    """Generate a doc string given a GIInfoStruct.
+
+    :param gi.types.BaseInfo info:
+        GI info instance to generate documentation for.
+    :returns:
+        Generated documentation as a string.
+    :rtype: str
+
+    This passes the info struct to the currently registered doc string
+    generator and returns the result.
+    """
+    return _generate_doc_string_func(info)
+
+
+_type_tag_to_py_type = {TypeTag.BOOLEAN: bool,
+                        TypeTag.INT8: int,
+                        TypeTag.UINT8: int,
+                        TypeTag.INT16: int,
+                        TypeTag.UINT16: int,
+                        TypeTag.INT32: int,
+                        TypeTag.UINT32: int,
+                        TypeTag.INT64: int,
+                        TypeTag.UINT64: int,
+                        TypeTag.FLOAT: float,
+                        TypeTag.DOUBLE: float,
+                        TypeTag.GLIST: list,
+                        TypeTag.GSLIST: list,
+                        TypeTag.ARRAY: list,
+                        TypeTag.GHASH: dict,
+                        TypeTag.UTF8: str,
+                        TypeTag.FILENAME: str,
+                        TypeTag.UNICHAR: str,
+                        TypeTag.INTERFACE: None,
+                        TypeTag.GTYPE: None,
+                        TypeTag.ERROR: None,
+                        TypeTag.VOID: None,
+                        }
+
+
+def _get_pytype_hint(gi_type):
+    type_tag = gi_type.get_tag()
+    py_type = _type_tag_to_py_type.get(type_tag, None)
+
+    if py_type and hasattr(py_type, '__name__'):
+        return py_type.__name__
+    elif type_tag == TypeTag.INTERFACE:
+        iface = gi_type.get_interface()
+
+        info_name = iface.get_name()
+        if not info_name:
+            return gi_type.get_tag_as_string()
+
+        return '%s.%s' % (iface.get_namespace(), info_name)
+
+    return gi_type.get_tag_as_string()
+
+
+def _generate_callable_info_doc(info):
+    in_args_strs = []
+    if isinstance(info, VFuncInfo):
+        in_args_strs = ['self']
+    elif isinstance(info, FunctionInfo):
+        if info.is_method():
+            in_args_strs = ['self']
+
+    args = info.get_arguments()
+    hint_blacklist = ('void',)
+
+    # Build lists of indices prior to adding the docs because it is possible
+    # the index retrieved comes before input arguments being used.
+    ignore_indices = {info.get_return_type().get_array_length()}
+    user_data_indices = set()
+    for arg in args:
+        ignore_indices.add(arg.get_destroy())
+        ignore_indices.add(arg.get_type().get_array_length())
+        user_data_indices.add(arg.get_closure())
+
+    # Build input argument strings
+    for i, arg in enumerate(args):
+        if arg.get_direction() == Direction.OUT:
+            continue  # skip exclusively output args
+        if i in ignore_indices:
+            continue
+        argstr = arg.get_name()
+        hint = _get_pytype_hint(arg.get_type())
+        if hint not in hint_blacklist:
+            argstr += ':' + hint
+        if arg.may_be_null() or i in user_data_indices:
+            # allow-none or user_data from a closure
+            argstr += '=None'
+        elif arg.is_optional():
+            argstr += '=<optional>'
+        in_args_strs.append(argstr)
+    in_args_str = ', '.join(in_args_strs)
+
+    # Build return + output argument strings
+    out_args_strs = []
+    return_hint = _get_pytype_hint(info.get_return_type())
+    if not info.skip_return() and return_hint and return_hint not in hint_blacklist:
+        argstr = return_hint
+        if info.may_return_null():
+            argstr += ' or None'
+        out_args_strs.append(argstr)
+
+    for i, arg in enumerate(args):
+        if arg.get_direction() == Direction.IN:
+            continue  # skip exclusively input args
+        if i in ignore_indices:
+            continue
+        argstr = arg.get_name()
+        hint = _get_pytype_hint(arg.get_type())
+        if hint not in hint_blacklist:
+            argstr += ':' + hint
+        out_args_strs.append(argstr)
+
+    if out_args_strs:
+        return '%s(%s) -> %s' % (info.__name__, in_args_str, ', '.join(out_args_strs))
+    else:
+        return '%s(%s)' % (info.__name__, in_args_str)
+
+
+def _generate_class_info_doc(info):
+    header = '\n:Constructors:\n\n::\n\n'  # start with \n to avoid auto indent of other lines
+    doc = ''
+
+    if isinstance(info, StructInfo):
+        # Don't show default constructor for disguised (0 length) structs
+        if info.get_size() > 0:
+            doc += '    ' + info.get_name() + '()\n'
+    else:
+        doc += '    ' + info.get_name() + '(**properties)\n'
+
+    for method_info in info.get_methods():
+        if method_info.is_constructor():
+            doc += '    ' + _generate_callable_info_doc(method_info) + '\n'
+
+    if doc:
+        return header + doc
+    else:
+        return ''
+
+
+def _generate_doc_dispatch(info):
+    if isinstance(info, (ObjectInfo, StructInfo)):
+        return _generate_class_info_doc(info)
+
+    elif isinstance(info, CallableInfo):
+        return _generate_callable_info_doc(info)
+
+    return ''
+
+
+set_doc_string_generator(_generate_doc_dispatch)