# -*- Python -*-
# Copyright (c) Twisted Matrix Laboratories.
# See LICENSE for details.
"""
Pan-protocol chat client.
"""
from zope.interface import Interface, Attribute
# (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} with an eventual L{IClient} result.
"""
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
"""