twisted/words/im/interfaces.py

   1 # -*- Python -*-
   2 # Copyright (c) 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         """