urwid 2.6.0.post0__py3-none-any.whl

urwid/signals.py

@@ -0,0 +1,330 @@
+# Urwid signal dispatching
+#    Copyright (C) 2004-2012  Ian Ward
+#
+#    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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+# Urwid web site: https://urwid.org/
+
+
+from __future__ import annotations
+
+import itertools
+import typing
+import warnings
+import weakref
+
+if typing.TYPE_CHECKING:
+    from collections.abc import Callable, Collection, Container, Hashable, Iterable
+
+
+class MetaSignals(type):
+    """
+    register the list of signals in the class variable signals,
+    including signals in superclasses.
+    """
+
+    def __init__(cls, name: str, bases: tuple[type, ...], d: dict[str, typing.Any]) -> None:
+        signals = d.get("signals", [])
+        for superclass in cls.__bases__:
+            signals.extend(getattr(superclass, "signals", []))
+        signals = list(dict.fromkeys(signals).keys())
+        d["signals"] = signals
+        register_signal(cls, signals)
+        super().__init__(name, bases, d)
+
+
+def setdefaultattr(obj, name, value):
+    # like dict.setdefault() for object attributes
+    if hasattr(obj, name):
+        return getattr(obj, name)
+    setattr(obj, name, value)
+    return value
+
+
+class Key:
+    """
+    Minimal class, whose only purpose is to produce objects with a
+    unique hash
+    """
+
+    __slots__ = ()
+
+
+class Signals:
+    _signal_attr = "_urwid_signals"  # attribute to attach to signal senders
+
+    def __init__(self):
+        self._supported = {}
+
+    def register(self, sig_cls, signals: Container[Hashable]) -> None:
+        """
+        :param sig_cls: the class of an object that will be sending signals
+        :type sig_cls: class
+        :param signals: a list of signals that may be sent, typically each
+                        signal is represented by a string
+        :type signals: signal names
+
+        This function must be called for a class before connecting any
+        signal callbacks or emitting any signals from that class' objects
+        """
+        self._supported[sig_cls] = signals
+
+    def connect(
+        self,
+        obj,
+        name: Hashable,
+        callback: Callable[..., typing.Any],
+        user_arg: typing.Any = None,
+        *,
+        weak_args: Iterable[typing.Any] = (),
+        user_args: Iterable[typing.Any] = (),
+    ) -> Key:
+        """
+        :param obj: the object sending a signal
+        :type obj: object
+        :param name: the signal to listen for, typically a string
+        :type name: signal name
+        :param callback: the function to call when that signal is sent
+        :type callback: function
+        :param user_arg: deprecated additional argument to callback (appended
+                         after the arguments passed when the signal is
+                         emitted). If None no arguments will be added.
+                         Don't use this argument, use user_args instead.
+        :param weak_args: additional arguments passed to the callback
+                          (before any arguments passed when the signal
+                          is emitted and before any user_args).
+
+                          These arguments are stored as weak references
+                          (but converted back into their original value
+                          before passing them to callback) to prevent
+                          any objects referenced (indirectly) from
+                          weak_args from being kept alive just because
+                          they are referenced by this signal handler.
+
+                          Use this argument only as a keyword argument,
+                          since user_arg might be removed in the future.
+        :type weak_args: iterable
+        :param user_args: additional arguments to pass to the callback,
+                          (before any arguments passed when the signal
+                          is emitted but after any weak_args).
+
+                          Use this argument only as a keyword argument,
+                          since user_arg might be removed in the future.
+        :type user_args: iterable
+
+        When a matching signal is sent, callback will be called. The
+        arguments it receives will be the user_args passed at connect
+        time (as individual arguments) followed by all the positional
+        parameters sent with the signal.
+
+        As an example of using weak_args, consider the following snippet:
+
+        >>> import urwid
+        >>> debug = urwid.Text('')
+        >>> def handler(widget, newtext):
+        ...    debug.set_text("Edit widget changed to %s" % newtext)
+        >>> edit = urwid.Edit('')
+        >>> key = urwid.connect_signal(edit, 'change', handler)
+
+        If you now build some interface using "edit" and "debug", the
+        "debug" widget will show whatever you type in the "edit" widget.
+        However, if you remove all references to the "debug" widget, it
+        will still be kept alive by the signal handler. This because the
+        signal handler is a closure that (implicitly) references the
+        "edit" widget. If you want to allow the "debug" widget to be
+        garbage collected, you can create a "fake" or "weak" closure
+        (it's not really a closure, since it doesn't reference any
+        outside variables, so it's just a dynamic function):
+
+        >>> debug = urwid.Text('')
+        >>> def handler(weak_debug, widget, newtext):
+        ...    weak_debug.set_text("Edit widget changed to %s" % newtext)
+        >>> edit = urwid.Edit('')
+        >>> key = urwid.connect_signal(edit, 'change', handler, weak_args=[debug])
+
+        Here the weak_debug parameter in print_debug is the value passed
+        in the weak_args list to connect_signal. Note that the
+        weak_debug value passed is not a weak reference anymore, the
+        signals code transparently dereferences the weakref parameter
+        before passing it to print_debug.
+
+        Returns a key associated by this signal handler, which can be
+        used to disconnect the signal later on using
+        urwid.disconnect_signal_by_key. Alternatively, the signal
+        handler can also be disconnected by calling
+        urwid.disconnect_signal, which doesn't need this key.
+        """
+        if user_arg is not None:
+            warnings.warn(
+                "Don't use user_arg argument, use user_args instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        sig_cls = obj.__class__
+        if name not in self._supported.get(sig_cls, ()):
+            raise NameError(f"No such signal {name!r} for object {obj!r}")
+
+        # Just generate an arbitrary (but unique) key
+        key = Key()
+
+        handlers = setdefaultattr(obj, self._signal_attr, {}).setdefault(name, [])
+
+        # Remove the signal handler when any of the weakref'd arguments
+        # are garbage collected. Note that this means that the handlers
+        # dictionary can be modified _at any time_, so it should never
+        # be iterated directly (e.g. iterate only over .keys() and
+        # .items(), never over .iterkeys(), .iteritems() or the object
+        # itself).
+        # We let the callback keep a weakref to the object as well, to
+        # prevent a circular reference between the handler and the
+        # object (via the weakrefs, which keep strong references to
+        # their callbacks) from existing.
+        obj_weak = weakref.ref(obj)
+
+        def weakref_callback(weakref):  # pylint: disable=redefined-outer-name  # bad, but not changing API
+            o = obj_weak()
+            if o:
+                self.disconnect_by_key(o, name, key)
+
+        user_args = self._prepare_user_args(weak_args, user_args, weakref_callback)
+        handlers.append((key, callback, user_arg, user_args))
+
+        return key
+
+    def _prepare_user_args(
+        self,
+        weak_args: Iterable[typing.Any] = (),
+        user_args: Iterable[typing.Any] = (),
+        callback: Callable[..., typing.Any] | None = None,
+    ) -> tuple[Collection[weakref.ReferenceType], Collection[typing.Any]]:
+        # Turn weak_args into weakrefs and prepend them to user_args
+        w_args = tuple(weakref.ref(w_arg, callback) for w_arg in weak_args)
+        args = tuple(user_args) or ()
+        return (w_args, args)
+
+    def disconnect(
+        self,
+        obj,
+        name: Hashable,
+        callback: Callable[..., typing.Any],
+        user_arg: typing.Any = None,
+        *,
+        weak_args: Iterable[typing.Any] = (),
+        user_args: Iterable[typing.Any] = (),
+    ) -> None:
+        """
+        :param obj: the object to disconnect the signal from
+        :type obj: object
+        :param name: the signal to disconnect, typically a string
+        :type name: signal name
+        :param callback: the callback function passed to connect_signal
+        :type callback: function
+        :param user_arg: the user_arg parameter passed to connect_signal
+        :param weak_args: the weak_args parameter passed to connect_signal
+        :param user_args: the weak_args parameter passed to connect_signal
+
+        This function will remove a callback from the list connected
+        to a signal with connect_signal(). The arguments passed should
+        be exactly the same as those passed to connect_signal().
+
+        If the callback is not connected or already disconnected, this
+        function will simply do nothing.
+        """
+        signals = setdefaultattr(obj, self._signal_attr, {})
+        if name not in signals:
+            return None
+
+        handlers = signals[name]
+
+        # Do the same processing as in connect, so we can compare the
+        # resulting tuple.
+        user_args = self._prepare_user_args(weak_args, user_args)
+
+        # Remove the given handler
+        for h in handlers:
+            if h[1:] == (callback, user_arg, user_args):
+                return self.disconnect_by_key(obj, name, h[0])
+        return None
+
+    def disconnect_by_key(self, obj, name: Hashable, key: Key) -> None:
+        """
+        :param obj: the object to disconnect the signal from
+        :type obj: object
+        :param name: the signal to disconnect, typically a string
+        :type name: signal name
+        :param key: the key for this signal handler, as returned by
+                    connect_signal().
+        :type key: Key
+
+        This function will remove a callback from the list connected
+        to a signal with connect_signal(). The key passed should be the
+        value returned by connect_signal().
+
+        If the callback is not connected or already disconnected, this
+        function will simply do nothing.
+        """
+        handlers = setdefaultattr(obj, self._signal_attr, {}).get(name, [])
+        handlers[:] = [h for h in handlers if h[0] is not key]
+
+    def emit(self, obj, name: Hashable, *args) -> bool:
+        """
+        :param obj: the object sending a signal
+        :type obj: object
+        :param name: the signal to send, typically a string
+        :type name: signal name
+        :param args: zero or more positional arguments to pass to the signal callback functions
+
+        This function calls each of the callbacks connected to this signal
+        with the args arguments as positional parameters.
+
+        This function returns True if any of the callbacks returned True.
+        """
+        result = False
+        handlers = getattr(obj, self._signal_attr, {}).get(name, [])
+        for _key, callback, user_arg, (weak_args, user_args) in handlers:
+            result |= self._call_callback(callback, user_arg, weak_args, user_args, args)
+        return result
+
+    def _call_callback(
+        self,
+        callback,
+        user_arg: typing.Any,
+        weak_args: Collection[weakref.ReferenceType],
+        user_args: Collection[typing.Any],
+        emit_args: Iterable[typing.Any],
+    ) -> bool:
+        args_to_pass = []
+        for w_arg in weak_args:
+            real_arg = w_arg()
+            if real_arg is not None:
+                args_to_pass.append(real_arg)
+            else:
+                # de-referenced
+                return False
+
+        # The deprecated user_arg argument was added to the end
+        # instead of the beginning.
+        args = itertools.chain(args_to_pass, user_args, emit_args, (user_arg,) if user_arg is not None else ())
+
+        return bool(callback(*args))
+
+
+_signals = Signals()
+emit_signal = _signals.emit
+register_signal = _signals.register
+connect_signal = _signals.connect
+disconnect_signal = _signals.disconnect
+disconnect_signal_by_key = _signals.disconnect_by_key

urwid/split_repr.py

@@ -0,0 +1,130 @@
+# Urwid split_repr helper functions
+#    Copyright (C) 2004-2011  Ian Ward
+#
+#    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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+# Urwid web site: https://urwid.org/
+
+
+from __future__ import annotations
+
+from inspect import getfullargspec
+
+
+def split_repr(self):
+    """
+    Return a helpful description of the object using
+    self._repr_words() and self._repr_attrs() to add
+    to the description.  This function may be used by
+    adding code to your class like this:
+
+    >>> class Foo(object):
+    ...     __repr__ = split_repr
+    ...     def _repr_words(self):
+    ...         return ["words", "here"]
+    ...     def _repr_attrs(self):
+    ...         return {'attrs': "appear too"}
+    >>> Foo()
+    <Foo words here attrs='appear too'>
+    >>> class Bar(Foo):
+    ...     def _repr_words(self):
+    ...         return Foo._repr_words(self) + ["too"]
+    ...     def _repr_attrs(self):
+    ...         return dict(Foo._repr_attrs(self), barttr=42)
+    >>> Bar()
+    <Bar words here too attrs='appear too' barttr=42>
+    """
+    alist = sorted((str(k), normalize_repr(v)) for k, v in self._repr_attrs().items())
+
+    words = self._repr_words()
+    if not words and not alist:
+        # if we're just going to print the classname fall back
+        # to the previous __repr__ implementation instead
+        return super(self.__class__, self).__repr__()
+    if words and alist:
+        words.append("")
+    return f"<{self.__class__.__name__} {' '.join(words) + ' '.join([f'{k}={v}' for k, v in alist])}>"
+
+
+def normalize_repr(v):
+    """
+    Return dictionary repr sorted by keys, leave others unchanged
+
+    >>> normalize_repr({1:2,3:4,5:6,7:8})
+    '{1: 2, 3: 4, 5: 6, 7: 8}'
+    >>> normalize_repr('foo')
+    "'foo'"
+    """
+    if isinstance(v, dict):
+        items = sorted((repr(k), repr(v)) for k, v in v.items())
+
+        return f"{{{', '.join(f'{k}: {v}' for k, v in items)}}}"
+
+    return repr(v)
+
+
+def remove_defaults(d, fn):
+    """
+    Remove keys in d that are set to the default values from
+    fn.  This method is used to unclutter the _repr_attrs()
+    return value.
+
+    d will be modified by this function.
+
+    Returns d.
+
+    >>> class Foo(object):
+    ...     def __init__(self, a=1, b=2):
+    ...         self.values = a, b
+    ...     __repr__ = split_repr
+    ...     def _repr_words(self):
+    ...         return ["object"]
+    ...     def _repr_attrs(self):
+    ...         d = dict(a=self.values[0], b=self.values[1])
+    ...         return remove_defaults(d, Foo.__init__)
+    >>> Foo(42, 100)
+    <Foo object a=42 b=100>
+    >>> Foo(10, 2)
+    <Foo object a=10>
+    >>> Foo()
+    <Foo object>
+    """
+    args, varargs, varkw, defaults, _, _, _ = getfullargspec(fn)
+
+    # ignore *varargs and **kwargs
+    if varkw:
+        del args[-1]
+    if varargs:
+        del args[-1]
+
+    # create a dictionary of args with default values
+    ddict = dict(zip(args[len(args) - len(defaults) :], defaults))
+
+    for k in list(d.keys()):
+        if k in ddict and ddict[k] == d[k]:
+            # remove values that match their defaults
+            del d[k]
+
+    return d
+
+
+def _test():
+    import doctest
+
+    doctest.testmod()
+
+
+if __name__ == "__main__":
+    _test()