dreamirc/src/interfaces.py

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