← Back to branch summary

~certify-web-dev/twisted/certify-trunk

« back to all changes in this revision

Viewing changes to twisted/im/interfaces.py

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2004-06-21 22:01:11 UTC
  • mto: (2.2.3 sid)
  • mto: This revision was merged to the branch mainline in revision 3.
  • Revision ID: james.westby@ubuntu.com-20040621220111-vkf909euqnyrp3nr
Tags: upstream-1.3.0
Import upstream version 1.3.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
twisted/im/interfaces.py
 
1
# -*- Python -*-
 
2
"""Pan-protocol chat client.
 
3
 
 
4
Stability: incendiary, work in progress.
 
5
"""
 
6
from twisted.python.components import Interface
 
7
 
 
8
import locals
 
9
 
 
10
# (Random musings, may not reflect on current state of code:)
 
11
#
 
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)
 
18
 
 
19
 
 
20
class IAccount(Interface):
 
21
    """I represent a user's account with a chat service.
 
22
 
 
23
    @cvar gatewayType: Identifies the protocol used by this account.
 
24
    @type gatewayType: string
 
25
 
 
26
    @ivar client: The Client currently connecting to this account, if any.
 
27
    @type client: L{IClient}
 
28
    """
 
29
 
 
30
    def __init__(self, accountName, autoLogin, username, password, host, port):
 
31
        """
 
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
 
37
        @type host: string
 
38
        @type port: integer
 
39
        """
 
40
 
 
41
    def isOnline(self):
 
42
        """Am I online?
 
43
 
 
44
        @returntype: boolean
 
45
        """
 
46
 
 
47
    def logOn(self, chatui):
 
48
        """Go on-line.
 
49
 
 
50
        @type chatui: Implementor of C{IChatUI}
 
51
 
 
52
        @returntype: Deferred L{Client}
 
53
        """
 
54
 
 
55
    def logOff(self):
 
56
        """Sign off.
 
57
        """
 
58
 
 
59
    def getGroup(self, groupName):
 
60
        """
 
61
        @returntype: L{Group<IGroup>}
 
62
        """
 
63
 
 
64
    def getPerson(self, personName):
 
65
        """
 
66
        @returntype: L{Person<IPerson>}
 
67
        """
 
68
 
 
69
class IClient(Interface):
 
70
    """
 
71
    @ivar account: The Account I am a Client for.
 
72
    @type account: L{IAccount}
 
73
    """
 
74
    def __init__(self, account, chatui, logonDeferred):
 
75
        """
 
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>}
 
80
        """
 
81
 
 
82
    def joinGroup(self, groupName):
 
83
        """
 
84
        @param groupName: The name of the group to join.
 
85
        @type groupName: string
 
86
        """
 
87
 
 
88
    def leaveGroup(self, groupName):
 
89
        """
 
90
        @param groupName: The name of the group to leave.
 
91
        @type groupName: string
 
92
        """
 
93
 
 
94
    def getGroupConversation(self, name,hide=0):
 
95
        pass
 
96
 
 
97
    def getPerson(self,name):
 
98
        pass
 
99
 
 
100
 
 
101
class IPerson(Interface):
 
102
    def __init__(self, name, account):
 
103
        """Initialize me.
 
104
 
 
105
        @param name: My name, as the server knows me.
 
106
        @type name: string
 
107
        @param account: The account I am accessed through.
 
108
        @type account: I{Account}
 
109
        """
 
110
 
 
111
    def isOnline(self):
 
112
        """Am I online right now?
 
113
 
 
114
        @returntype: boolean
 
115
        """
 
116
 
 
117
    def getStatus(self):
 
118
        """What is my on-line status?
 
119
 
 
120
        @returns: L{locals.StatusEnum}
 
121
        """
 
122
 
 
123
    def getIdleTime(self):
 
124
        """
 
125
        @returntype: string (XXX: How about a scalar?)
 
126
        """
 
127
 
 
128
    def sendMessage(self, text, metadata=None):
 
129
        """Send a message to this person.
 
130
 
 
131
        @type text: string
 
132
        @type metadata: dict
 
133
        """
 
134
 
 
135
 
 
136
class IGroup(Interface):
 
137
    """A group which you may have a conversation with.
 
138
 
 
139
    Groups generally have a loosely-defined set of members, who may
 
140
    leave and join at any time.
 
141
 
 
142
    @ivar name: My name, as the server knows me.
 
143
    @type name: string
 
144
    @ivar account: The account I am accessed through.
 
145
    @type account: I{Account<IAccount>}
 
146
    """
 
147
 
 
148
    def __init__(self, name, account):
 
149
        """Initialize me.
 
150
 
 
151
        @param name: My name, as the server knows me.
 
152
        @type name: string
 
153
        @param account: The account I am accessed through.
 
154
        @type account: I{Account<IAccount>}
 
155
        """
 
156
 
 
157
    def setTopic(self, text):
 
158
        """Set this Groups topic on the server.
 
159
 
 
160
        @type text: string
 
161
        """
 
162
 
 
163
    def sendGroupMessage(self, text, metadata=None):
 
