← Back to branch summary

~soren/nova/iptables-security-groups

« back to all changes in this revision

Viewing changes to vendor/Twisted-10.0.0/twisted/words/im/interfaces.py

  • Committer: Jesse Andrews
  • Date: 2010-05-28 06:05:26 UTC
  • Revision ID: git-v1:bf6e6e718cdc7488e2da87b21e258ccc065fe499
initial commit

Show diffs side-by-side

added added

removed removed

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