summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLance Stout <lancestout@gmail.com>2010-08-03 17:30:34 -0400
committerLance Stout <lancestout@gmail.com>2010-08-03 17:30:34 -0400
commit41ab2b84604849d0e650ecd833554b3488733785 (patch)
tree861a77851ea4d754a0e5c1281ee4fce468e40748
parent939ae298c2856f095526a9e0f52216e9dc4e7db1 (diff)
downloadslixmpp-41ab2b84604849d0e650ecd833554b3488733785.tar.gz
slixmpp-41ab2b84604849d0e650ecd833554b3488733785.tar.bz2
slixmpp-41ab2b84604849d0e650ecd833554b3488733785.tar.xz
slixmpp-41ab2b84604849d0e650ecd833554b3488733785.zip
Updated presence stanza with documentation and PEP8 style.
-rw-r--r--sleekxmpp/stanza/presence.py183
-rw-r--r--tests/test_presencestanzas.py96
2 files changed, 185 insertions, 94 deletions
diff --git a/sleekxmpp/stanza/presence.py b/sleekxmpp/stanza/presence.py
index ec681763..651bf34d 100644
--- a/sleekxmpp/stanza/presence.py
+++ b/sleekxmpp/stanza/presence.py
@@ -6,54 +6,141 @@
See the file LICENSE for copying permission.
"""
-from . error import Error
-from . rootstanza import RootStanza
-from .. xmlstream.stanzabase import StanzaBase, ET
+from sleekxmpp.stanza import Error
+from sleekxmpp.stanza.rootstanza import RootStanza
+from sleekxmpp.xmlstream.stanzabase import StanzaBase, ET
class Presence(RootStanza):
- interfaces = set(('type', 'to', 'from', 'id', 'show', 'status', 'priority'))
- types = set(('available', 'unavailable', 'error', 'probe', 'subscribe', 'subscribed', 'unsubscribe', 'unsubscribed'))
- showtypes = set(('dnd', 'chat', 'xa', 'away'))
- sub_interfaces = set(('show', 'status', 'priority'))
- name = 'presence'
- plugin_attrib = name
- namespace = 'jabber:client'
-
- def setShow(self, show):
- if show in self.showtypes:
- self._setSubText('show', text=show)
- return self
-
- def setType(self, value):
- if value in self.types:
- self['show'] = None
- if value == 'available':
- value = ''
- self._setAttr('type', value)
- elif value in self.showtypes:
- self['show'] = value
- return self
-
- def setPriority(self, value):
- self._setSubText('priority', text = str(value))
-
- def getPriority(self):
- p = self._getSubText('priority')
- if not p: p = 0
- return int(p)
-
- def getType(self):
- out = self._getAttr('type')
- if not out:
- out = self['show']
- if not out or out is None:
- out = 'available'
- return out
-
- def reply(self):
- if self['type'] == 'unsubscribe':
- self['type'] = 'unsubscribed'
- elif self['type'] == 'subscribe':
- self['type'] = 'subscribed'
- return StanzaBase.reply(self)
+
+ """
+ XMPP's <presence> stanza allows entities to know the status of other
+ clients and components. Since it is currently the only multi-cast
+ stanza in XMPP, many extensions add more information to <presence>
+ stanzas to broadcast to every entry in the roster, such as
+ capabilities, music choices, or locations (XEP-0115: Entity Capabilities
+ and XEP-0163: Personal Eventing Protocol).
+
+ Since <presence> stanzas are broadcast when an XMPP entity changes
+ its status, the bulk of the traffic in an XMPP network will be from
+ <presence> stanzas. Therefore, do not include more information than
+ necessary in a status message or within a <presence> stanza in order
+ to help keep the network running smoothly.
+
+ Example <presence> stanzas:
+ <presence />
+
+ <presence from="user@example.com">
+ <show>away</show>
+ <status>Getting lunch.</status>
+ <priority>5</priority>
+ </presence>
+
+ <presence type="unavailable" />
+
+ <presence to="user@otherhost.com" type="subscribe" />
+
+ Stanza Interface:
+ priority -- A value used by servers to determine message routing.
+ show -- The type of status, such as away or available for chat.
+ status -- Custom, human readable status message.
+
+ Attributes:
+ types -- One of: available, unavailable, error, probe,
+ subscribe, subscribed, unsubscribe,
+ and unsubscribed.
+ showtypes -- One of: away, chat, dnd, and xa.
+
+ Methods:
+ reply -- Overrides StanzaBase.reply
+ setShow -- Set the value of the <show> element.
+ getType -- Get the value of the type attribute or <show> element.
+ setType -- Set the value of the type attribute or <show> element.
+ getPriority -- Get the value of the <priority> element.
+ setPriority -- Set the value of the <priority> element.
+ """
+
+ namespace = 'jabber:client'
+ name = 'presence'
+ interfaces = set(('type', 'to', 'from', 'id', 'show',
+ 'status', 'priority'))
+ sub_interfaces = set(('show', 'status', 'priority'))
+ plugin_attrib = name
+
+ types = set(('available', 'unavailable', 'error', 'probe', 'subscribe',
+ 'subscribed', 'unsubscribe', 'unsubscribed'))
+ showtypes = set(('dnd', 'chat', 'xa', 'away'))
+
+ def setShow(self, show):
+ """
+ Set the value of the <show> element.
+
+ Arguments:
+ show -- Must be one of: away, chat, dnd, or xa.
+ """
+ if show in self.showtypes:
+ self._setSubText('show', text=show)
+ return self
+
+ def setType(self, value):
+ """
+ Set the type attribute's value, and the <show> element
+ if applicable.
+
+ Arguments:
+ value -- Must be in either self.types or self.showtypes.
+ """
+ if value in self.types:
+ self['show'] = None
+ if value == 'available':
+ value = ''
+ self._setAttr('type', value)
+ elif value in self.showtypes:
+ self['show'] = value
+ return self
+
+ def setPriority(self, value):
+ """
+ Set the entity's priority value. Some server use priority to
+ determine message routing behavior.
+
+ Bot clients should typically use a priority of 0 if the same
+ JID is used elsewhere by a human-interacting client.
+
+ Arguments:
+ value -- An integer value greater than or equal to 0.
+ """
+ self._setSubText('priority', text=str(value))
+
+ def getPriority(self):
+ """
+ Return the value of the <presence> element as an integer.
+ """
+ p = self._getSubText('priority')
+ if not p:
+ p = 0
+ return int(p)
+
+ def getType(self):
+ """
+ Return the value of the <presence> stanza's type attribute, or
+ the value of the <show> element.
+ """
+ out = self._getAttr('type')
+ if not out:
+ out = self['show']
+ if not out or out is None:
+ out = 'available'
+ return out
+
+ def reply(self):
+ """
+ Set the appropriate presence reply type.
+
+ Overrides StanzaBase.reply.
+ """
+ if self['type'] == 'unsubscribe':
+ self['type'] = 'unsubscribed'
+ elif self['type'] == 'subscribe':
+ self['type'] = 'subscribed'
+ return StanzaBase.reply(self)
diff --git a/tests/test_presencestanzas.py b/tests/test_presencestanzas.py
index 02799c8f..2cab3af7 100644
--- a/tests/test_presencestanzas.py
+++ b/tests/test_presencestanzas.py
@@ -2,52 +2,56 @@ import sleekxmpp
from sleektest import *
from sleekxmpp.stanza.presence import Presence
+
class TestPresenceStanzas(SleekTest):
-
- def testPresenceShowRegression(self):
- """Regression check presence['type'] = 'dnd' show value working"""
- p = self.Presence()
- p['type'] = 'dnd'
- self.checkPresence(p, """
- <presence><show>dnd</show></presence>
- """)
-
- def testPresenceType(self):
- """Test manipulating presence['type']"""
- p = self.Presence()
- p['type'] = 'available'
- self.checkPresence(p, """
- <presence />
- """)
- self.failUnless(p['type'] == 'available', "Incorrect presence['type'] for type 'available'")
-
- for showtype in ['away', 'chat', 'dnd', 'xa']:
- p['type'] = showtype
- self.checkPresence(p, """
- <presence><show>%s</show></presence>
- """ % showtype)
- self.failUnless(p['type'] == showtype, "Incorrect presence['type'] for type '%s'" % showtype)
-
- p['type'] = None
- self.checkPresence(p, """
- <presence />
- """)
-
- def testPresenceUnsolicitedOffline(self):
- """Unsolicted offline presence does not spawn changed_status or update roster"""
- p = self.Presence()
- p['type'] = 'unavailable'
- p['from'] = 'bill@chadmore.com/gmail15af'
-
- c = sleekxmpp.ClientXMPP('crap@wherever', 'password')
- happened = []
- def handlechangedpresence(event):
- happened.append(True)
- c.add_event_handler("changed_status", handlechangedpresence)
- c._handlePresence(p)
-
- self.failUnless(happened == [], "changed_status event triggered for superfulous unavailable presence")
- self.failUnless(c.roster == {}, "Roster updated for superfulous unavailable presence")
-
+
+ def testPresenceShowRegression(self):
+ """Regression check presence['type'] = 'dnd' show value working"""
+ p = self.Presence()
+ p['type'] = 'dnd'
+ self.checkPresence(p, "<presence><show>dnd</show></presence>")
+
+ def testPresenceType(self):
+ """Test manipulating presence['type']"""
+ p = self.Presence()
+ p['type'] = 'available'
+ self.checkPresence(p, "<presence />")
+ self.failUnless(p['type'] == 'available',
+ "Incorrect presence['type'] for type 'available'")
+
+ for showtype in ['away', 'chat', 'dnd', 'xa']:
+ p['type'] = showtype
+ self.checkPresence(p, """
+ <presence><show>%s</show></presence>
+ """ % showtype)
+ self.failUnless(p['type'] == showtype,
+ "Incorrect presence['type'] for type '%s'" % showtype)
+
+ p['type'] = None
+ self.checkPresence(p, "<presence />")
+
+ def testPresenceUnsolicitedOffline(self):
+ """
+ Unsolicted offline presence does not spawn changed_status
+ or update the roster.
+ """
+ p = self.Presence()
+ p['type'] = 'unavailable'
+ p['from'] = 'bill@chadmore.com/gmail15af'
+
+ c = sleekxmpp.ClientXMPP('crap@wherever', 'password')
+ happened = []
+
+ def handlechangedpresence(event):
+ happened.append(True)
+
+ c.add_event_handler("changed_status", handlechangedpresence)
+ c._handlePresence(p)
+
+ self.failUnless(happened == [],
+ "changed_status event triggered for extra unavailable presence")
+ self.failUnless(c.roster == {},
+ "Roster updated for superfulous unavailable presence")
+
suite = unittest.TestLoader().loadTestsFromTestCase(TestPresenceStanzas)