view sat_frontends/quick_frontend/ @ 2845:42380a4f6433

quick frontend (app): new synchronisation mechanism: on some frontend (notably on mobiles) frontend can be paused and lose synchronisation with backend, this can also happen if backend restart a connexion without resuming using stream management. To manage that, QuickApp now has a sync attribute which is True when the backend is in sync with frontend. When synchronisation has been lost and is possible again, all widget will have their "resync" method called, which can be used to do necessary calls to update the status. It's the responsability of each widget to then reset the "sync" attribute, once everything has been resynchronised.
author Goffi <>
date Sat, 09 Mar 2019 16:33:31 +0100
parents 441b536e28ed
children 7764383a968c
line wrap: on
line source

#!/usr/bin/env python2
# -*- coding: utf-8 -*-

# helper class for making a SAT frontend
# Copyright (C) 2009-2019 Jérôme Poisson (

# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.

# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# GNU Affero General Public License for more details.

# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see <>.

from sat.core.log import getLogger

log = getLogger(__name__)
from sat.core import exceptions
from sat_frontends.quick_frontend.constants import Const as C

NEW_INSTANCE_SUFF = "_new_instance_"
classes_map = {}

    # FIXME: to be removed when an acceptable solution is here
    unicode("")  # XXX: unicode doesn't exist in pyjamas
except (
):  # Error raised is not the same depending on pyjsbuild options
    unicode = str

