path: root/contrib/python/Twisted/py2/twisted/words/im/basechat.py

# -*- test-case-name: twisted.words.test.test_basechat -*-
# Copyright (c) Twisted Matrix Laboratories.
# See LICENSE for details.

"""
Base classes for Instance Messenger clients.
"""

from twisted.words.im.locals import OFFLINE, ONLINE, AWAY


class ContactsList:
    """
    A GUI object that displays a contacts list.

    @ivar chatui: The GUI chat client associated with this contacts list.
    @type chatui: L{ChatUI}

    @ivar contacts: The contacts.
    @type contacts: C{dict} mapping C{str} to a L{IPerson<interfaces.IPerson>}
        provider

    @ivar onlineContacts: The contacts who are currently online (have a status
        that is not C{OFFLINE}).
    @type onlineContacts: C{dict} mapping C{str} to a
        L{IPerson<interfaces.IPerson>} provider

    @ivar clients: The signed-on clients.
    @type clients: C{list} of L{IClient<interfaces.IClient>} providers
    """
    def __init__(self, chatui):
        """
        @param chatui: The GUI chat client associated with this contacts list.
        @type chatui: L{ChatUI}
        """
        self.chatui = chatui
        self.contacts = {}
        self.onlineContacts = {}
        self.clients = []


    def setContactStatus(self, person):
        """
        Inform the user that a person's status has changed.

        @param person: The person whose status has changed.
        @type person: L{IPerson<interfaces.IPerson>} provider
        """
        if person.name not in self.contacts:
            self.contacts[person.name] = person
        if person.name not in self.onlineContacts and \
                (person.status == ONLINE or person.status == AWAY):
            self.onlineContacts[person.name] = person
        if person.name in self.onlineContacts and \
                person.status == OFFLINE:
            del self.onlineContacts[person.name]


    def registerAccountClient(self, client):
        """
        Notify the user that an account client has been signed on to.

        @param client: The client being added to your list of account clients.
        @type client: L{IClient<interfaces.IClient>} provider
        """
        if not client in self.clients:
            self.clients.append(client)


    def unregisterAccountClient(self, client):
        """
        Notify the user that an account client has been signed off or
        disconnected from.

        @param client: The client being removed from the list of account
            clients.
        @type client: L{IClient<interfaces.IClient>} provider
        """
        if client in self.clients:
            self.clients.remove(client)


    def contactChangedNick(self, person, newnick):
        """
        Update your contact information to reflect a change to a contact's
        nickname.

        @param person: The person in your contacts list whose nickname is
            changing.
        @type person: L{IPerson<interfaces.IPerson>} provider

        @param newnick: The new nickname for this person.
        @type newnick: C{str}
        """
        oldname = person.name
        if oldname in self.contacts:
            del self.contacts[oldname]
            person.name = newnick
            self.contacts[newnick] = person
            if oldname in self.onlineContacts:
                del self.onlineContacts[oldname]
                self.onlineContacts[newnick] = person



class Conversation:
    """
    A GUI window of a conversation with a specific person.

    @ivar person: The person who you're having this conversation with.
    @type person: L{IPerson<interfaces.IPerson>} provider

    @ivar chatui: The GUI chat client associated with this conversation.
    @type chatui: L{ChatUI}
    """
    def __init__(self, person, chatui):
        """
        @param person: The person who you're having this conversation with.
        @type person: L{IPerson<interfaces.IPerson>} provider

        @param chatui: The GUI chat client associated with this conversation.
        @type chatui: L{ChatUI}
        """
        self.chatui = chatui
        self.person = person


    def show(self):
        """
        Display the ConversationWindow.
        """
        raise NotImplementedError("Subclasses must implement this method")


    def hide(self):
        """
        Hide the ConversationWindow.
        """
        raise NotImplementedError("Subclasses must implement this method")


    def sendText(self, text):
        """
        Send text to the person with whom the user is conversing.

        @param text: The text to be sent.
        @type text: C{str}
        """
        self.person.sendMessage(text, None)


    def showMessage(self, text, metadata=None):
        """
        Display a message sent from the person with whom the user is conversing.

        @param text: The sent message.
        @type text: C{str}

        @param metadata: Metadata associated with this message.
        @type metadata: C{dict}
        """
        raise NotImplementedError("Subclasses must implement this method")


    def contactChangedNick(self, person, newnick):
        """
        Change a person's name.

        @param person: The person whose nickname is changing.
        @type person: L{IPerson<interfaces.IPerson>} provider

        @param newnick: The new nickname for this person.
        @type newnick: C{str}
        """
        self.person.name = newnick