164
        """Send a message to this group.
 
165
 
 
166
        @type text: string
 
167
 
 
168
        @type metadata: dict
 
169
        @param metadata: Valid keys for this dictionary include:
 
170
        
 
171
            style: associated with one of:
 
172
                emote: indicates this is an action
 
173
        """
 
174
 
 
175
    def join(self):
 
176
        pass
 
177
 
 
178
    def leave(self):
 
179
        """Depart this group"""
 
180
 
 
181
 
 
182
class IConversation(Interface):
 
183
    """A conversation with a specific person."""
 
184
    def __init__(self, person, chatui):
 
185
        """
 
186
        @type person: L{IPerson}
 
187
        """
 
188
 
 
189
    def show(self):
 
190
        """doesn't seem like it belongs in this interface."""
 
191
 
 
192
    def hide(self):
 
193
        """nor this neither."""
 
194
 
 
195
    def sendText(self, text, metadata):
 
196
        pass
 
197
 
 
198
    def showMessage(self, text, metadata):
 
199
        pass
 
200
 
 
201
    def changedNick(self, person, newnick):
 
202
        """
 
203
        @param person: XXX Shouldn't this always be Conversation.person?
 
204
        """
 
205
 
 
206
class IGroupConversation(Interface):
 
207
    def show(self):
 
208
        """doesn't seem like it belongs in this interface."""
 
209
 
 
210
    def hide(self):
 
211
        """nor this neither."""
 
212
 
 
213
    def sendText(self, text, metadata):
 
214
        pass
 
215
 
 
216
    def showGroupMessage(self, sender, text, metadata):
 
217
        pass
 
218
 
 
219
    def setGroupMembers(self, members):
 
220
        """Sets the list of members in the group and displays it to the user
 
221
        """
 
222
 
 
223
    def setTopic(self, topic, author):
 
224
        """Displays the topic (from the server) for the group conversation window
 
225
 
 
226
        @type topic: string
 
227
        @type author: string (XXX: Not Person?)
 
228
        """
 
229
 
 
230
    def memberJoined(self, member):
 
231
        """Adds the given member to the list of members in the group conversation
 
232
        and displays this to the user
 
233
 
 
234
        @type member: string (XXX: Not Person?)
 
235
        """
 
236
 
 
237
    def memberChangedNick(self, oldnick, newnick):
 
238
        """Changes the oldnick in the list of members to newnick and displays this
 
239
        change to the user
 
240
 
 
241
        @type oldnick: string (XXX: Not Person?)
 
242
        @type newnick: string
 
243
        """
 
244
 
 
245
    def memberLeft(self, member):
 
246
        """Deletes the given member from the list of members in the group
 
247
        conversation and displays the change to the user
 
248
 
 
249
        @type member: string (XXX: Not Person?)
 
250
        """
 
251
 
 
252
 
 
253
class IChatUI(Interface):
 
254
    def registerAccountClient(self, client):
 
255
        """Notifies user that an account has been signed on to.
 
256
 
 
257
        @type client: L{Client<IClient>}
 
258
        """
 
259
 
 
260
    def unregisterAccountClient(self, client):
 
261
        """Notifies user that an account has been signed off or disconnected
 
262
 
 
263
        @type client: L{Client<IClient>}
 
264
        """
 
265
 
 
266
    def getContactsList(self):
 
267
        """
 
268
        @returntype: L{ContactsList}
 
269
        """
 
270
 
 
271
    # WARNING: You'll want to be polymorphed into something with
 
272
    # intrinsic stoning resistance before continuing.
 
273
 
 
274
    def getConversation(self, 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.
 
277
 
 
278
        @type person: L{Person<IPerson>}
 
279
        @type Class: L{Conversation<IConversation>} class
 
280
        @type stayHidden: boolean
 
281
 
 
282
        @returntype: L{Conversation<IConversation>}
 
283
        """
 
284
 
 
285
    def getGroupConversation(self,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.
 
288
 
 
289
        @type group: L{Group<interfaces.IGroup>}
 
290
        @type Class: L{Conversation<interfaces.IConversation>} class
 
291
        @type stayHidden: boolean
 
292
 
 
293
        @returntype: L{GroupConversation<interfaces.IGroupConversation>}
 
294
        """
 
295
 
 
296
    def getPerson(self, name, client):
 
297
        """Get a Person for a client.
 
298
 
 
299
        Duplicates L{IAccount.getPerson}.
 
300
 
 
301
        @type name: string
 
302
        @type client: L{Client<IClient>}
 
303
 
 
304
        @returntype: L{Person<IPerson>}
 
305
        """
 
306
 
 
307
    def getGroup(self, name, client):
 
308
        """Get a Group for a client.
 
309
 
 
310
        Duplicates L{IAccount.getGroup}.
 
311
 
 
312
        @type name: string
 
313
        @type client: L{Client<IClient>}
 
314
 
 
315
        @returntype: L{Group<IGroup>}
 
316
        """
 
317
 
 
318
    def contactChangedNick(self, 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
 
321
        to change as well.
 
322
 
 
323
        @type oldnick: string
 
324
        @type newnick: string
 
325
        """