def register(base_cls, child_cls=None):
    """Register a child class to use by default when a base class is needed

    @param base_cls: "Quick..." base class (like QuickChat or QuickContact), must inherit from QuickWidget
    @param child_cls: inherited class to use when Quick... class is requested, must inherit from base_cls.
        Can be None if it's the base_cls itself which register
    # FIXME: we use base_cls.__name__ instead of base_cls directly because pyjamas because
    #        in the second case
    classes_map[base_cls.__name__] = child_cls

class WidgetAlreadyExistsError(Exception):

class QuickWidgetsManager(object):
    """This class is used to manage all the widgets of a frontend
    A widget can be a window, a graphical thing, or someting else depending of the frontend"""

    def __init__(self, host): = host
        self._widgets = {}

    def __iter__(self):
        """Iterate throught all widgets"""
        for widget_map in self._widgets.itervalues():
            for widget in widget_map.itervalues():
                yield widget

    def getRealClass(self, class_):
        """Return class registered for given class_

        @param class_: subclass of QuickWidget
        @return: class actually used to create widget
            # FIXME: we use base_cls.__name__ instead of base_cls directly because pyjamas bugs
            #        in the second case
            cls = classes_map[class_.__name__]
        except KeyError:
            cls = class_
        if cls is None:
            raise exceptions.InternalError(
                "There is not class registered for {}".format(class_)
        return cls

    def getRootHash(self, hash_):
        """Return root hash (i.e. hash without new instance suffix for recreated widgets

        @param hash_(immutable): hash of a widget
        @return (unicode): root hash (transtyped to unicode)
        return unicode(hash_).split(NEW_INSTANCE_SUFF)[0]

    def getWidgets(self, class_, target=None, profiles=None):
        """Get all subclassed widgets instances

        @param class_: subclass of QuickWidget, same parameter as used in [getOrCreateWidget]
        @param target: if not None, construct a hash with this target and filter corresponding widgets
            recreated widgets (with new instance suffix) are handled
        @param profiles(iterable, None): if not None, filter on instances linked to these profiles
        @return: iterator on widgets
        class_ = self.getRealClass(class_)
            widgets_map = self._widgets[class_.__name__]
        except KeyError:
            if target is not None:
                filter_hash = unicode(class_.getWidgetHash(target, profiles))
                filter_hash = None
            for w_hash, w in widgets_map.iteritems():
                if profiles is None or w.profiles.intersection(profiles):
                    if (
                        filter_hash is not None
                        and self.getRootHash(w_hash) != filter_hash
                    yield w

    def getWidget(self, class_, target=None, profiles=None):
        """Get a widget without creating it if it doesn't exist.

        @param class_: subclass of QuickWidget, same parameter as used in [getOrCreateWidget]
        @param target: target depending of the widget, usually a JID instance
        @param profiles (unicode, iterable[unicode], None): profile(s) to use (may or may not be
            used, depending of the widget class)
        @return: a class_ instance or None if the widget doesn't exist
        assert (target is not None) or (profiles is not None)
        if profiles is not None and isinstance(profiles, unicode):
            profiles = [profiles]
        class_ = self.getRealClass(class_)
        hash_ = class_.getWidgetHash(target, profiles)
            return self._widgets[class_.__name__][hash_]
        except KeyError:
            return None

    def getOrCreateWidget(self, class_, target, *args, **kwargs):
        """Get an existing widget or create a new one when necessary

        If the widget is new, will be called with it.
        @param class_(class): class of the widget to create
        @param target: target depending of the widget, usually a JID instance
        @param args(list): optional args to create a new instance of class_
        @param kwargs(dict): optional kwargs to create a new instance of class_
            if 'profile' key is present, it will be popped and put in 'profiles'
            if there is neither 'profile' nor 'profiles', None will be used for 'profiles'
            if 'on_new_widget' is present it can have the following values:
                C.WIDGET_NEW [default]: will be called on widget creation
                [callable]: this method will be called instead of
                None: do nothing
            if 'on_existing_widget' is present it can have the following values:
                C.WIDGET_KEEP  [default]: return the existing widget
                C.WIDGET_RAISE: raise WidgetAlreadyExistsError
                C.WIDGET_RECREATE: create a new widget *WITH A NEW HASH*
                    if the existing widget has a "recreateArgs" method, it will be called with args list and kwargs dict
                    so the values can be completed to create correctly the new instance
                [callable]: this method will be called with existing widget as argument
            if 'force_hash' is present, the hash given in value will be used instead of the one returned by class_.getWidgetHash
            other keys will be used to instanciate class_ if the case happen (e.g. if type_ is present and class_ is a QuickChat subclass,
                it will be used to create a new QuickChat instance).
        @return: a class_ instance, either new or already existing
        cls = self.getRealClass(class_)

        ## arguments management ##
        _args = [, target] + list(
        ) or []  # FIXME: check if it's really necessary to use optional args
        _kwargs = kwargs or {}
        if "profiles" in _kwargs and "profile" in _kwargs:
            raise ValueError(
                "You can't have 'profile' and 'profiles' keys at the same time"
            _kwargs["profiles"] = [_kwargs.pop("profile")]
        except KeyError:
            if not "profiles" in _kwargs:
                _kwargs["profiles"] = None

        # on_new_widget tells what to do for the new widget creation
            on_new_widget = _kwargs.pop("on_new_widget")
        except KeyError:
            on_new_widget = C.WIDGET_NEW

        # on_existing_widget tells what to do when the widget already exists
            on_existing_widget = _kwargs.pop("on_existing_widget")
        except KeyError:
            on_existing_widget = C.WIDGET_KEEP

        ## we get the hash ##
            hash_ = _kwargs.pop("force_hash")
        except KeyError:
            hash_ = cls.getWidgetHash(target, _kwargs["profiles"])

        ## widget creation or retrieval ##

        widgets_map = self._widgets.setdefault(
            cls.__name__, {}
        )  # we sorts widgets by classes
        if not cls.SINGLE:
            widget = None  # if the class is not SINGLE, we always create a new widget
                widget = widgets_map[hash_]
            except KeyError:
                widget = None

        if widget is None:
            # we need to create a new widget
            log.debug(u"Creating new widget for target {} {}".format(target, cls))
            widget = cls(*_args, **_kwargs)
            widgets_map[hash_] = widget

            if on_new_widget == C.WIDGET_NEW:
            elif callable(on_new_widget):
                assert on_new_widget is None
            # the widget already exists
            if on_existing_widget == C.WIDGET_KEEP:
            elif on_existing_widget == C.WIDGET_RAISE:
                raise WidgetAlreadyExistsError(hash_)
            elif on_existing_widget == C.WIDGET_RECREATE:
                # we use getOrCreateWidget to recreate the new widget
                # /!\ we use args and kwargs and not _args and _kwargs because we need the original args
                #     we need to get rid of kwargs special options
                new_kwargs = kwargs.copy()
                    )  # FIXME: we use pop instead of del here because pyjamas doesn't raise error on del
                except KeyError:
                    raise ValueError(
                        "force_hash option can't be used with on_existing_widget=RECREATE"

                new_kwargs["on_new_widget"] = on_new_widget

                # XXX: keep up-to-date if new special kwargs are added (i.e.: delete these keys here)
                new_kwargs["on_existing_widget"] = C.WIDGET_RAISE
                    recreateArgs = widget.recreateArgs
                except AttributeError:
                    recreateArgs(args, new_kwargs)
                hash_idx = 1
                while True:
                    new_kwargs["force_hash"] = "{}{}{}".format(
                        hash_, NEW_INSTANCE_SUFF, hash_idx
                        widget = self.getOrCreateWidget(
                            class_, target, *args, **new_kwargs
                    except WidgetAlreadyExistsError:
                        hash_idx += 1
                            u"Widget already exists, a new one has been recreated with hash {}".format(
            elif callable(on_existing_widget):
                raise exceptions.InternalError(
                    "Unexpected on_existing_widget value ({})".format(on_existing_widget)

        return widget

    def deleteWidget(self, widget_to_delete, *args, **kwargs):
        """Delete a widget

        this method must be called by frontends when a widget is deleted
        widget's onDelete method will be called before deletion
        @param widget_to_delete(QuickWidget): widget which need to deleted
        @param *args: extra arguments to pass to onDelete
        @param *kwargs: extra keywords arguments to pass to onDelete
            the extra arguments are not use by QuickFrontend, it's is up to
            the frontend to use them or not
        if widget_to_delete.onDelete(*args, **kwargs) == False:

        if == widget_to_delete:
   = None

        for widget_map in self._widgets.itervalues():
            to_delete = set()
            for hash_, widget in widget_map.iteritems():
                if widget_to_delete is widget:
            for hash_ in to_delete:
                del widget_map[hash_]

class QuickWidget(object):
    """generic widget base"""

    SINGLE = True  # if True, there can be only one widget per target(s)
    PROFILES_MULTIPLE = False  # If True, this widget can handle several profiles at once
    PROFILES_ALLOW_NONE = False  # If True, this widget can be used without profile

    def __init__(self, host, target, profiles=None):
        @param host: %(doc_host)s
        @param target: target specific for this widget class
        @param profiles: can be either:
            - (unicode): used when widget class manage a unique profile
            - (iterable): some widget class can manage several profiles, several at once can be specified here
            - None: no profile is managed by this widget class (rare)
        @raise: ValueError when (iterable) or None is given to profiles for a widget class which manage one unique profile.
        """ = host
        self.targets = set()
        self.profiles = set()
        if isinstance(profiles, basestring):
        elif profiles is None:
            if not self.PROFILES_ALLOW_NONE:
                raise ValueError("profiles can't have a value of None")
            for profile in profiles:
            if not self.profiles:
                raise ValueError("no profile found, use None for no profile classes")

    def profile(self):
        assert (
            len(self.profiles) == 1
            and not self.PROFILES_MULTIPLE
            and not self.PROFILES_ALLOW_NONE
        return list(self.profiles)[0]

    def addTarget(self, target):
        """Add a target if it doesn't already exists

        @param target: target to add

    def addProfile(self, profile):
        """Add a profile is if doesn't already exists

        @param profile: profile to add
        if self.profiles and not self.PROFILES_MULTIPLE:
            raise ValueError("multiple profiles are not allowed")

    def getWidgetHash(target, profiles):
        """Return the hash associated with this target for this widget class

        some widget classes can manage several target on the same instance
        (e.g.: a chat widget with multiple resources on the same bare jid),
        this method allow to return a hash associated to one or several targets
        to retrieve the good instance. For example, a widget managing JID targets,
        and all resource of the same bare jid would return the bare jid as hash.

        @param target: target to check
        @param profiles: profile(s) associated to target, see __init__ docstring
        @return: a hash (can correspond to one or many targets or profiles, depending of widget class)
        return unicode(target)  # by defaut, there is one hash for one target

    def onDelete(self, *args, **kwargs):
        """Called when a widget is being deleted

        @return (boot, None): False to cancel deletion
            all other value continue deletion
        log.debug(u"widget {} deleted".format(self))
        return True