class GroupConversation:
    """
    A GUI window of a conversation with a group of people.

    @ivar chatui: The GUI chat client associated with this conversation.
    @type chatui: L{ChatUI}

    @ivar group: The group of people that are having this conversation.
    @type group: L{IGroup<interfaces.IGroup>} provider

    @ivar members: The names of the people in this conversation.
    @type members: C{list} of C{str}
    """
    def __init__(self, group, chatui):
        """
        @param chatui: The GUI chat client associated with this conversation.
        @type chatui: L{ChatUI}

        @param group: The group of people that are having this conversation.
        @type group: L{IGroup<interfaces.IGroup>} provider
        """
        self.chatui = chatui
        self.group = group
        self.members = []


    def show(self):
        """
        Display the GroupConversationWindow.
        """
        raise NotImplementedError("Subclasses must implement this method")


    def hide(self):
        """
        Hide the GroupConversationWindow.
        """
        raise NotImplementedError("Subclasses must implement this method")


    def sendText(self, text):
        """
        Send text to the group.

        @param: The text to be sent.
        @type text: C{str}
        """
        self.group.sendGroupMessage(text, None)


    def showGroupMessage(self, sender, text, metadata=None):
        """
        Display to the user a message sent to this group from the given sender.

        @param sender: The person sending the message.
        @type sender: C{str}

        @param text: The sent message.
        @type text: C{str}

        @param metadata: Metadata associated with this message.
        @type metadata: C{dict}
        """
        raise NotImplementedError("Subclasses must implement this method")


    def setGroupMembers(self, members):
        """
        Set the list of members in the group.

        @param members: The names of the people that will be in this group.
        @type members: C{list} of C{str}
        """
        self.members = members


    def setTopic(self, topic, author):
        """
        Change the topic for the group conversation window and display this
        change to the user.

        @param topic: This group's topic.
        @type topic: C{str}

        @param author: The person changing the topic.
        @type author: C{str}
        """
        raise NotImplementedError("Subclasses must implement this method")


    def memberJoined(self, member):
        """
        Add the given member to the list of members in the group conversation
        and displays this to the user.

        @param member: The person joining the group conversation.
        @type member: C{str}
        """
        if not member in self.members:
            self.members.append(member)


    def memberChangedNick(self, oldnick, newnick):
        """
        Change the nickname for a member of the group conversation and displays
        this change to the user.

        @param oldnick: The old nickname.
        @type oldnick: C{str}

        @param newnick: The new nickname.
        @type newnick: C{str}
        """
        if oldnick in self.members:
            self.members.remove(oldnick)
            self.members.append(newnick)


    def memberLeft(self, member):
        """
        Delete the given member from the list of members in the group
        conversation and displays the change to the user.

        @param member: The person leaving the group conversation.
        @type member: C{str}
        """
        if member in self.members:
            self.members.remove(member)



