2
"""Pan-protocol chat client.
4
Stability: incendiary, work in progress.
6
from zope.interface import Interface
8
from twisted.words.im import locals
10
# (Random musings, may not reflect on current state of code:)
12
# Accounts have Protocol components (clients)
13
# Persons have Conversation components
14
# Groups have GroupConversation components
15
# Persons and Groups are associated with specific Accounts
16
# At run-time, Clients/Accounts are slaved to a User Interface
17
# (Note: User may be a bot, so don't assume all UIs are built on gui toolkits)
20
class IAccount(Interface):
21
"""I represent a user's account with a chat service.
23
@cvar gatewayType: Identifies the protocol used by this account.
24
@type gatewayType: string
26
@ivar client: The Client currently connecting to this account, if any.
27
@type client: L{IClient}
30
def __init__(accountName, autoLogin, username, password, host, port):
32
@type accountName: string
33
@param accountName: A name to refer to the account by locally.
34
@type autoLogin: boolean
35
@type username: string
36
@type password: string
50
@type chatui: Implementor of C{IChatUI}
52
@returntype: Deferred L{Client}
59
def getGroup(groupName):
61
@returntype: L{Group<IGroup>}
64
def getPerson(personName):
66
@returntype: L{Person<IPerson>}
69
class IClient(Interface):
71
@ivar account: The Account I am a Client for.
72
@type account: L{IAccount}
74
def __init__(account, chatui, logonDeferred):
76
@type account: L{IAccount}
77
@type chatui: L{IChatUI}
78
@param logonDeferred: Will be called back once I am logged on.
79
@type logonDeferred: L{Deferred<twisted.internet.defer.Deferred>}
82
def joinGroup(groupName):
84
@param groupName: The name of the group to join.
85
@type groupName: string
88
def leaveGroup(groupName):
90
@param groupName: The name of the group to leave.
91
@type groupName: string
94
def getGroupConversation(name,hide=0):
101
class IPerson(Interface):
102
def __init__(name, account):
105
@param name: My name, as the server knows me.
107
@param account: The account I am accessed through.
108
@type account: I{Account}
112
"""Am I online right now?
118
"""What is my on-line status?
120
@returns: L{locals.StatusEnum}
125
@returntype: string (XXX: How about a scalar?)
128
def sendMessage(text, metadata=None):
129
"""Send a message to this person.
136
class IGroup(Interface):
137
"""A group which you may have a conversation with.
139
Groups generally have a loosely-defined set of members, who may
140
leave and join at any time.
142
@ivar name: My name, as the server knows me.
144
@ivar account: The account I am accessed through.
145
@type account: I{Account<IAccount>}
148
def __init__(name, account):
151
@param name: My name, as the server knows me.
153
@param account: The account I am accessed through.
154
@type account: I{Account<IAccount>}
158
"""Set this Groups topic on the server.
163
def sendGroupMessage(text, metadata=None):
164
"""Send a message to this group.
169
@param metadata: Valid keys for this dictionary include:
171
- C{'style'}: associated with one of:
172
- C{'emote'}: indicates this is an action
179
"""Depart this group"""
182
class IConversation(Interface):
183
"""A conversation with a specific person."""
184
def __init__(person, chatui):
186
@type person: L{IPerson}
190
"""doesn't seem like it belongs in this interface."""
193
"""nor this neither."""
195
def sendText(text, metadata):
198
def showMessage(text, metadata):
201
def changedNick(person, newnick):
203
@param person: XXX Shouldn't this always be Conversation.person?
206
class IGroupConversation(Interface):
208
"""doesn't seem like it belongs in this interface."""
211
"""nor this neither."""
213
def sendText(text, metadata):
216
def showGroupMessage(sender, text, metadata):
219
def setGroupMembers(members):
220
"""Sets the list of members in the group and displays it to the user
223
def setTopic(topic, author):
224
"""Displays the topic (from the server) for the group conversation window
227
@type author: string (XXX: Not Person?)
230
def memberJoined(member):
231
"""Adds the given member to the list of members in the group conversation
232
and displays this to the user
234
@type member: string (XXX: Not Person?)
237
def memberChangedNick(oldnick, newnick):
238
"""Changes the oldnick in the list of members to newnick and displays this
241
@type oldnick: string (XXX: Not Person?)
242
@type newnick: string
245
def memberLeft(member):
246
"""Deletes the given member from the list of members in the group
247
conversation and displays the change to the user
249
@type member: string (XXX: Not Person?)
253
class IChatUI(Interface):
254
def registerAccountClient(client):
255
"""Notifies user that an account has been signed on to.
257
@type client: L{Client<IClient>}
260
def unregisterAccountClient(client):
261
"""Notifies user that an account has been signed off or disconnected
263
@type client: L{Client<IClient>}
266
def getContactsList():
268
@returntype: L{ContactsList}
271
# WARNING: You'll want to be polymorphed into something with
272
# intrinsic stoning resistance before continuing.
274
def getConversation(person, Class, stayHidden=0):
275
"""For the given person object, returns the conversation window
276
or creates and returns a new conversation window if one does not exist.
278
@type person: L{Person<IPerson>}
279
@type Class: L{Conversation<IConversation>} class
280
@type stayHidden: boolean
282
@returntype: L{Conversation<IConversation>}
285
def getGroupConversation(group,Class,stayHidden=0):
286
"""For the given group object, returns the group conversation window or
287
creates and returns a new group conversation window if it doesn't exist.
289
@type group: L{Group<interfaces.IGroup>}
290
@type Class: L{Conversation<interfaces.IConversation>} class
291
@type stayHidden: boolean
293
@returntype: L{GroupConversation<interfaces.IGroupConversation>}
296
def getPerson(name, client):
297
"""Get a Person for a client.
299
Duplicates L{IAccount.getPerson}.
302
@type client: L{Client<IClient>}
304
@returntype: L{Person<IPerson>}
307
def getGroup(name, client):
308
"""Get a Group for a client.
310
Duplicates L{IAccount.getGroup}.
313
@type client: L{Client<IClient>}
315
@returntype: L{Group<IGroup>}
318
def contactChangedNick(oldnick, newnick):
319
"""For the given person, changes the person's name to newnick, and
320
tells the contact list and any conversation windows with that person
323
@type oldnick: string
324
@type newnick: string
added
removed
twisted/words/im/interfaces.py
