| # -*- Python -*- |
| # Copyright (c) 2008 Twisted Matrix Laboratories. |
| # See LICENSE for details. |
| |
| """ |
| Pan-protocol chat client. |
| """ |
| |
| from zope.interface import Interface, Attribute |
| |
| from twisted.words.im import locals |
| |
| # (Random musings, may not reflect on current state of code:) |
| # |
| # Accounts have Protocol components (clients) |
| # Persons have Conversation components |
| # Groups have GroupConversation components |
| # Persons and Groups are associated with specific Accounts |
| # At run-time, Clients/Accounts are slaved to a User Interface |
| # (Note: User may be a bot, so don't assume all UIs are built on gui toolkits) |
| |
| |
| class IAccount(Interface): |
| """ |
| I represent a user's account with a chat service. |
| """ |
| |
| client = Attribute('The L{IClient} currently connecting to this account, if any.') |
| gatewayType = Attribute('A C{str} that identifies the protocol used by this account.') |
| |
| def __init__(accountName, autoLogin, username, password, host, port): |
| """ |
| @type accountName: string |
| @param accountName: A name to refer to the account by locally. |
| @type autoLogin: boolean |
| @type username: string |
| @type password: string |
| @type host: string |
| @type port: integer |
| """ |
| |
| def isOnline(): |
| """ |
| Am I online? |
| |
| @rtype: boolean |
| """ |
| |
| def logOn(chatui): |
| """ |
| Go on-line. |
| |
| @type chatui: Implementor of C{IChatUI} |
| |
| @rtype: L{Deferred} L{Client} |
| """ |
| |
| def logOff(): |
| """ |
| Sign off. |
| """ |
| |
| def getGroup(groupName): |
| """ |
| @rtype: L{Group<IGroup>} |
| """ |
| |
| def getPerson(personName): |
| """ |
| @rtype: L{Person<IPerson>} |
| """ |
| |
| class IClient(Interface): |
| |
| account = Attribute('The L{IAccount} I am a Client for') |
| |
| def __init__(account, chatui, logonDeferred): |
| """ |
| @type account: L{IAccount} |
| @type chatui: L{IChatUI} |
| @param logonDeferred: Will be called back once I am logged on. |
| @type logonDeferred: L{Deferred<twisted.internet.defer.Deferred>} |
| """ |
| |
| def joinGroup(groupName): |
| """ |
| @param groupName: The name of the group to join. |
| @type groupName: string |
| """ |
| |
| def leaveGroup(groupName): |
| """ |
| @param groupName: The name of the group to leave. |
| @type groupName: string |
| """ |
| |
| def getGroupConversation(name, hide=0): |
| pass |
| |
| def getPerson(name): |
| pass |
| |
| |
| class IPerson(Interface): |
| |
| def __init__(name, account): |
| """ |
| Initialize me. |
| |
| @param name: My name, as the server knows me. |
| @type name: string |
| @param account: The account I am accessed through. |
| @type account: I{Account} |
| """ |
| |
| def isOnline(): |
| """ |
| Am I online right now? |
| |
| @rtype: boolean |
| """ |
| |
| def getStatus(): |
| """ |
| What is my on-line status? |
| |
| @return: L{locals.StatusEnum} |
| """ |
| |
| def getIdleTime(): |
| """ |
| @rtype: string (XXX: How about a scalar?) |
| """ |
| |
| def sendMessage(text, metadata=None): |
| """ |
| Send a message to this person. |
| |
| @type text: string |
| @type metadata: dict |
| """ |
| |
| |
| class IGroup(Interface): |
| """ |
| A group which you may have a conversation with. |
| |
| Groups generally have a loosely-defined set of members, who may |
| leave and join at any time. |
| """ |
| |
| name = Attribute('My C{str} name, as the server knows me.') |
| account = Attribute('The L{Account<IAccount>} I am accessed through.') |
| |
| def __init__(name, account): |
| """ |
| Initialize me. |
| |
| @param name: My name, as the server knows me. |
| @type name: str |
| @param account: The account I am accessed through. |
| @type account: L{Account<IAccount>} |
| """ |
| |
| def setTopic(text): |
| """ |
| Set this Groups topic on the server. |
| |
| @type text: string |
| """ |
| |
| def sendGroupMessage(text, metadata=None): |
| """ |
| Send a message to this group. |
| |
| @type text: str |
| |
| @type metadata: dict |
| @param metadata: Valid keys for this dictionary include: |
| |
| - C{'style'}: associated with one of: |
| - C{'emote'}: indicates this is an action |
| """ |
| |
| def join(): |
| """ |
| Join this group. |
| """ |
| |
| def leave(): |
| """ |
| Depart this group. |
| """ |
| |
| |
| class IConversation(Interface): |
| """ |
| A conversation with a specific person. |
| """ |
| |
| def __init__(person, chatui): |
| """ |
| @type person: L{IPerson} |
| """ |
| |
| def show(): |
| """ |
| doesn't seem like it belongs in this interface. |
| """ |
| |
| def hide(): |
| """ |
| nor this neither. |
| """ |
| |
| def sendText(text, metadata): |
| pass |
| |
| def showMessage(text, metadata): |
| pass |
| |
| def changedNick(person, newnick): |
| """ |
| @param person: XXX Shouldn't this always be Conversation.person? |
| """ |
| |
| class IGroupConversation(Interface): |
| |
| def show(): |
| """ |
| doesn't seem like it belongs in this interface. |
| """ |
| |
| def hide(): |
| """ |
| nor this neither. |
| """ |
| |
| def sendText(text, metadata): |
| pass |
| |
| def showGroupMessage(sender, text, metadata): |
| pass |
| |
| def setGroupMembers(members): |
| """ |
| Sets the list of members in the group and displays it to the user. |
| """ |
| |
| def setTopic(topic, author): |
| """ |
| Displays the topic (from the server) for the group conversation window. |
| |
| @type topic: string |
| @type author: string (XXX: Not Person?) |
| """ |
| |
| def memberJoined(member): |
| """ |
| Adds the given member to the list of members in the group conversation |
| and displays this to the user, |
| |
| @type member: string (XXX: Not Person?) |
| """ |
| |
| def memberChangedNick(oldnick, newnick): |
| """ |
| Changes the oldnick in the list of members to C{newnick} and displays this |
| change to the user, |
| |
| @type oldnick: string (XXX: Not Person?) |
| @type newnick: string |
| """ |
| |
| def memberLeft(member): |
| """ |
| Deletes the given member from the list of members in the group |
| conversation and displays the change to the user. |
| |
| @type member: string (XXX: Not Person?) |
| """ |
| |
| |
| class IChatUI(Interface): |
| |
| def registerAccountClient(client): |
| """ |
| Notifies user that an account has been signed on to. |
| |
| @type client: L{Client<IClient>} |
| """ |
| |
| def unregisterAccountClient(client): |
| """ |
| Notifies user that an account has been signed off or disconnected. |
| |
| @type client: L{Client<IClient>} |
| """ |
| |
| def getContactsList(): |
| """ |
| @rtype: L{ContactsList} |
| """ |
| |
| # WARNING: You'll want to be polymorphed into something with |
| # intrinsic stoning resistance before continuing. |
| |
| def getConversation(person, Class, stayHidden=0): |
| """ |
| For the given person object, returns the conversation window |
| or creates and returns a new conversation window if one does not exist. |
| |
| @type person: L{Person<IPerson>} |
| @type Class: L{Conversation<IConversation>} class |
| @type stayHidden: boolean |
| |
| @rtype: L{Conversation<IConversation>} |
| """ |
| |
| def getGroupConversation(group, Class, stayHidden=0): |
| """ |
| For the given group object, returns the group conversation window or |
| creates and returns a new group conversation window if it doesn't exist. |
| |
| @type group: L{Group<interfaces.IGroup>} |
| @type Class: L{Conversation<interfaces.IConversation>} class |
| @type stayHidden: boolean |
| |
| @rtype: L{GroupConversation<interfaces.IGroupConversation>} |
| """ |
| |
| def getPerson(name, client): |
| """ |
| Get a Person for a client. |
| |
| Duplicates L{IAccount.getPerson}. |
| |
| @type name: string |
| @type client: L{Client<IClient>} |
| |
| @rtype: L{Person<IPerson>} |
| """ |
| |
| def getGroup(name, client): |
| """ |
| Get a Group for a client. |
| |
| Duplicates L{IAccount.getGroup}. |
| |
| @type name: string |
| @type client: L{Client<IClient>} |
| |
| @rtype: L{Group<IGroup>} |
| """ |
| |
| def contactChangedNick(oldnick, newnick): |
| """ |
| For the given person, changes the person's name to newnick, and |
| tells the contact list and any conversation windows with that person |
| to change as well. |
| |
| @type oldnick: string |
| @type newnick: string |
| """ |