class ChatUI:
    """
    A GUI chat client.

    @type conversations: C{dict} of L{Conversation}
    @ivar conversations: A cache of all the direct windows.

    @type groupConversations: C{dict} of L{GroupConversation}
    @ivar groupConversations: A cache of all the group windows.

    @type persons: C{dict} with keys that are a C{tuple} of (C{str},
       L{IAccount<interfaces.IAccount>} provider) and values that are
       L{IPerson<interfaces.IPerson>} provider
    @ivar persons: A cache of all the users associated with this client.

    @type groups: C{dict} with keys that are a C{tuple} of (C{str},
        L{IAccount<interfaces.IAccount>} provider) and values that are
        L{IGroup<interfaces.IGroup>} provider
    @ivar groups: A cache of all the groups associated with this client.

    @type onlineClients: C{list} of L{IClient<interfaces.IClient>} providers
    @ivar onlineClients: A list of message sources currently online.

    @type contactsList: L{ContactsList}
    @ivar contactsList: A contacts list.
    """
    def __init__(self):
        self.conversations = {}
        self.groupConversations = {}
        self.persons = {}
        self.groups = {}
        self.onlineClients = []
        self.contactsList = ContactsList(self)


    def registerAccountClient(self, client):
        """
        Notify the user that an account has been signed on to.

        @type client: L{IClient<interfaces.IClient>} provider
        @param client: The client account for the person who has just signed on.

        @rtype client: L{IClient<interfaces.IClient>} provider
        @return: The client, so that it may be used in a callback chain.
        """
        self.onlineClients.append(client)
        self.contactsList.registerAccountClient(client)
        return client


    def unregisterAccountClient(self, client):
        """
        Notify the user that an account has been signed off or disconnected.

        @type client: L{IClient<interfaces.IClient>} provider
        @param client: The client account for the person who has just signed
            off.
        """
        self.onlineClients.remove(client)
        self.contactsList.unregisterAccountClient(client)


    def getContactsList(self):
        """
        Get the contacts list associated with this chat window.

        @rtype: L{ContactsList}
        @return: The contacts list associated with this chat window.
        """
        return self.contactsList


    def getConversation(self, person, Class=Conversation, stayHidden=False):
        """
        For the given person object, return the conversation window or create
        and return a new conversation window if one does not exist.

        @type person: L{IPerson<interfaces.IPerson>} provider
        @param person: The person whose conversation window we want to get.

        @type Class: L{IConversation<interfaces.IConversation>} implementor
        @param: The kind of conversation window we want. If the conversation
            window for this person didn't already exist, create one of this type.

        @type stayHidden: C{bool}
        @param stayHidden: Whether or not the conversation window should stay
            hidden.

        @rtype: L{IConversation<interfaces.IConversation>} provider
        @return: The conversation window.
        """
        conv = self.conversations.get(person)
        if not conv:
            conv = Class(person, self)
            self.conversations[person] = conv
        if stayHidden:
            conv.hide()
        else:
            conv.show()
        return conv


    def getGroupConversation(self, group, Class=GroupConversation,
                             stayHidden=False):
        """
        For the given group object, return the group conversation window or
        create and return a new group conversation window if it doesn't exist.

        @type group: L{IGroup<interfaces.IGroup>} provider
        @param group: The group whose conversation window we want to get.

        @type Class: L{IConversation<interfaces.IConversation>} implementor
        @param: The kind of conversation window we want. If the conversation
            window for this person didn't already exist, create one of this type.

        @type stayHidden: C{bool}
        @param stayHidden: Whether or not the conversation window should stay
            hidden.

        @rtype: L{IGroupConversation<interfaces.IGroupConversation>} provider
        @return: The group conversation window.
        """
        conv = self.groupConversations.get(group)
        if not conv:
            conv = Class(group, self)
            self.groupConversations[group] = conv
        if stayHidden:
            conv.hide()
        else:
            conv.show()
        return conv


    def getPerson(self, name, client):
        """
        For the given name and account client, return an instance of a
        L{IGroup<interfaces.IPerson>} provider or create and return a new
        instance of a L{IGroup<interfaces.IPerson>} provider.

        @type name: C{str}
        @param name: The name of the person of interest.

        @type client: L{IClient<interfaces.IClient>} provider
        @param client: The client account of interest.

        @rtype: L{IPerson<interfaces.IPerson>} provider
        @return: The person with that C{name}.
        """
        account = client.account
        p = self.persons.get((name, account))
        if not p:
            p = account.getPerson(name)
            self.persons[name, account] = p
        return p


    def getGroup(self, name, client):
        """
        For the given name and account client, return an instance of a
        L{IGroup<interfaces.IGroup>} provider or create and return a new instance
        of a L{IGroup<interfaces.IGroup>} provider.

        @type name: C{str}
        @param name: The name of the group of interest.

        @type client: L{IClient<interfaces.IClient>} provider
        @param client: The client account of interest.

        @rtype: L{IGroup<interfaces.IGroup>} provider
        @return: The group with that C{name}.
        """
        # I accept 'client' instead of 'account' in my signature for
        # backwards compatibility.  (Groups changed to be Account-oriented
        # in CVS revision 1.8.)
        account = client.account
        g = self.groups.get((name, account))
        if not g:
            g = account.getGroup(name)
            self.groups[name, account] = g
        return g


    def contactChangedNick(self, person, newnick):
        """
        For the given C{person}, change the C{person}'s C{name} to C{newnick}
        and tell the contact list and any conversation windows with that
        C{person} to change as well.

        @type person: L{IPerson<interfaces.IPerson>} provider
        @param person: The person whose nickname will get changed.

        @type newnick: C{str}
        @param newnick: The new C{name} C{person} will take.
        """
        oldnick = person.name
        if (oldnick, person.account) in self.persons:
            conv = self.conversations.get(person)
            if conv:
                conv.contactChangedNick(person, newnick)
            self.contactsList.contactChangedNick(person, newnick)
            del self.persons[oldnick, person.account]
            person.name = newnick
            self.persons[person.name, person.account] = person