summaryrefslogtreecommitdiff
path: root/sleekxmpp/xmlstream
diff options
context:
space:
mode:
Diffstat (limited to 'sleekxmpp/xmlstream')
-rw-r--r--sleekxmpp/xmlstream/filesocket.py24
-rw-r--r--sleekxmpp/xmlstream/handler/base.py85
-rw-r--r--sleekxmpp/xmlstream/handler/callback.py82
-rw-r--r--sleekxmpp/xmlstream/handler/waiter.py93
-rw-r--r--sleekxmpp/xmlstream/jid.py58
-rw-r--r--sleekxmpp/xmlstream/matcher/base.py23
-rw-r--r--sleekxmpp/xmlstream/matcher/id.py25
-rw-r--r--sleekxmpp/xmlstream/matcher/stanzapath.py28
-rw-r--r--sleekxmpp/xmlstream/matcher/xmlmask.py71
-rw-r--r--sleekxmpp/xmlstream/matcher/xpath.py43
-rw-r--r--sleekxmpp/xmlstream/scheduler.py149
-rw-r--r--sleekxmpp/xmlstream/stanzabase.py925
-rw-r--r--sleekxmpp/xmlstream/tostring.py64
-rw-r--r--sleekxmpp/xmlstream/xmlstream.py907
14 files changed, 1298 insertions, 1279 deletions
diff --git a/sleekxmpp/xmlstream/filesocket.py b/sleekxmpp/xmlstream/filesocket.py
index fd81864b..56554c73 100644
--- a/sleekxmpp/xmlstream/filesocket.py
+++ b/sleekxmpp/xmlstream/filesocket.py
@@ -1,9 +1,15 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.xmlstream.filesocket
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ This module is a shim for correcting deficiencies in the file
+ socket implementation of Python2.6.
+
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
from socket import _fileobject
@@ -12,12 +18,11 @@ import socket
class FileSocket(_fileobject):
- """
- Create a file object wrapper for a socket to work around
+ """Create a file object wrapper for a socket to work around
issues present in Python 2.6 when using sockets as file objects.
- The parser for xml.etree.cElementTree requires a file, but we will
- be reading from the XMPP connection socket instead.
+ The parser for :class:`~xml.etree.cElementTree` requires a file, but
+ we will be reading from the XMPP connection socket instead.
"""
def read(self, size=4096):
@@ -31,8 +36,7 @@ class FileSocket(_fileobject):
class Socket26(socket._socketobject):
- """
- A custom socket implementation that uses our own FileSocket class
+ """A custom socket implementation that uses our own FileSocket class
to work around issues in Python 2.6 when using sockets as files.
"""
diff --git a/sleekxmpp/xmlstream/handler/base.py b/sleekxmpp/xmlstream/handler/base.py
index 7f05c757..59dcb306 100644
--- a/sleekxmpp/xmlstream/handler/base.py
+++ b/sleekxmpp/xmlstream/handler/base.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.xmlstream.handler.base
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
import weakref
@@ -16,78 +19,62 @@ class BaseHandler(object):
incoming stanzas so that the stanza may be processed in some way.
Stanzas may be matched with multiple handlers.
- Handler execution may take place in two phases. The first is during
- the stream processing itself. The second is after stream processing
- and during SleekXMPP's main event loop. The prerun method is used
- for execution during stream processing, and the run method is used
- during the main event loop.
-
- Attributes:
- name -- The name of the handler.
- stream -- The stream this handler is assigned to.
-
- Methods:
- match -- Compare a stanza with the handler's matcher.
- prerun -- Handler execution during stream processing.
- run -- Handler execution during the main event loop.
- check_delete -- Indicate if the handler may be removed from use.
+ Handler execution may take place in two phases: during the incoming
+ stream processing, and in the main event loop. The :meth:`prerun()`
+ method is executed in the first case, and :meth:`run()` is called
+ during the second.
+
+ :param string name: The name of the handler.
+ :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
+ derived object that will be used to determine if a
+ stanza should be accepted by this handler.
+ :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
+ instance that the handle will respond to.
"""
def __init__(self, name, matcher, stream=None):
- """
- Create a new stream handler.
-
- Arguments:
- name -- The name of the handler.
- matcher -- A matcher object from xmlstream.matcher that will be
- used to determine if a stanza should be accepted by
- this handler.
- stream -- The XMLStream instance the handler should monitor.
- """
+ #: The name of the handler
self.name = name
+
+ #: The XML stream this handler is assigned to
+ self.stream = None
if stream is not None:
self.stream = weakref.ref(stream)
- else:
- self.stream = None
+ stream.register_handler(self)
+
self._destroy = False
self._payload = None
self._matcher = matcher
- if stream is not None:
- stream.registerHandler(self)
def match(self, xml):
- """
- Compare a stanza or XML object with the handler's matcher.
+ """Compare a stanza or XML object with the handler's matcher.
- Arguments
- xml -- An XML or stanza object.
+ :param xml: An XML or
+ :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object
"""
return self._matcher.match(xml)
def prerun(self, payload):
- """
- Prepare the handler for execution while the XML stream is being
- processed.
+ """Prepare the handler for execution while the XML
+ stream is being processed.
- Arguments:
- payload -- A stanza object.
+ :param payload: A :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+ object.
"""
self._payload = payload
def run(self, payload):
- """
- Execute the handler after XML stream processing and during the
+ """Execute the handler after XML stream processing and during the
main event loop.
- Arguments:
- payload -- A stanza object.
+ :param payload: A :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+ object.
"""
self._payload = payload
def check_delete(self):
- """
- Check if the handler should be removed from the list of stream
- handlers.
+ """Check if the handler should be removed from the list
+ of stream handlers.
"""
return self._destroy
diff --git a/sleekxmpp/xmlstream/handler/callback.py b/sleekxmpp/xmlstream/handler/callback.py
index 7fadab43..37f53335 100644
--- a/sleekxmpp/xmlstream/handler/callback.py
+++ b/sleekxmpp/xmlstream/handler/callback.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.xmlstream.handler.callback
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
from sleekxmpp.xmlstream.handler.base import BaseHandler
@@ -18,48 +21,42 @@ class Callback(BaseHandler):
The handler may execute the callback either during stream
processing or during the main event loop.
- Callback functions are all executed in the same thread, so be
- aware if you are executing functions that will block for extended
- periods of time. Typically, you should signal your own events using the
- SleekXMPP object's event() method to pass the stanza off to a threaded
- event handler for further processing.
-
- Methods:
- prerun -- Overrides BaseHandler.prerun
- run -- Overrides BaseHandler.run
+ Callback functions are all executed in the same thread, so be aware if
+ you are executing functions that will block for extended periods of
+ time. Typically, you should signal your own events using the SleekXMPP
+ object's :meth:`~sleekxmpp.xmlstream.xmlstream.XMLStream.event()`
+ method to pass the stanza off to a threaded event handler for further
+ processing.
+
+
+ :param string name: The name of the handler.
+ :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
+ derived object for matching stanza objects.
+ :param pointer: The function to execute during callback.
+ :param bool thread: **DEPRECATED.** Remains only for
+ backwards compatibility.
+ :param bool once: Indicates if the handler should be used only
+ once. Defaults to False.
+ :param bool instream: Indicates if the callback should be executed
+ during stream processing instead of in the
+ main event loop.
+ :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
+ instance this handler should monitor.
"""
def __init__(self, name, matcher, pointer, thread=False,
once=False, instream=False, stream=None):
- """
- Create a new callback handler.
-
- Arguments:
- name -- The name of the handler.
- matcher -- A matcher object for matching stanza objects.
- pointer -- The function to execute during callback.
- thread -- DEPRECATED. Remains only for backwards compatibility.
- once -- Indicates if the handler should be used only
- once. Defaults to False.
- instream -- Indicates if the callback should be executed
- during stream processing instead of in the
- main event loop.
- stream -- The XMLStream instance this handler should monitor.
- """
BaseHandler.__init__(self, name, matcher, stream)
self._pointer = pointer
self._once = once
self._instream = instream
def prerun(self, payload):
- """
- Execute the callback during stream processing, if
- the callback was created with instream=True.
-
- Overrides BaseHandler.prerun
+ """Execute the callback during stream processing, if
+ the callback was created with ``instream=True``.
- Arguments:
- payload -- The matched stanza object.
+ :param payload: The matched
+ :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
"""
if self._once:
self._destroy = True
@@ -67,16 +64,13 @@ class Callback(BaseHandler):
self.run(payload, True)
def run(self, payload, instream=False):
- """
- Execute the callback function with the matched stanza payload.
-
- Overrides BaseHandler.run
+ """Execute the callback function with the matched stanza payload.
- Arguments:
- payload -- The matched stanza object.
- instream -- Force the handler to execute during
- stream processing. Used only by prerun.
- Defaults to False.
+ :param payload: The matched
+ :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
+ :param bool instream: Force the handler to execute during stream
+ processing. This should only be used by
+ :meth:`prerun()`. Defaults to ``False``.
"""
if not self._instream or instream:
self._pointer(payload)
diff --git a/sleekxmpp/xmlstream/handler/waiter.py b/sleekxmpp/xmlstream/handler/waiter.py
index 25dc161c..01ff5d67 100644
--- a/sleekxmpp/xmlstream/handler/waiter.py
+++ b/sleekxmpp/xmlstream/handler/waiter.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.xmlstream.handler.waiter
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
import logging
@@ -22,83 +25,63 @@ log = logging.getLogger(__name__)
class Waiter(BaseHandler):
"""
- The Waiter handler allows an event handler to block
- until a particular stanza has been received. The handler
- will either be given the matched stanza, or False if the
- waiter has timed out.
-
- Methods:
- check_delete -- Overrides BaseHandler.check_delete
- prerun -- Overrides BaseHandler.prerun
- run -- Overrides BaseHandler.run
- wait -- Wait for a stanza to arrive and return it to
- an event handler.
+ The Waiter handler allows an event handler to block until a
+ particular stanza has been received. The handler will either be
+ given the matched stanza, or ``False`` if the waiter has timed out.
+
+ :param string name: The name of the handler.
+ :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
+ derived object for matching stanza objects.
+ :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
+ instance this handler should monitor.
"""
def __init__(self, name, matcher, stream=None):
- """
- Create a new Waiter.
-
- Arguments:
- name -- The name of the waiter.
- matcher -- A matcher object to detect the desired stanza.
- stream -- Optional XMLStream instance to monitor.
- """
BaseHandler.__init__(self, name, matcher, stream=stream)
self._payload = queue.Queue()
def prerun(self, payload):
- """
- Store the matched stanza.
-
- Overrides BaseHandler.prerun
+ """Store the matched stanza when received during processing.
- Arguments:
- payload -- The matched stanza object.
+ :param payload: The matched
+ :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
"""
self._payload.put(payload)
def run(self, payload):
- """
- Do not process this handler during the main event loop.
-
- Overrides BaseHandler.run
-
- Arguments:
- payload -- The matched stanza object.
- """
+ """Do not process this handler during the main event loop."""
pass
def wait(self, timeout=None):
- """
- Block an event handler while waiting for a stanza to arrive.
+ """Block an event handler while waiting for a stanza to arrive.
Be aware that this will impact performance if called from a
non-threaded event handler.
- Will return either the received stanza, or False if the waiter
- timed out.
+ Will return either the received stanza, or ``False`` if the
+ waiter timed out.
- Arguments:
- timeout -- The number of seconds to wait for the stanza to
- arrive. Defaults to the global default timeout
- value sleekxmpp.xmlstream.RESPONSE_TIMEOUT.
+ :param int timeout: The number of seconds to wait for the stanza
+ to arrive. Defaults to the the stream's
+ :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream.response_timeout`
+ value.
"""
if timeout is None:
timeout = self.stream().response_timeout
- try:
- stanza = self._payload.get(True, timeout)
- except queue.Empty:
- stanza = False
- log.warning("Timed out waiting for %s" % self.name)
+ elapsed_time = 0
+ stanza = False
+ while elapsed_time < timeout and not self.stream().stop.is_set():
+ try:
+ stanza = self._payload.get(True, 1)
+ break
+ except queue.Empty:
+ elapsed_time += 1
+ if elapsed_time >= timeout:
+ log.warning("Timed out waiting for %s", self.name)
self.stream().remove_handler(self.name)
return stanza
def check_delete(self):
- """
- Always remove waiters after use.
-
- Overrides BaseHandler.check_delete
- """
+ """Always remove waiters after use."""
return True
diff --git a/sleekxmpp/xmlstream/jid.py b/sleekxmpp/xmlstream/jid.py
index 3d617f5a..c91c8fb3 100644
--- a/sleekxmpp/xmlstream/jid.py
+++ b/sleekxmpp/xmlstream/jid.py
@@ -1,15 +1,22 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.xmlstream.jid
+ ~~~~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ This module allows for working with Jabber IDs (JIDs) by
+ providing accessors for the various components of a JID.
+
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
from __future__ import unicode_literals
class JID(object):
+
"""
A representation of a Jabber ID, or JID.
@@ -19,18 +26,16 @@ class JID(object):
When a resource is not used, the JID is called a bare JID.
The JID is a full JID otherwise.
- Attributes:
- jid -- Alias for 'full'.
- full -- The value of the full JID.
- bare -- The value of the bare JID.
- user -- The username portion of the JID.
- domain -- The domain name portion of the JID.
- server -- Alias for 'domain'.
- resource -- The resource portion of the JID.
-
- Methods:
- reset -- Use a new JID value.
- regenerate -- Recreate the JID from its components.
+ **JID Properties:**
+ :jid: Alias for ``full``.
+ :full: The value of the full JID.
+ :bare: The value of the bare JID.
+ :user: The username portion of the JID.
+ :domain: The domain name portion of the JID.
+ :server: Alias for ``domain``.
+ :resource: The resource portion of the JID.
+
+ :param string jid: A string of the form ``'[user@]domain[/resource]'``.
"""
def __init__(self, jid):
@@ -38,11 +43,9 @@ class JID(object):
self.reset(jid)
def reset(self, jid):
- """
- Start fresh from a new JID string.
+ """Start fresh from a new JID string.
- Arguments:
- jid - The new JID value.
+ :param string jid: A string of the form ``'[user@]domain[/resource]'``.
"""
if isinstance(jid, JID):
jid = jid.full
@@ -53,12 +56,10 @@ class JID(object):
self._bare = None
def __getattr__(self, name):
- """
- Handle getting the JID values, using cache if available.
+ """Handle getting the JID values, using cache if available.
- Arguments:
- name -- One of: user, server, domain, resource,
- full, or bare.
+ :param name: One of: user, server, domain, resource,
+ full, or bare.
"""
if name == 'resource':
if self._resource is None and '/' in self._jid:
@@ -83,8 +84,7 @@ class JID(object):
return self._bare or ""
def __setattr__(self, name, value):
- """
- Edit a JID by updating it's individual values, resetting the
+ """Edit a JID by updating it's individual values, resetting the
generated JID in the end.
Arguments:
@@ -137,7 +137,5 @@ class JID(object):
return self.full == other.full
def __ne__(self, other):
- """
- Two JIDs are considered unequal if they are not equal.
- """
+ """Two JIDs are considered unequal if they are not equal."""
return not self == other
diff --git a/sleekxmpp/xmlstream/matcher/base.py b/sleekxmpp/xmlstream/matcher/base.py
index 701ab32f..83c26688 100644
--- a/sleekxmpp/xmlstream/matcher/base.py
+++ b/sleekxmpp/xmlstream/matcher/base.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.xmlstream.matcher.base
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
@@ -13,21 +16,15 @@ class MatcherBase(object):
Base class for stanza matchers. Stanza matchers are used to pick
stanzas out of the XML stream and pass them to the appropriate
stream handlers.
+
+ :param criteria: Object to compare some aspect of a stanza against.
"""
def __init__(self, criteria):
- """
- Create a new stanza matcher.
-
- Arguments:
- criteria -- Object to compare some aspect of a stanza
- against.
- """
self._criteria = criteria
def match(self, xml):
- """
- Check if a stanza matches the stored criteria.
+ """Check if a stanza matches the stored criteria.
Meant to be overridden.
"""
diff --git a/sleekxmpp/xmlstream/matcher/id.py b/sleekxmpp/xmlstream/matcher/id.py
index 0c8ce2d8..11ab70bb 100644
--- a/sleekxmpp/xmlstream/matcher/id.py
+++ b/sleekxmpp/xmlstream/matcher/id.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.xmlstream.matcher.id
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
from sleekxmpp.xmlstream.matcher.base import MatcherBase
@@ -14,19 +17,13 @@ class MatcherId(MatcherBase):
"""
The ID matcher selects stanzas that have the same stanza 'id'
interface value as the desired ID.
-
- Methods:
- match -- Overrides MatcherBase.match.
"""
def match(self, xml):
- """
- Compare the given stanza's 'id' attribute to the stored
- id value.
-
- Overrides MatcherBase.match.
+ """Compare the given stanza's ``'id'`` attribute to the stored
+ ``id`` value.
- Arguments:
- xml -- The stanza to compare against.
+ :param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+ stanza to compare against.
"""
return xml['id'] == self._criteria
diff --git a/sleekxmpp/xmlstream/matcher/stanzapath.py b/sleekxmpp/xmlstream/matcher/stanzapath.py
index f8ff283d..61c5332c 100644
--- a/sleekxmpp/xmlstream/matcher/stanzapath.py
+++ b/sleekxmpp/xmlstream/matcher/stanzapath.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.xmlstream.matcher.stanzapath
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
from sleekxmpp.xmlstream.matcher.base import MatcherBase
@@ -15,24 +18,17 @@ class StanzaPath(MatcherBase):
The StanzaPath matcher selects stanzas that match a given "stanza path",
which is similar to a normal XPath except that it uses the interfaces and
plugins of the stanza instead of the actual, underlying XML.
-
- In most cases, the stanza path and XPath should be identical, but be
- aware that differences may occur.
-
- Methods:
- match -- Overrides MatcherBase.match.
"""
def match(self, stanza):
"""
Compare a stanza against a "stanza path". A stanza path is similar to
an XPath expression, but uses the stanza's interfaces and plugins
- instead of the underlying XML. For most cases, the stanza path and
- XPath should be identical, but be aware that differences may occur.
-
- Overrides MatcherBase.match.
+ instead of the underlying XML. See the documentation for the stanza
+ :meth:`~sleekxmpp.xmlstream.stanzabase.ElementBase.match()` method
+ for more information.
- Arguments:
- stanza -- The stanza object to compare against.
+ :param stanza: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+ stanza to compare against.
"""
return stanza.match(self._criteria)
diff --git a/sleekxmpp/xmlstream/matcher/xmlmask.py b/sleekxmpp/xmlstream/matcher/xmlmask.py
index 53ccc9ba..7977e767 100644
--- a/sleekxmpp/xmlstream/matcher/xmlmask.py
+++ b/sleekxmpp/xmlstream/matcher/xmlmask.py
@@ -30,66 +30,59 @@ class MatchXMLMask(MatcherBase):
XML pattern, or mask. For example, message stanzas with body elements
could be matched using the mask:
+ .. code-block:: xml
+
<message xmlns="jabber:client"><body /></message>
- Use of XMLMask is discouraged, and XPath or StanzaPath should be used
- instead.
+ Use of XMLMask is discouraged, and
+ :class:`~sleekxmpp.xmlstream.matcher.xpath.MatchXPath` or
+ :class:`~sleekxmpp.xmlstream.matcher.stanzapath.StanzaPath`
+ should be used instead.
The use of namespaces in the mask comparison is controlled by
- IGNORE_NS. Setting IGNORE_NS to True will disable namespace based matching
- for ALL XMLMask matchers.
+ ``IGNORE_NS``. Setting ``IGNORE_NS`` to ``True`` will disable namespace
+ based matching for ALL XMLMask matchers.
- Methods:
- match -- Overrides MatcherBase.match.
- setDefaultNS -- Set the default namespace for the mask.
+ :param criteria: Either an :class:`~xml.etree.ElementTree.Element` XML
+ object or XML string to use as a mask.
"""
def __init__(self, criteria):
- """
- Create a new XMLMask matcher.
-
- Arguments:
- criteria -- Either an XML object or XML string to use as a mask.
- """
MatcherBase.__init__(self, criteria)
if isinstance(criteria, str):
self._criteria = ET.fromstring(self._criteria)
self.default_ns = 'jabber:client'
def setDefaultNS(self, ns):
- """
- Set the default namespace to use during comparisons.
+ """Set the default namespace to use during comparisons.
- Arguments:
- ns -- The new namespace to use as the default.
+ :param ns: The new namespace to use as the default.
"""
self.default_ns = ns
def match(self, xml):
- """
- Compare a stanza object or XML object against the stored XML mask.
+ """Compare a stanza object or XML object against the stored XML mask.
Overrides MatcherBase.match.
- Arguments:
- xml -- The stanza object or XML object to compare against.
+ :param xml: The stanza object or XML object to compare against.
"""
if hasattr(xml, 'xml'):
xml = xml.xml
return self._mask_cmp(xml, self._criteria, True)
def _mask_cmp(self, source, mask, use_ns=False, default_ns='__no_ns__'):
- """
- Compare an XML object against an XML mask.
-
- Arguments:
- source -- The XML object to compare against the mask.
- mask -- The XML object serving as the mask.
- use_ns -- Indicates if namespaces should be respected during
- the comparison.
- default_ns -- The default namespace to apply to elements that
- do not have a specified namespace.
- Defaults to "__no_ns__".
+ """Compare an XML object against an XML mask.
+
+ :param source: The :class:`~xml.etree.ElementTree.Element` XML object
+ to compare against the mask.
+ :param mask: The :class:`~xml.etree.ElementTree.Element` XML object
+ serving as the mask.
+ :param use_ns: Indicates if namespaces should be respected during
+ the comparison.
+ :default_ns: The default namespace to apply to elements that
+ do not have a specified namespace.
+ Defaults to ``"__no_ns__"``.
"""
use_ns = not IGNORE_NS
@@ -102,8 +95,7 @@ class MatchXMLMask(MatcherBase):
try:
mask = ET.fromstring(mask)
except ExpatError:
- log.warning("Expat error: %s\nIn parsing: %s" % ('', mask))
-
+ log.warning("Expat error: %s\nIn parsing: %s", '', mask)
if not use_ns:
# Compare the element without using namespaces.
source_tag = source.tag.split('}', 1)[-1]
@@ -149,14 +141,13 @@ class MatchXMLMask(MatcherBase):
return True
def _get_child(self, xml, tag):
- """
- Return a child element given its tag, ignoring namespace values.
+ """Return a child element given its tag, ignoring namespace values.
- Returns None if the child was not found.
+ Returns ``None`` if the child was not found.
- Arguments:
- xml -- The XML object to search for the given child tag.
- tag -- The name of the subelement to find.
+ :param xml: The :class:`~xml.etree.ElementTree.Element` XML object
+ to search for the given child tag.
+ :param tag: The name of the subelement to find.
"""
tag = tag.split('}')[-1]
try:
diff --git a/sleekxmpp/xmlstream/matcher/xpath.py b/sleekxmpp/xmlstream/matcher/xpath.py
index 669c9f16..b6af0609 100644
--- a/sleekxmpp/xmlstream/matcher/xpath.py
+++ b/sleekxmpp/xmlstream/matcher/xpath.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.xmlstream.matcher.xpath
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
from sleekxmpp.xmlstream.stanzabase import ET
@@ -22,30 +25,34 @@ class MatchXPath(MatcherBase):
The XPath matcher selects stanzas whose XML contents matches a given
XPath expression.
- Note that using this matcher may not produce expected behavior when using
- attribute selectors. For Python 2.6 and 3.1, the ElementTree find method
- does not support the use of attribute selectors. If you need to support
- Python 2.6 or 3.1, it might be more useful to use a StanzaPath matcher.
+ .. warning::
- If the value of IGNORE_NS is set to true, then XPath expressions will
- be matched without using namespaces.
+ Using this matcher may not produce expected behavior when using
+ attribute selectors. For Python 2.6 and 3.1, the ElementTree
+ :meth:`~xml.etree.ElementTree.Element.find()` method does
+ not support the use of attribute selectors. If you need to
+ support Python 2.6 or 3.1, it might be more useful to use a
+ :class:`~sleekxmpp.xmlstream.matcher.stanzapath.StanzaPath` matcher.
- Methods:
- match -- Overrides MatcherBase.match.
+ If the value of :data:`IGNORE_NS` is set to ``True``, then XPath
+ expressions will be matched without using namespaces.
"""
def match(self, xml):
"""
Compare a stanza's XML contents to an XPath expression.
- If the value of IGNORE_NS is set to true, then XPath expressions
- will be matched without using namespaces.
+ If the value of :data:`IGNORE_NS` is set to ``True``, then XPath
+ expressions will be matched without using namespaces.
+
+ .. warning::
- Note that in Python 2.6 and 3.1 the ElementTree find method does
- not support attribute selectors in the XPath expression.
+ In Python 2.6 and 3.1 the ElementTree
+ :meth:`~xml.etree.ElementTree.Element.find()` method does not
+ support attribute selectors in the XPath expression.
- Arguments:
- xml -- The stanza object to compare against.
+ :param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+ stanza to compare against.
"""
if hasattr(xml, 'xml'):
xml = xml.xml
diff --git a/sleekxmpp/xmlstream/scheduler.py b/sleekxmpp/xmlstream/scheduler.py
index 58219257..4a6f073f 100644
--- a/sleekxmpp/xmlstream/scheduler.py
+++ b/sleekxmpp/xmlstream/scheduler.py
@@ -1,9 +1,15 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.xmlstream.scheduler
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ This module provides a task scheduler that works better
+ with SleekXMPP's threading usage than the stock version.
+
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
import time
@@ -24,50 +30,47 @@ class Task(object):
A scheduled task that will be executed by the scheduler
after a given time interval has passed.
- Attributes:
- name -- The name of the task.
- seconds -- The number of seconds to wait before executing.
- callback -- The function to execute.
- args -- The arguments to pass to the callback.
- kwargs -- The keyword arguments to pass to the callback.
- repeat -- Indicates if the task should repeat.
- Defaults to False.
- qpointer -- A pointer to an event queue for queuing callback
+ :param string name: The name of the task.
+ :param int seconds: The number of seconds to wait before executing.
+ :param callback: The function to execute.
+ :param tuple args: The arguments to pass to the callback.
+ :param dict kwargs: The keyword arguments to pass to the callback.
+ :param bool repeat: Indicates if the task should repeat.
+ Defaults to ``False``.
+ :param pointer: A pointer to an event queue for queuing callback
execution instead of executing immediately.
-
- Methods:
- run -- Either queue or execute the callback.
- reset -- Reset the task's timer.
"""
def __init__(self, name, seconds, callback, args=None,
kwargs=None, repeat=False, qpointer=None):
- """
- Create a new task.
-
- Arguments:
- name -- The name of the task.
- seconds -- The number of seconds to wait before executing.
- callback -- The function to execute.
- args -- The arguments to pass to the callback.
- kwargs -- The keyword arguments to pass to the callback.
- repeat -- Indicates if the task should repeat.
- Defaults to False.
- qpointer -- A pointer to an event queue for queuing callback
- execution instead of executing immediately.
- """
+ #: The name of the task.
self.name = name
+
+ #: The number of seconds to wait before executing.
self.seconds = seconds
+
+ #: The function to execute once enough time has passed.
self.callback = callback
+
+ #: The arguments to pass to :attr:`callback`.
self.args = args or tuple()
+
+ #: The keyword arguments to pass to :attr:`callback`.
self.kwargs = kwargs or {}
+
+ #: Indicates if the task should repeat after executing,
+ #: using the same :attr:`seconds` delay.
self.repeat = repeat
+
+ #: The time when the task should execute next.
self.next = time.time() + self.seconds
+
+ #: The main event queue, which allows for callbacks to
+ #: be queued for execution instead of executing immediately.
self.qpointer = qpointer
def run(self):
- """
- Execute the task's callback.
+ """Execute the task's callback.
If an event queue was supplied, place the callback in the queue;
otherwise, execute the callback immediately.
@@ -81,9 +84,7 @@ class Task(object):
return self.repeat
def reset(self):
- """
- Reset the task's timer so that it will repeat.
- """
+ """Reset the task's timer so that it will repeat."""
self.next = time.time() + self.seconds
@@ -93,48 +94,42 @@ class Scheduler(object):
A threaded scheduler that allows for updates mid-execution unlike the
scheduler in the standard library.
- http://docs.python.org/library/sched.html#module-sched
-
- Attributes:
- addq -- A queue storing added tasks.
- schedule -- A list of tasks in order of execution times.
- thread -- If threaded, the thread processing the schedule.
- run -- Indicates if the scheduler is running.
- stop -- Threading event indicating if the main process
- has been stopped.
- Methods:
- add -- Add a new task to the schedule.
- process -- Process and schedule tasks.
- quit -- Stop the scheduler.
+ Based on: http://docs.python.org/library/sched.html#module-sched
+
+ :param parentstop: An :class:`~threading.Event` to signal stopping
+ the scheduler.
"""
def __init__(self, parentstop=None):
- """
- Create a new scheduler.
-
- Arguments:
- parentstop -- A threading event indicating if the main process has
- been stopped.
- """
+ #: A queue for storing tasks
self.addq = queue.Queue()
+
+ #: A list of tasks in order of execution time.
self.schedule = []
+
+ #: If running in threaded mode, this will be the thread processing
+ #: the schedule.
self.thread = None
+
+ #: A flag indicating that the scheduler is running.
self.run = False
+
+ #: An :class:`~threading.Event` instance for signalling to stop
+ #: the scheduler.
self.stop = parentstop
+
+ #: Lock for accessing the task queue.
self.schedule_lock = threading.RLock()
def process(self, threaded=True):
- """
- Begin accepting and processing scheduled tasks.
+ """Begin accepting and processing scheduled tasks.
- Arguments:
- threaded -- Indicates if the scheduler should execute in its own
- thread. Defaults to True.
+ :param bool threaded: Indicates if the scheduler should execute
+ in its own thread. Defaults to ``True``.
"""
if threaded:
- self.thread = threading.Thread(name='sheduler_process',
+ self.thread = threading.Thread(name='scheduler_process',
target=self._process)
- self.thread.daemon = True
self.thread.start()
else:
self._process()
@@ -184,18 +179,16 @@ class Scheduler(object):
def add(self, name, seconds, callback, args=None,
kwargs=None, repeat=False, qpointer=None):
- """
- Schedule a new task.
-
- Arguments:
- name -- The name of the task.
- seconds -- The number of seconds to wait before executing.
- callback -- The function to execute.
- args -- The arguments to pass to the callback.
- kwargs -- The keyword arguments to pass to the callback.
- repeat -- Indicates if the task should repeat.
- Defaults to False.
- qpointer -- A pointer to an event queue for queuing callback
+ """Schedule a new task.
+
+ :param string name: The name of the task.
+ :param int seconds: The number of seconds to wait before executing.
+ :param callback: The function to execute.
+ :param tuple args: The arguments to pass to the callback.
+ :param dict kwargs: The keyword arguments to pass to the callback.
+ :param bool repeat: Indicates if the task should repeat.
+ Defaults to ``False``.
+ :param pointer: A pointer to an event queue for queuing callback
execution instead of executing immediately.
"""
try:
@@ -212,12 +205,10 @@ class Scheduler(object):
self.schedule_lock.release()
def remove(self, name):
- """
- Remove a scheduled task ahead of schedule, and without
+ """Remove a scheduled task ahead of schedule, and without
executing it.
- Arguments:
- name -- The name of the task to remove.
+ :param string name: The name of the task to remove.
"""
try:
self.schedule_lock.acquire()
diff --git a/sleekxmpp/xmlstream/stanzabase.py b/sleekxmpp/xmlstream/stanzabase.py
index 1ff89554..389fe20c 100644
--- a/sleekxmpp/xmlstream/stanzabase.py
+++ b/sleekxmpp/xmlstream/stanzabase.py
@@ -1,9 +1,15 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.xmlstream.stanzabase
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ This module implements a wrapper layer for XML objects
+ that allows them to be treated like dictionaries.
+
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
import copy
@@ -28,15 +34,22 @@ def register_stanza_plugin(stanza, plugin, iterable=False, overrides=False):
"""
Associate a stanza object as a plugin for another stanza.
- Arguments:
- stanza -- The class of the parent stanza.
- plugin -- The class of the plugin stanza.
- iterable -- Indicates if the plugin stanza should be
- included in the parent stanza's iterable
- 'substanzas' interface results.
- overrides -- Indicates if the plugin should be allowed
- to override the interface handlers for
- the parent stanza.
+ >>> from sleekxmpp.xmlstream import register_stanza_plugin
+ >>> register_stanza_plugin(Iq, CustomStanza)
+
+ :param class stanza: The class of the parent stanza.
+ :param class plugin: The class of the plugin stanza.
+ :param bool iterable: Indicates if the plugin stanza should be
+ included in the parent stanza's iterable
+ ``'substanzas'`` interface results.
+ :param bool overrides: Indicates if the plugin should be allowed
+ to override the interface handlers for
+ the parent stanza, based on the plugin's
+ ``overrides`` field.
+
+ .. versionadded:: 1.0-Beta1
+ Made ``register_stanza_plugin`` the default name. The prior
+ ``registerStanzaPlugin`` function name remains as an alias.
"""
tag = "{%s}%s" % (plugin.namespace, plugin.name)
@@ -73,23 +86,23 @@ class ElementBase(object):
to the Ruby XMPP library Blather's stanza implementation.
Stanzas are defined by their name, namespace, and interfaces. For
- example, a simplistic Message stanza could be defined as:
+ example, a simplistic Message stanza could be defined as::
- >>> class Message(ElementBase):
- ... name = "message"
- ... namespace = "jabber:client"
- ... interfaces = set(('to', 'from', 'type', 'body'))
- ... sub_interfaces = set(('body',))
+ >>> class Message(ElementBase):
+ ... name = "message"
+ ... namespace = "jabber:client"
+ ... interfaces = set(('to', 'from', 'type', 'body'))
+ ... sub_interfaces = set(('body',))
- The resulting Message stanza's contents may be accessed as so:
+ The resulting Message stanza's contents may be accessed as so::
- >>> message['to'] = "user@example.com"
- >>> message['body'] = "Hi!"
- >>> message['body']
- "Hi!"
- >>> del message['body']
- >>> message['body']
- ""
+ >>> message['to'] = "user@example.com"
+ >>> message['body'] = "Hi!"
+ >>> message['body']
+ "Hi!"
+ >>> del message['body']
+ >>> message['body']
+ ""
The interface values map to either custom access methods, stanza
XML attributes, or (if the interface is also in sub_interfaces) the
@@ -100,164 +113,171 @@ class ElementBase(object):
"Interface" is the titlecase version of the interface name.
Stanzas may be extended through the use of plugins. A plugin
- is simply a stanza that has a plugin_attrib value. For example:
+ is simply a stanza that has a plugin_attrib value. For example::
- >>> class MessagePlugin(ElementBase):
- ... name = "custom_plugin"
- ... namespace = "custom"
- ... interfaces = set(('useful_thing', 'custom'))
- ... plugin_attrib = "custom"
+ >>> class MessagePlugin(ElementBase):
+ ... name = "custom_plugin"
+ ... namespace = "custom"
+ ... interfaces = set(('useful_thing', 'custom'))
+ ... plugin_attrib = "custom"
The plugin stanza class must be associated with its intended
- container stanza by using register_stanza_plugin as so:
+ container stanza by using register_stanza_plugin as so::
- >>> register_stanza_plugin(Message, MessagePlugin)
+ >>> register_stanza_plugin(Message, MessagePlugin)
The plugin may then be accessed as if it were built-in to the parent
- stanza.
+ stanza::
- >>> message['custom']['useful_thing'] = 'foo'
+ >>> message['custom']['useful_thing'] = 'foo'
If a plugin provides an interface that is the same as the plugin's
plugin_attrib value, then the plugin's interface may be assigned
directly from the parent stanza, as shown below, but retrieving
- information will require all interfaces to be used, as so:
+ information will require all interfaces to be used, as so::
- >>> message['custom'] = 'bar' # Same as using message['custom']['custom']
- >>> message['custom']['custom'] # Must use all interfaces
- 'bar'
+ >>> message['custom'] = 'bar' # Same as using message['custom']['custom']
+ >>> message['custom']['custom'] # Must use all interfaces
+ 'bar'
- If the plugin sets the value is_extension = True, then both setting
+ If the plugin sets :attr:`is_extension` to ``True``, then both setting
and getting an interface value that is the same as the plugin's
- plugin_attrib value will work, as so:
-
- >>> message['custom'] = 'bar' # Using is_extension=True
- >>> message['custom']
- 'bar'
-
-
- Class Attributes:
- name -- The name of the stanza's main element.
- namespace -- The namespace of the stanza's main element.
- interfaces -- A set of attribute and element names that may
- be accessed using dictionary syntax.
- sub_interfaces -- A subset of the set of interfaces which map
- to subelements instead of attributes.
- subitem -- A set of stanza classes which are allowed to
- be added as substanzas. Deprecated version
- of plugin_iterables.
- overrides -- A list of interfaces prepended with 'get_',
- 'set_', or 'del_'. If the stanza is registered
- as a plugin with overrides=True, then the
- parent's interface handlers will be
- overridden by the plugin's matching handler.
- types -- A set of generic type attribute values.
- tag -- The namespaced name of the stanza's root
- element. Example: "{foo_ns}bar"
- plugin_attrib -- The interface name that the stanza uses to be
- accessed as a plugin from another stanza.
- plugin_attrib_map -- A mapping of plugin attribute names with the
- associated plugin stanza classes.
- plugin_iterables -- A set of stanza classes which are allowed to
- be added as substanzas.
- plugin_overrides -- A mapping of interfaces prepended with 'get_',
- 'set_' or 'del_' to plugin attrib names. Allows
- a plugin to override the behaviour of a parent
- stanza's interface handlers.
- plugin_tag_map -- A mapping of plugin stanza tag names with
- the associated plugin stanza classes.
- is_extension -- When True, allows the stanza to provide one
- additional interface to the parent stanza,
- extending the interfaces supported by the
- parent. Defaults to False.
- xml_ns -- The XML namespace,
- http://www.w3.org/XML/1998/namespace,
- for use with xml:lang values.
-
- Instance Attributes:
- xml -- The stanza's XML contents.
- parent -- The parent stanza of this stanza.
- plugins -- A map of enabled plugin names with the
- initialized plugin stanza objects.
- values -- A dictionary of the stanza's interfaces
- and interface values, including plugins.
-
- Class Methods
- tag_name -- Return the namespaced version of the stanza's
- root element's name.
-
- Methods:
- setup -- Initialize the stanza's XML contents.
- enable -- Instantiate a stanza plugin.
- Alias for init_plugin.
- init_plugin -- Instantiate a stanza plugin.
- _get_stanza_values -- Return a dictionary of stanza interfaces and
- their values.
- _set_stanza_values -- Set stanza interface values given a dictionary
- of interfaces and values.
- __getitem__ -- Return the value of a stanza interface.
- __setitem__ -- Set the value of a stanza interface.
- __delitem__ -- Remove the value of a stanza interface.
- _set_attr -- Set an attribute value of the main
- stanza element.
- _del_attr -- Remove an attribute from the main
- stanza element.
- _get_attr -- Return an attribute's value from the main
- stanza element.
- _get_sub_text -- Return the text contents of a subelement.
- _set_sub_text -- Set the text contents of a subelement.
- _del_sub -- Remove a subelement.
- match -- Compare the stanza against an XPath expression.
- find -- Return subelement matching an XPath expression.
- findall -- Return subelements matching an XPath expression.
- get -- Return the value of a stanza interface, with an
- optional default value.
- keys -- Return the set of interface names accepted by
- the stanza.
- append -- Add XML content or a substanza to the stanza.
- appendxml -- Add XML content to the stanza.
- pop -- Remove a substanza.
- next -- Return the next iterable substanza.
- clear -- Reset the stanza's XML contents.
- _fix_ns -- Apply the stanza's namespace to non-namespaced
- elements in an XPath expression.
+ plugin_attrib value will work, as so::
+
+ >>> message['custom'] = 'bar' # Using is_extension=True
+ >>> message['custom']
+ 'bar'
+
+
+ :param xml: Initialize the stanza object with an existing XML object.
+ :param parent: Optionally specify a parent stanza object will will
+ contain this substanza.
"""
+ #: The XML tag name of the element, not including any namespace
+ #: prefixes. For example, an :class:`ElementBase` object for ``<message />``
+ #: would use ``name = 'message'``.
name = 'stanza'
- plugin_attrib = 'plugin'
+
+ #: The XML namespace for the element. Given ``<foo xmlns="bar" />``,
+ #: then ``namespace = "bar"`` should be used. The default namespace
+ #: is ``jabber:client`` since this is being used in an XMPP library.
namespace = 'jabber:client'
+
+ #: For :class:`ElementBase` subclasses which are intended to be used
+ #: as plugins, the ``plugin_attrib`` value defines the plugin name.
+ #: Plugins may be accessed by using the ``plugin_attrib`` value as
+ #: the interface. An example using ``plugin_attrib = 'foo'``:
+ #:
+ #: register_stanza_plugin(Message, FooPlugin)
+ #: msg = Message()
+ #: msg['foo']['an_interface_from_the_foo_plugin']
+ plugin_attrib = 'plugin'
+
+ #: The set of keys that the stanza provides for accessing and
+ #: manipulating the underlying XML object. This set may be augmented
+ #: with the :attr:`plugin_attrib` value of any registered
+ #: stanza plugins.
interfaces = set(('type', 'to', 'from', 'id', 'payload'))
- types = set(('get', 'set', 'error', None, 'unavailable', 'normal', 'chat'))
+
+ #: A subset of :attr:`interfaces` which maps interfaces to direct
+ #: subelements of the underlying XML object. Using this set, the text
+ #: of these subelements may be set, retrieved, or removed without
+ #: needing to define custom methods.
sub_interfaces = tuple()
- overrides = {}
- plugin_attrib_map = {}
+
+ #: In some cases you may wish to override the behaviour of one of the
+ #: parent stanza's interfaces. The ``overrides`` list specifies the
+ #: interface name and access method to be overridden. For example,
+ #: to override setting the parent's ``'condition'`` interface you
+ #: would use::
+ #:
+ #: overrides = ['set_condition']
+ #:
+ #: Getting and deleting the ``'condition'`` interface would not
+ #: be affected.
+ #:
+ #: .. versionadded:: 1.0-Beta5
+ overrides = []
+
+ #: If you need to add a new interface to an existing stanza, you
+ #: can create a plugin and set ``is_extension = True``. Be sure
+ #: to set the :attr:`plugin_attrib` value to the desired interface
+ #: name, and that it is the only interface listed in
+ #: :attr:`interfaces`. Requests for the new interface from the
+ #: parent stanza will be passed to the plugin directly.
+ #:
+ #: .. versionadded:: 1.0-Beta5
+ is_extension = False
+
+ #: A map of interface operations to the overriding functions.
+ #: For example, after overriding the ``set`` operation for
+ #: the interface ``body``, :attr:`plugin_overrides` would be::
+ #:
+ #: {'set_body': <some function>}
+ #:
+ #: .. versionadded: 1.0-Beta5
plugin_overrides = {}
- plugin_iterables = set()
+
+ #: A mapping of the :attr:`plugin_attrib` values of registered
+ #: plugins to their respective classes.
+ plugin_attrib_map = {}
+
+ #: A mapping of root element tag names (in ``'{namespace}elementname'``
+ #: format) to the plugin classes responsible for them.
plugin_tag_map = {}
+
+ #: The set of stanza classes that can be iterated over using
+ #: the 'substanzas' interface. Classes are added to this set
+ #: when registering a plugin with ``iterable=True``::
+ #:
+ #: register_stanza_plugin(DiscoInfo, DiscoItem, iterable=True)
+ #:
+ #: .. versionadded:: 1.0-Beta5
+ plugin_iterables = set()
+
+ #: A deprecated version of :attr:`plugin_iterables` that remains
+ #: for backward compatibility. It required a parent stanza to
+ #: know beforehand what stanza classes would be iterable::
+ #:
+ #: class DiscoItem(ElementBase):
+ #: ...
+ #:
+ #: class DiscoInfo(ElementBase):
+ #: subitem = (DiscoItem, )
+ #: ...
+ #:
+ #: .. deprecated:: 1.0-Beta5
subitem = set()
- is_extension = False
+
+ #: The default XML namespace: ``http://www.w3.org/XML/1998/namespace``.
xml_ns = 'http://www.w3.org/XML/1998/namespace'
def __init__(self, xml=None, parent=None):
- """
- Create a new stanza object.
+ self._index = 0
- Arguments:
- xml -- Initialize the stanza with optional existing XML.
- parent -- Optional stanza object that contains this stanza.
- """
+ #: The underlying XML object for the stanza. It is a standard
+ #: :class:`xml.etree.cElementTree` object.
self.xml = xml
+
+ #: An ordered dictionary of plugin stanzas, mapped by their
+ #: :attr:`plugin_attrib` value.
self.plugins = OrderedDict()
+
+ #: A list of child stanzas whose class is included in
+ #: :attr:`plugin_iterables`.
self.iterables = []
- self._index = 0
+
+ #: The name of the tag for the stanza's root element. It is the
+ #: same as calling :meth:`tag_name()` and is formatted as
+ #: ``'{namespace}elementname'``.
self.tag = self.tag_name()
- if parent is None:
- self.parent = None
- else:
- self.parent = weakref.ref(parent)
- ElementBase.values = property(ElementBase._get_stanza_values,
- ElementBase._set_stanza_values)
+ #: A :class:`weakref.weakref` to the parent stanza, if there is one.
+ #: If not, then :attr:`parent` is ``None``.
+ self.parent = None
+ if parent is not None:
+ self.parent = weakref.ref(parent)
if self.subitem is not None:
for sub in self.subitem:
@@ -270,23 +290,21 @@ class ElementBase(object):
# Initialize values using provided XML
for child in self.xml.getchildren():
if child.tag in self.plugin_tag_map:
- plugin = self.plugin_tag_map[child.tag]
- self.plugins[plugin.plugin_attrib] = plugin(child, self)
- for sub in self.plugin_iterables:
- if child.tag == "{%s}%s" % (sub.namespace, sub.name):
- self.iterables.append(sub(child, self))
- break
+ plugin_class = self.plugin_tag_map[child.tag]
+ plugin = plugin_class(child, self)
+ self.plugins[plugin.plugin_attrib] = plugin
+ if plugin_class in self.plugin_iterables:
+ self.iterables.append(plugin)
def setup(self, xml=None):
- """
- Initialize the stanza's XML contents.
+ """Initialize the stanza's XML contents.
- Will return True if XML was generated according to the stanza's
- definition.
+ Will return ``True`` if XML was generated according to the stanza's
+ definition instead of building a stanza object from an existing
+ XML object.
- Arguments:
- xml -- Optional XML object to use for the stanza's content
- instead of generating XML.
+ :param xml: An existing XML object to use for the stanza's content
+ instead of generating new XML.
"""
if self.xml is None:
self.xml = xml
@@ -310,33 +328,47 @@ class ElementBase(object):
return False
def enable(self, attrib):
- """
- Enable and initialize a stanza plugin.
+ """Enable and initialize a stanza plugin.
- Alias for init_plugin.
+ Alias for :meth:`init_plugin`.
- Arguments:
- attrib -- The stanza interface for the plugin.
+ :param string attrib: The :attr:`plugin_attrib` value of the
+ plugin to enable.
"""
return self.init_plugin(attrib)
def init_plugin(self, attrib):
- """
- Enable and initialize a stanza plugin.
+ """Enable and initialize a stanza plugin.
- Arguments:
- attrib -- The stanza interface for the plugin.
+ :param string attrib: The :attr:`plugin_attrib` value of the
+ plugin to enable.
"""
if attrib not in self.plugins:
plugin_class = self.plugin_attrib_map[attrib]
- self.plugins[attrib] = plugin_class(parent=self)
+ plugin = plugin_class(parent=self)
+ self.plugins[attrib] = plugin
+ if plugin_class in self.plugin_iterables:
+ self.iterables.append(plugin)
return self
def _get_stanza_values(self):
- """
- Return a dictionary of the stanza's interface values.
+ """Return A JSON/dictionary version of the XML content
+ exposed through the stanza's interfaces::
- Stanza plugin values are included as nested dictionaries.
+ >>> msg = Message()
+ >>> msg.values
+ {'body': '', 'from': , 'mucnick': '', 'mucroom': '',
+ 'to': , 'type': 'normal', 'id': '', 'subject': ''}
+
+ Likewise, assigning to :attr:`values` will change the XML
+ content::
+
+ >>> msg = Message()
+ >>> msg.values = {'body': 'Hi!', 'to': 'user@example.com'}
+ >>> msg
+ '<message to="user@example.com"><body>Hi!</body></message>'
+
+ .. versionadded:: 1.0-Beta1
"""
values = {}
for interface in self.interfaces:
@@ -352,15 +384,15 @@ class ElementBase(object):
return values
def _set_stanza_values(self, values):
- """
- Set multiple stanza interface values using a dictionary.
+ """Set multiple stanza interface values using a dictionary.
Stanza plugin values may be set using nested dictionaries.
- Arguments:
- values -- A dictionary mapping stanza interface with values.
- Plugin interfaces may accept a nested dictionary that
- will be used recursively.
+ :param values: A dictionary mapping stanza interface with values.
+ Plugin interfaces may accept a nested dictionary that
+ will be used recursively.
+
+ .. versionadded:: 1.0-Beta1
"""
iterable_interfaces = [p.plugin_attrib for \
p in self.plugin_iterables]
@@ -393,30 +425,31 @@ class ElementBase(object):
return self
def __getitem__(self, attrib):
- """
- Return the value of a stanza interface using dictionary-like syntax.
+ """Return the value of a stanza interface using dict-like syntax.
+
+ Example::
- Example:
>>> msg['body']
'Message contents'
Stanza interfaces are typically mapped directly to the underlying XML
- object, but can be overridden by the presence of a get_attrib method
- (or get_foo where the interface is named foo, etc).
+ object, but can be overridden by the presence of a ``get_attrib``
+ method (or ``get_foo`` where the interface is named ``'foo'``, etc).
The search order for interface value retrieval for an interface
- named 'foo' is:
- 1. The list of substanzas.
- 2. The result of calling the get_foo override handler.
- 3. The result of calling get_foo.
- 4. The result of calling getFoo.
- 5. The contents of the foo subelement, if foo is a sub interface.
- 6. The value of the foo attribute of the XML object.
- 7. The plugin named 'foo'
+ named ``'foo'`` is:
+
+ 1. The list of substanzas (``'substanzas'``)
+ 2. The result of calling the ``get_foo`` override handler.
+ 3. The result of calling ``get_foo``.
+ 4. The result of calling ``getFoo``.
+ 5. The contents of the ``foo`` subelement, if ``foo`` is listed
+ in :attr:`sub_interfaces`.
+ 6. The value of the ``foo`` attribute of the XML object.
+ 7. The plugin named ``'foo'``
8. An empty string.
- Arguments:
- attrib -- The name of the requested stanza interface.
+ :param string attrib: The name of the requested stanza interface.
"""
if attrib == 'substanzas':
return self.iterables
@@ -452,33 +485,34 @@ class ElementBase(object):
return ''
def __setitem__(self, attrib, value):
- """
- Set the value of a stanza interface using dictionary-like syntax.
+ """Set the value of a stanza interface using dictionary-like syntax.
+
+ Example::
- Example:
>>> msg['body'] = "Hi!"
>>> msg['body']
'Hi!'
Stanza interfaces are typically mapped directly to the underlying XML
- object, but can be overridden by the presence of a set_attrib method
- (or set_foo where the interface is named foo, etc).
+ object, but can be overridden by the presence of a ``set_attrib``
+ method (or ``set_foo`` where the interface is named ``'foo'``, etc).
The effect of interface value assignment for an interface
- named 'foo' will be one of:
+ named ``'foo'`` will be one of:
+
1. Delete the interface's contents if the value is None.
- 2. Call the set_foo override handler, if it exists.
- 3. Call set_foo, if it exists.
- 4. Call setFoo, if it exists.
- 5. Set the text of a foo element, if foo is in sub_interfaces.
- 6. Set the value of a top level XML attribute name foo.
- 7. Attempt to pass value to a plugin named foo using the plugin's
- foo interface.
+ 2. Call the ``set_foo`` override handler, if it exists.
+ 3. Call ``set_foo``, if it exists.
+ 4. Call ``setFoo``, if it exists.
+ 5. Set the text of a ``foo`` element, if ``'foo'`` is
+ in :attr:`sub_interfaces`.
+ 6. Set the value of a top level XML attribute named ``foo``.
+ 7. Attempt to pass the value to a plugin named ``'foo'`` using
+ the plugin's ``'foo'`` interface.
8. Do nothing.
- Arguments:
- attrib -- The name of the stanza interface to modify.
- value -- The new value of the stanza interface.
+ :param string attrib: The name of the stanza interface to modify.
+ :param value: The new value of the stanza interface.
"""
if attrib in self.interfaces:
if value is not None:
@@ -513,10 +547,10 @@ class ElementBase(object):
return self
def __delitem__(self, attrib):
- """
- Delete the value of a stanza interface using dictionary-like syntax.
+ """Delete the value of a stanza interface using dict-like syntax.
+
+ Example::
- Example:
>>> msg['body'] = "Hi!"
>>> msg['body']
'Hi!'
@@ -525,21 +559,22 @@ class ElementBase(object):
''
Stanza interfaces are typically mapped directly to the underlyig XML
- object, but can be overridden by the presence of a del_attrib method
- (or del_foo where the interface is named foo, etc).
+ object, but can be overridden by the presence of a ``del_attrib``
+ method (or ``del_foo`` where the interface is named ``'foo'``, etc).
- The effect of deleting a stanza interface value named foo will be
+ The effect of deleting a stanza interface value named ``foo`` will be
one of:
- 1. Call del_foo override handler, if it exists.
- 2. Call del_foo, if it exists.
- 3. Call delFoo, if it exists.
- 4. Delete foo element, if foo is in sub_interfaces.
- 5. Delete top level XML attribute named foo.
- 6. Remove the foo plugin, if it was loaded.
+
+ 1. Call ``del_foo`` override handler, if it exists.
+ 2. Call ``del_foo``, if it exists.
+ 3. Call ``delFoo``, if it exists.
+ 4. Delete ``foo`` element, if ``'foo'`` is in
+ :attr:`sub_interfaces`.
+ 5. Delete top level XML attribute named ``foo``.
+ 6. Remove the ``foo`` plugin, if it was loaded.
7. Do nothing.
- Arguments:
- attrib -- The name of the affected stanza interface.
+ :param attrib: The name of the affected stanza interface.
"""
if attrib in self.interfaces:
del_method = "del_%s" % attrib.lower()
@@ -576,16 +611,14 @@ class ElementBase(object):
return self
def _set_attr(self, name, value):
- """
- Set the value of a top level attribute of the underlying XML object.
+ """Set the value of a top level attribute of the XML object.
If the new value is None or an empty string, then the attribute will
be removed.
- Arguments:
- name -- The name of the attribute.
- value -- The new value of the attribute, or None or '' to
- remove it.
+ :param name: The name of the attribute.
+ :param value: The new value of the attribute, or None or '' to
+ remove it.
"""
if value is None or value == '':
self.__delitem__(name)
@@ -593,43 +626,36 @@ class ElementBase(object):
self.xml.attrib[name] = value
def _del_attr(self, name):
- """
- Remove a top level attribute of the underlying XML object.
+ """Remove a top level attribute of the XML object.
- Arguments:
- name -- The name of the attribute.
+ :param name: The name of the attribute.
"""
if name in self.xml.attrib:
del self.xml.attrib[name]
def _get_attr(self, name, default=''):
- """
- Return the value of a top level attribute of the underlying
- XML object.
+ """Return the value of a top level attribute of the XML object.
In case the attribute has not been set, a default value can be
returned instead. An empty string is returned if no other default
is supplied.
- Arguments:
- name -- The name of the attribute.
- default -- Optional value to return if the attribute has not
- been set. An empty string is returned otherwise.
+ :param name: The name of the attribute.
+ :param default: Optional value to return if the attribute has not
+ been set. An empty string is returned otherwise.
"""
return self.xml.attrib.get(name, default)
def _get_sub_text(self, name, default=''):
- """
- Return the text contents of a sub element.
+ """Return the text contents of a sub element.
In case the element does not exist, or it has no textual content,
a default value can be returned instead. An empty string is returned
if no other default is supplied.
- Arguments:
- name -- The name or XPath expression of the element.
- default -- Optional default to return if the element does
- not exists. An empty string is returned otherwise.
+ :param name: The name or XPath expression of the element.
+ :param default: Optional default to return if the element does
+ not exists. An empty string is returned otherwise.
"""
name = self._fix_ns(name)
stanza = self.xml.find(name)
@@ -639,8 +665,7 @@ class ElementBase(object):
return stanza.text
def _set_sub_text(self, name, text=None, keep=False):
- """
- Set the text contents of a sub element.
+ """Set the text contents of a sub element.
In case the element does not exist, a element will be created,
and its text contents will be set.
@@ -648,13 +673,12 @@ class ElementBase(object):
If the text is set to an empty string, or None, then the
element will be removed, unless keep is set to True.
- Arguments:
- name -- The name or XPath expression of the element.
- text -- The new textual content of the element. If the text
- is an empty string or None, the element will be removed
- unless the parameter keep is True.
- keep -- Indicates if the element should be kept if its text is
- removed. Defaults to False.
+ :param name: The name or XPath expression of the element.
+ :param text: The new textual content of the element. If the text
+ is an empty string or None, the element will be removed
+ unless the parameter keep is True.
+ :param keep: Indicates if the element should be kept if its text is
+ removed. Defaults to False.
"""
path = self._fix_ns(name, split=True)
element = self.xml.find(name)
@@ -682,17 +706,15 @@ class ElementBase(object):
return element
def _del_sub(self, name, all=False):
- """
- Remove sub elements that match the given name or XPath.
+ """Remove sub elements that match the given name or XPath.
If the element is in a path, then any parent elements that become
empty after deleting the element may also be deleted if requested
by setting all=True.
- Arguments:
- name -- The name or XPath expression for the element(s) to remove.
- all -- If True, remove all empty elements in the path to the
- deleted element. Defaults to False.
+ :param name: The name or XPath expression for the element(s) to remove.
+ :param bool all: If True, remove all empty elements in the path to the
+ deleted element. Defaults to False.
"""
path = self._fix_ns(name, split=True)
original_target = path[-1]
@@ -720,19 +742,22 @@ class ElementBase(object):
return
def match(self, xpath):
- """
- Compare a stanza object with an XPath expression. If the XPath matches
- the contents of the stanza object, the match is successful.
+ """Compare a stanza object with an XPath-like expression.
+
+ If the XPath matches the contents of the stanza object, the match
+ is successful.
The XPath expression may include checks for stanza attributes.
- For example:
- presence@show=xa@priority=2/status
- Would match a presence stanza whose show value is set to 'xa', has a
- priority value of '2', and has a status element.
+ For example::
- Arguments:
- xpath -- The XPath expression to check against. It may be either a
- string or a list of element names with attribute checks.
+ 'presence@show=xa@priority=2/status'
+
+ Would match a presence stanza whose show value is set to ``'xa'``,
+ has a priority value of ``'2'``, and has a status element.
+
+ :param string xpath: The XPath expression to check against. It
+ may be either a string or a list of element
+ names with attribute checks.
"""
if isinstance(xpath, str):
xpath = self._fix_ns(xpath, split=True, propagate_ns=False)
@@ -781,44 +806,46 @@ class ElementBase(object):
return True
def find(self, xpath):
- """
- Find an XML object in this stanza given an XPath expression.
+ """Find an XML object in this stanza given an XPath expression.
Exposes ElementTree interface for backwards compatibility.
- Note that matching on attribute values is not supported in Python 2.6
- or Python 3.1
+ .. note::
- Arguments:
- xpath -- An XPath expression matching a single desired element.
+ Matching on attribute values is not supported in Python 2.6
+ or Python 3.1
+
+ :param string xpath: An XPath expression matching a single
+ desired element.
"""
return self.xml.find(xpath)
def findall(self, xpath):
- """
- Find multiple XML objects in this stanza given an XPath expression.
+ """Find multiple XML objects in this stanza given an XPath expression.
Exposes ElementTree interface for backwards compatibility.
- Note that matching on attribute values is not supported in Python 2.6
- or Python 3.1.
+ .. note::
- Arguments:
- xpath -- An XPath expression matching multiple desired elements.
+ Matching on attribute values is not supported in Python 2.6
+ or Python 3.1.
+
+ :param string xpath: An XPath expression matching multiple
+ desired elements.
"""
return self.xml.findall(xpath)
def get(self, key, default=None):
- """
- Return the value of a stanza interface. If the found value is None
- or an empty string, return the supplied default value.
+ """Return the value of a stanza interface.
+
+ If the found value is None or an empty string, return the supplied
+ default value.
Allows stanza objects to be used like dictionaries.
- Arguments:
- key -- The name of the stanza interface to check.
- default -- Value to return if the stanza interface has a value
- of None or "". Will default to returning None.
+ :param string key: The name of the stanza interface to check.
+ :param default: Value to return if the stanza interface has a value
+ of ``None`` or ``""``. Will default to returning None.
"""
value = self[key]
if value is None or value == '':
@@ -826,8 +853,7 @@ class ElementBase(object):
return value
def keys(self):
- """
- Return the names of all stanza interfaces provided by the
+ """Return the names of all stanza interfaces provided by the
stanza object.
Allows stanza objects to be used like dictionaries.
@@ -840,17 +866,15 @@ class ElementBase(object):
return out
def append(self, item):
- """
- Append either an XML object or a substanza to this stanza object.
+ """Append either an XML object or a substanza to this stanza object.
If a substanza object is appended, it will be added to the list
of iterable stanzas.
Allows stanza objects to be used like lists.
- Arguments:
- item -- Either an XML object or a stanza object to add to
- this stanza's contents.
+ :param item: Either an XML object or a stanza object to add to
+ this stanza's contents.
"""
if not isinstance(item, ElementBase):
if type(item) == XML_TYPE:
@@ -862,41 +886,34 @@ class ElementBase(object):
return self
def appendxml(self, xml):
- """
- Append an XML object to the stanza's XML.
+ """Append an XML object to the stanza's XML.
The added XML will not be included in the list of
iterable substanzas.
- Arguments:
- xml -- The XML object to add to the stanza.
+ :param XML xml: The XML object to add to the stanza.
"""
self.xml.append(xml)
return self
def pop(self, index=0):
- """
- Remove and return the last substanza in the list of
+ """Remove and return the last substanza in the list of
iterable substanzas.
Allows stanza objects to be used like lists.
- Arguments:
- index -- The index of the substanza to remove.
+ :param int index: The index of the substanza to remove.
"""
substanza = self.iterables.pop(index)
self.xml.remove(substanza.xml)
return substanza
def next(self):
- """
- Return the next iterable substanza.
- """
+ """Return the next iterable substanza."""
return self.__next__()
def clear(self):
- """
- Remove all XML element contents and plugins.
+ """Remove all XML element contents and plugins.
Any attribute values will be preserved.
"""
@@ -908,43 +925,44 @@ class ElementBase(object):
@classmethod
def tag_name(cls):
- """
- Return the namespaced name of the stanza's root element.
+ """Return the namespaced name of the stanza's root element.
+
+ The format for the tag name is::
+
+ '{namespace}elementname'
- For example, for the stanza <foo xmlns="bar" />,
- stanza.tag would return "{bar}foo".
+ For example, for the stanza ``<foo xmlns="bar" />``,
+ ``stanza.tag_name()`` would return ``"{bar}foo"``.
"""
return "{%s}%s" % (cls.namespace, cls.name)
@property
def attrib(self):
- """
- DEPRECATED
-
- For backwards compatibility, stanza.attrib returns the stanza itself.
+ """Return the stanza object itself.
Older implementations of stanza objects used XML objects directly,
- requiring the use of .attrib to access attribute values.
+ requiring the use of ``.attrib`` to access attribute values.
Use of the dictionary syntax with the stanza object itself for
accessing stanza interfaces is preferred.
+
+ .. deprecated:: 1.0
"""
return self
def _fix_ns(self, xpath, split=False, propagate_ns=True):
- """
- Apply the stanza's namespace to elements in an XPath expression.
-
- Arguments:
- xpath -- The XPath expression to fix with namespaces.
- split -- Indicates if the fixed XPath should be left as a
- list of element names with namespaces. Defaults to
- False, which returns a flat string path.
- propagate_ns -- Overrides propagating parent element namespaces
- to child elements. Useful if you wish to simply
- split an XPath that has non-specified namespaces,
- and child and parent namespaces are known not to
- always match. Defaults to True.
+ """Apply the stanza's namespace to elements in an XPath expression.
+
+ :param string xpath: The XPath expression to fix with namespaces.
+ :param bool split: Indicates if the fixed XPath should be left as a
+ list of element names with namespaces. Defaults to
+ False, which returns a flat string path.
+ :param bool propagate_ns: Overrides propagating parent element
+ namespaces to child elements. Useful if
+ you wish to simply split an XPath that has
+ non-specified namespaces, and child and
+ parent namespaces are known not to always
+ match. Defaults to True.
"""
fixed = []
# Split the XPath into a series of blocks, where a block
@@ -975,14 +993,12 @@ class ElementBase(object):
return '/'.join(fixed)
def __eq__(self, other):
- """
- Compare the stanza object with another to test for equality.
+ """Compare the stanza object with another to test for equality.
Stanzas are equal if their interfaces return the same values,
and if they are both instances of ElementBase.
- Arguments:
- other -- The stanza object to compare against.
+ :param ElementBase other: The stanza object to compare against.
"""
if not isinstance(other, ElementBase):
return False
@@ -1004,42 +1020,35 @@ class ElementBase(object):
return True
def __ne__(self, other):
- """
- Compare the stanza object with another to test for inequality.
+ """Compare the stanza object with another to test for inequality.
Stanzas are not equal if their interfaces return different values,
or if they are not both instances of ElementBase.
- Arguments:
- other -- The stanza object to compare against.
+ :param ElementBase other: The stanza object to compare against.
"""
return not self.__eq__(other)
def __bool__(self):
- """
- Stanza objects should be treated as True in boolean contexts.
+ """Stanza objects should be treated as True in boolean contexts.
Python 3.x version.
"""
return True
def __nonzero__(self):
- """
- Stanza objects should be treated as True in boolean contexts.
+ """Stanza objects should be treated as True in boolean contexts.
Python 2.x version.
"""
return True
def __len__(self):
- """
- Return the number of iterable substanzas contained in this stanza.
- """
+ """Return the number of iterable substanzas in this stanza."""
return len(self.iterables)
def __iter__(self):
- """
- Return an iterator object for iterating over the stanza's substanzas.
+ """Return an iterator object for the stanza's substanzas.
The iterator is the stanza object itself. Attempting to use two
iterators on the same stanza at the same time is discouraged.
@@ -1048,9 +1057,7 @@ class ElementBase(object):
return self
def __next__(self):
- """
- Return the next iterable substanza.
- """
+ """Return the next iterable substanza."""
self._index += 1
if self._index > len(self.iterables):
self._index = 0
@@ -1058,19 +1065,18 @@ class ElementBase(object):
return self.iterables[self._index - 1]
def __copy__(self):
- """
- Return a copy of the stanza object that does not share the same
+ """Return a copy of the stanza object that does not share the same
underlying XML object.
"""
return self.__class__(xml=copy.deepcopy(self.xml), parent=self.parent)
def __str__(self, top_level_ns=True):
- """
- Return a string serialization of the underlying XML object.
+ """Return a string serialization of the underlying XML object.
- Arguments:
- top_level_ns -- Display the top-most namespace.
- Defaults to True.
+ .. seealso:: :ref:`tostring`
+
+ :param bool top_level_ns: Display the top-most namespace.
+ Defaults to True.
"""
stanza_ns = '' if top_level_ns else self.namespace
return tostring(self.xml, xmlns='',
@@ -1078,72 +1084,54 @@ class ElementBase(object):
top_level=not top_level_ns)
def __repr__(self):
- """
- Use the stanza's serialized XML as its representation.
- """
+ """Use the stanza's serialized XML as its representation."""
return self.__str__()
class StanzaBase(ElementBase):
"""
- StanzaBase provides the foundation for all other stanza objects used by
- SleekXMPP, and defines a basic set of interfaces common to nearly
- all stanzas. These interfaces are the 'id', 'type', 'to', and 'from'
- attributes. An additional interface, 'payload', is available to access
- the XML contents of the stanza. Most stanza objects will provided more
- specific interfaces, however.
-
- Stanza Interface:
- from -- A JID object representing the sender's JID.
- id -- An optional id value that can be used to associate stanzas
- with their replies.
- payload -- The XML contents of the stanza.
- to -- A JID object representing the recipient's JID.
- type -- The type of stanza, typically will be 'normal', 'error',
- 'get', or 'set', etc.
-
- Attributes:
- stream -- The XMLStream instance that will handle sending this stanza.
-
- Methods:
- set_type -- Set the type of the stanza.
- get_to -- Return the stanza recipients JID.
- set_to -- Set the stanza recipient's JID.
- get_from -- Return the stanza sender's JID.
- set_from -- Set the stanza sender's JID.
- get_payload -- Return the stanza's XML contents.
- set_payload -- Append to the stanza's XML contents.
- del_payload -- Remove the stanza's XML contents.
- reply -- Reset the stanza and modify the 'to' and 'from'
- attributes to prepare for sending a reply.
- error -- Set the stanza's type to 'error'.
- unhandled -- Callback for when the stanza is not handled by a
- stream handler.
- exception -- Callback for if an exception is raised while
- handling the stanza.
- send -- Send the stanza using the stanza's stream.
+ StanzaBase provides the foundation for all other stanza objects used
+ by SleekXMPP, and defines a basic set of interfaces common to nearly
+ all stanzas. These interfaces are the ``'id'``, ``'type'``, ``'to'``,
+ and ``'from'`` attributes. An additional interface, ``'payload'``, is
+ available to access the XML contents of the stanza. Most stanza objects
+ will provided more specific interfaces, however.
+
+ **Stanza Interfaces:**
+
+ :id: An optional id value that can be used to associate stanzas
+ :to: A JID object representing the recipient's JID.
+ :from: A JID object representing the sender's JID.
+ with their replies.
+ :type: The type of stanza, typically will be ``'normal'``,
+ ``'error'``, ``'get'``, or ``'set'``, etc.
+ :payload: The XML contents of the stanza.
+
+ :param XMLStream stream: Optional :class:`sleekxmpp.xmlstream.XMLStream`
+ object responsible for sending this stanza.
+ :param XML xml: Optional XML contents to initialize stanza values.
+ :param string stype: Optional stanza type value.
+ :param sto: Optional string or :class:`sleekxmpp.xmlstream.JID`
+ object of the recipient's JID.
+ :param sfrom: Optional string or :class:`sleekxmpp.xmlstream.JID`
+ object of the sender's JID.
+ :param string sid: Optional ID value for the stanza.
"""
- name = 'stanza'
+ #: The default XMPP client namespace
namespace = 'jabber:client'
+
+ #: There is a small set of attributes which apply to all XMPP stanzas:
+ #: the stanza type, the to and from JIDs, the stanza ID, and, especially
+ #: in the case of an Iq stanza, a payload.
interfaces = set(('type', 'to', 'from', 'id', 'payload'))
+
+ #: A basic set of allowed values for the ``'type'`` interface.
types = set(('get', 'set', 'error', None, 'unavailable', 'normal', 'chat'))
- sub_interfaces = tuple()
def __init__(self, stream=None, xml=None, stype=None,
sto=None, sfrom=None, sid=None):
- """
- Create a new stanza.
-
- Arguments:
- stream -- Optional XMLStream responsible for sending this stanza.
- xml -- Optional XML contents to initialize stanza values.
- stype -- Optional stanza type value.
- sto -- Optional string or JID object of the recipient's JID.
- sfrom -- Optional string or JID object of the sender's JID.
- sid -- Optional ID value for the stanza.
- """
self.stream = stream
if stream is not None:
self.namespace = stream.default_ns
@@ -1157,38 +1145,34 @@ class StanzaBase(ElementBase):
self.tag = "{%s}%s" % (self.namespace, self.name)
def set_type(self, value):
- """
- Set the stanza's 'type' attribute.
+ """Set the stanza's ``'type'`` attribute.
- Only type values contained in StanzaBase.types are accepted.
+ Only type values contained in :attr:`types` are accepted.
- Arguments:
- value -- One of the values contained in StanzaBase.types
+ :param string value: One of the values contained in :attr:`types`
"""
if value in self.types:
self.xml.attrib['type'] = value
return self
def get_to(self):
- """Return the value of the stanza's 'to' attribute."""
+ """Return the value of the stanza's ``'to'`` attribute."""
return JID(self._get_attr('to'))
def set_to(self, value):
- """
- Set the 'to' attribute of the stanza.
+ """Set the ``'to'`` attribute of the stanza.
- Arguments:
- value -- A string or JID object representing the recipient's JID.
+ :param value: A string or :class:`sleekxmpp.xmlstream.JID` object
+ representing the recipient's JID.
"""
return self._set_attr('to', str(value))
def get_from(self):
- """Return the value of the stanza's 'from' attribute."""
+ """Return the value of the stanza's ``'from'`` attribute."""
return JID(self._get_attr('from'))
def set_from(self, value):
- """
- Set the 'from' attribute of the stanza.
+ """Set the 'from' attribute of the stanza.
Arguments:
from -- A string or JID object representing the sender's JID.
@@ -1200,12 +1184,10 @@ class StanzaBase(ElementBase):
return self.xml.getchildren()
def set_payload(self, value):
- """
- Add XML content to the stanza.
+ """Add XML content to the stanza.
- Arguments:
- value -- Either an XML or a stanza object, or a list
- of XML or stanza objects.
+ :param value: Either an XML or a stanza object, or a list
+ of XML or stanza objects.
"""
if not isinstance(value, list):
value = [value]
@@ -1219,16 +1201,17 @@ class StanzaBase(ElementBase):
return self
def reply(self, clear=True):
- """
- Swap the 'from' and 'to' attributes to prepare the stanza for
- sending a reply. If clear=True, then also remove the stanza's
+ """Prepare the stanza for sending a reply.
+
+ Swaps the ``'from'`` and ``'to'`` attributes.
+
+ If ``clear=True``, then also remove the stanza's
contents to make room for the reply content.
- For client streams, the 'from' attribute is removed.
+ For client streams, the ``'from'`` attribute is removed.
- Arguments:
- clear -- Indicates if the stanza's contents should be
- removed. Defaults to True
+ :param bool clear: Indicates if the stanza's contents should be
+ removed. Defaults to ``True``.
"""
# if it's a component, use from
if self.stream and hasattr(self.stream, "is_component") and \
@@ -1242,53 +1225,46 @@ class StanzaBase(ElementBase):
return self
def error(self):
- """Set the stanza's type to 'error'."""
+ """Set the stanza's type to ``'error'``."""
self['type'] = 'error'
return self
def unhandled(self):
- """
- Called when no handlers have been registered to process this
- stanza.
+ """Called if no handlers have been registered to process this stanza.
Meant to be overridden.
"""
pass
def exception(self, e):
- """
- Handle exceptions raised during stanza processing.
+ """Handle exceptions raised during stanza processing.
Meant to be overridden.
"""
- log.exception('Error handling {%s}%s stanza' % (self.namespace,
- self.name))
+ log.exception('Error handling {%s}%s stanza', self.namespace,
+ self.name)
def send(self, now=False):
- """
- Queue the stanza to be sent on the XML stream.
- Arguments:
- now -- Indicates if the queue should be skipped and the
- stanza sent immediately. Useful for stream
- initialization. Defaults to False.
+ """Queue the stanza to be sent on the XML stream.
+
+ :param bool now: Indicates if the queue should be skipped and the
+ stanza sent immediately. Useful for stream
+ initialization. Defaults to ``False``.
"""
self.stream.send_raw(self.__str__(), now=now)
def __copy__(self):
- """
- Return a copy of the stanza object that does not share the
+ """Return a copy of the stanza object that does not share the
same underlying XML object, but does share the same XML stream.
"""
return self.__class__(xml=copy.deepcopy(self.xml),
stream=self.stream)
def __str__(self, top_level_ns=False):
- """
- Serialize the stanza's XML to a string.
+ """Serialize the stanza's XML to a string.
- Arguments:
- top_level_ns -- Display the top-most namespace.
- Defaults to False.
+ :param bool top_level_ns: Display the top-most namespace.
+ Defaults to ``False``.
"""
stanza_ns = '' if top_level_ns else self.namespace
return tostring(self.xml, xmlns='',
@@ -1297,6 +1273,27 @@ class StanzaBase(ElementBase):
top_level=not top_level_ns)
+#: A JSON/dictionary version of the XML content exposed through
+#: the stanza interfaces::
+#:
+#: >>> msg = Message()
+#: >>> msg.values
+#: {'body': '', 'from': , 'mucnick': '', 'mucroom': '',
+#: 'to': , 'type': 'normal', 'id': '', 'subject': ''}
+#:
+#: Likewise, assigning to the :attr:`values` will change the XML
+#: content::
+#:
+#: >>> msg = Message()
+#: >>> msg.values = {'body': 'Hi!', 'to': 'user@example.com'}
+#: >>> msg
+#: '<message to="user@example.com"><body>Hi!</body></message>'
+#:
+#: Child stanzas are exposed as nested dictionaries.
+ElementBase.values = property(ElementBase._get_stanza_values,
+ ElementBase._set_stanza_values)
+
+
# To comply with PEP8, method names now use underscores.
# Deprecated method names are re-mapped for backwards compatibility.
ElementBase.initPlugin = ElementBase.init_plugin
diff --git a/sleekxmpp/xmlstream/tostring.py b/sleekxmpp/xmlstream/tostring.py
index f9674b15..8e729f79 100644
--- a/sleekxmpp/xmlstream/tostring.py
+++ b/sleekxmpp/xmlstream/tostring.py
@@ -1,9 +1,16 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.xmlstream.tostring
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ This module converts XML objects into Unicode strings and
+ intelligently includes namespaces only when necessary to
+ keep the output readable.
+
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
import sys
@@ -14,26 +21,28 @@ if sys.version_info < (3, 0):
def tostring(xml=None, xmlns='', stanza_ns='', stream=None,
outbuffer='', top_level=False):
- """
- Serialize an XML object to a Unicode string.
-
- If namespaces are provided using xmlns or stanza_ns, then elements
- that use those namespaces will not include the xmlns attribute in
- the output.
-
- Arguments:
- xml -- The XML object to serialize. If the value is None,
- then the XML object contained in this stanza
- object will be used.
- xmlns -- Optional namespace of an element wrapping the XML
- object.
- stanza_ns -- The namespace of the stanza object that contains
- the XML object.
- stream -- The XML stream that generated the XML object.
- outbuffer -- Optional buffer for storing serializations during
- recursive calls.
- top_level -- Indicates that the element is the outermost
- element.
+ """Serialize an XML object to a Unicode string.
+
+ If namespaces are provided using ``xmlns`` or ``stanza_ns``, then
+ elements that use those namespaces will not include the xmlns attribute
+ in the output.
+
+ :param XML xml: The XML object to serialize.
+ :param string xmlns: Optional namespace of an element wrapping the XML
+ object.
+ :param string stanza_ns: The namespace of the stanza object that contains
+ the XML object.
+ :param stream: The XML stream that generated the XML object.
+ :param string outbuffer: Optional buffer for storing serializations
+ during recursive calls.
+ :param bool top_level: Indicates that the element is the outermost
+ element.
+
+
+ :type xml: :py:class:`~xml.etree.ElementTree.Element`
+ :type stream: :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
+
+ :rtype: Unicode string
"""
# Add previous results to the start of the output.
output = [outbuffer]
@@ -102,11 +111,10 @@ def tostring(xml=None, xmlns='', stanza_ns='', stream=None,
def xml_escape(text):
- """
- Convert special characters in XML to escape sequences.
+ """Convert special characters in XML to escape sequences.
- Arguments:
- text -- The XML text to convert.
+ :param string text: The XML text to convert.
+ :rtype: Unicode string
"""
if sys.version_info < (3, 0):
if type(text) != types.UnicodeType:
diff --git a/sleekxmpp/xmlstream/xmlstream.py b/sleekxmpp/xmlstream/xmlstream.py
index b6d013b0..fb9f91bc 100644
--- a/sleekxmpp/xmlstream/xmlstream.py
+++ b/sleekxmpp/xmlstream/xmlstream.py
@@ -1,9 +1,16 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.xmlstream.xmlstream
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ This module provides the module for creating and
+ interacting with generic XML streams, along with
+ the necessary eventing infrastructure.
+
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
from __future__ import with_statement, unicode_literals
@@ -45,24 +52,35 @@ else:
DNSPYTHON = True
-# The time in seconds to wait before timing out waiting for response stanzas.
+#: The time in seconds to wait before timing out waiting for response stanzas.
RESPONSE_TIMEOUT = 30
-# The time in seconds to wait for events from the event queue, and also the
-# time between checks for the process stop signal.
+#: The time in seconds to wait for events from the event queue, and also the
+#: time between checks for the process stop signal.
WAIT_TIMEOUT = 1
-# The number of threads to use to handle XML stream events. This is not the
-# same as the number of custom event handling threads. HANDLER_THREADS must
-# be at least 1.
+#: The number of threads to use to handle XML stream events. This is not the
+#: same as the number of custom event handling threads.
+#: :data:`HANDLER_THREADS` must be at least 1. For Python implementations
+#: with a GIL, this should be left at 1, but for implemetnations without
+#: a GIL increasing this value can provide better performance.
HANDLER_THREADS = 1
-# Flag indicating if the SSL library is available for use.
+#: Flag indicating if the SSL library is available for use.
SSL_SUPPORT = True
-# Maximum time to delay between connection attempts is one hour.
+#: The time in seconds to delay between attempts to resend data
+#: after an SSL error.
+SSL_RETRY_DELAY = 0.5
+
+#: The maximum number of times to attempt resending data due to
+#: an SSL error.
+SSL_RETRY_MAX = 10
+
+#: Maximum time to delay between connection attempts is one hour.
RECONNECT_MAX_DELAY = 600
+
log = logging.getLogger(__name__)
@@ -85,115 +103,83 @@ class XMLStream(object):
streams should be complete and valid XML documents.
Three types of events are provided to manage the stream:
- Stream -- Triggered based on received stanzas, similar in concept
- to events in a SAX XML parser.
- Custom -- Triggered manually.
- Scheduled -- Triggered based on time delays.
+ :Stream: Triggered based on received stanzas, similar in concept
+ to events in a SAX XML parser.
+ :Custom: Triggered manually.
+ :Scheduled: Triggered based on time delays.
Typically, stanzas are first processed by a stream event handler which
will then trigger custom events to continue further processing,
especially since custom event handlers may run in individual threads.
-
- Attributes:
- address -- The hostname and port of the server.
- default_ns -- The default XML namespace that will be applied
- to all non-namespaced stanzas.
- event_queue -- A queue of stream, custom, and scheduled
- events to be processed.
- filesocket -- A filesocket created from the main connection socket.
- Required for ElementTree.iterparse.
- default_port -- Default port to connect to.
- namespace_map -- Optional mapping of namespaces to namespace prefixes.
- scheduler -- A scheduler object for triggering events
- after a given period of time.
- send_queue -- A queue of stanzas to be sent on the stream.
- socket -- The connection to the server.
- ssl_support -- Indicates if a SSL library is available for use.
- ssl_version -- The version of the SSL protocol to use.
- Defaults to ssl.PROTOCOL_TLSv1.
- ca_certs -- File path to a CA certificate to verify the
- server's identity.
- state -- A state machine for managing the stream's
- connection state.
- stream_footer -- The start tag and any attributes for the stream's
- root element.
- stream_header -- The closing tag of the stream's root element.
- use_ssl -- Flag indicating if SSL should be used.
- use_tls -- Flag indicating if TLS should be used.
- use_proxy -- Flag indicating that an HTTP Proxy should be used.
- stop -- threading Event used to stop all threads.
- proxy_config -- An optional dictionary with the following entries:
- host -- The host offering proxy services.
- port -- The port for the proxy service.
- username -- Optional username for the proxy.
- password -- Optional password for the proxy.
-
- auto_reconnect -- Flag to determine whether we auto reconnect.
- reconnect_max_delay -- Maximum time to delay between connection
- attempts. Defaults to RECONNECT_MAX_DELAY,
- which is one hour.
- dns_answers -- List of dns answers not yet used to connect.
-
- Methods:
- add_event_handler -- Add a handler for a custom event.
- add_handler -- Shortcut method for registerHandler.
- connect -- Connect to the given server.
- del_event_handler -- Remove a handler for a custom event.
- disconnect -- Disconnect from the server and terminate
- processing.
- event -- Trigger a custom event.
- get_id -- Return the current stream ID.
- incoming_filter -- Optionally filter stanzas before processing.
- new_id -- Generate a new, unique ID value.
- process -- Read XML stanzas from the stream and apply
- matching stream handlers.
- reconnect -- Reestablish a connection to the server.
- register_handler -- Add a handler for a stream event.
- register_stanza -- Add a new stanza object type that may appear
- as a direct child of the stream's root.
- remove_handler -- Remove a stream handler.
- remove_stanza -- Remove a stanza object type.
- schedule -- Schedule an event handler to execute after a
- given delay.
- send -- Send a stanza object on the stream.
- send_raw -- Send a raw string on the stream.
- send_xml -- Send an XML string on the stream.
- set_socket -- Set the stream's socket and generate a new
- filesocket.
- start_stream_handler -- Perform any stream initialization such
- as handshakes.
- start_tls -- Establish a TLS connection and restart
- the stream.
+ :param socket: Use an existing socket for the stream. Defaults to
+ ``None`` to generate a new socket.
+ :param string host: The name of the target server.
+ :param int port: The port to use for the connection. Defaults to 0.
"""
def __init__(self, socket=None, host='', port=0):
- """
- Establish a new XML stream.
-
- Arguments:
- socket -- Use an existing socket for the stream.
- Defaults to None to generate a new socket.
- host -- The name of the target server.
- Defaults to the empty string.
- port -- The port to use for the connection.
- Defaults to 0.
- """
+ #: Flag indicating if the SSL library is available for use.
self.ssl_support = SSL_SUPPORT
+
+ #: Most XMPP servers support TLSv1, but OpenFire in particular
+ #: does not work well with it. For OpenFire, set
+ #: :attr:`ssl_version` to use ``SSLv23``::
+ #:
+ #: import ssl
+ #: xmpp.ssl_version = ssl.PROTOCOL_SSLv23
self.ssl_version = ssl.PROTOCOL_TLSv1
+
+ #: Path to a file containing certificates for verifying the
+ #: server SSL certificate. A non-``None`` value will trigger
+ #: certificate checking.
+ #:
+ #: .. note::
+ #:
+ #: On Mac OS X, certificates in the system keyring will
+ #: be consulted, even if they are not in the provided file.
self.ca_certs = None
+ #: The time in seconds to wait for events from the event queue,
+ #: and also the time between checks for the process stop signal.
self.wait_timeout = WAIT_TIMEOUT
+
+ #: The time in seconds to wait before timing out waiting
+ #: for response stanzas.
self.response_timeout = RESPONSE_TIMEOUT
+
+ #: The current amount to time to delay attempting to reconnect.
+ #: This value doubles (with some jitter) with each failed
+ #: connection attempt up to :attr:`reconnect_max_delay` seconds.
self.reconnect_delay = None
+
+ #: Maximum time to delay between connection attempts is one hour.
self.reconnect_max_delay = RECONNECT_MAX_DELAY
+ #: The time in seconds to delay between attempts to resend data
+ #: after an SSL error.
+ self.ssl_retry_max = SSL_RETRY_MAX
+
+ #: The maximum number of times to attempt resending data due to
+ #: an SSL error.
+ self.ssl_retry_delay = SSL_RETRY_DELAY
+
+ #: The connection state machine tracks if the stream is
+ #: ``'connected'`` or ``'disconnected'``.
self.state = StateMachine(('disconnected', 'connected'))
self.state._set_state('disconnected')
+ #: The default port to return when querying DNS records.
self.default_port = int(port)
+
+ #: The domain to try when querying DNS records.
self.default_domain = ''
+
+ #: The desired, or actual, address of the connected server.
self.address = (host, int(port))
+
+ #: A file-like wrapper for the socket for use with the
+ #: :mod:`~xml.etree.ElementTree` module.
self.filesocket = None
self.set_socket(socket)
@@ -202,31 +188,79 @@ class XMLStream(object):
else:
self.socket_class = Socket.socket
+ #: Enable connecting to the server directly over SSL, in
+ #: particular when the service provides two ports: one for
+ #: non-SSL traffic and another for SSL traffic.
self.use_ssl = False
+
+ #: Enable connecting to the service without using SSL
+ #: immediately, but allow upgrading the connection later
+ #: to use SSL.
self.use_tls = False
+
+ #: If set to ``True``, attempt to connect through an HTTP
+ #: proxy based on the settings in :attr:`proxy_config`.
self.use_proxy = False
+ #: An optional dictionary of proxy settings. It may provide:
+ #: :host: The host offering proxy services.
+ #: :port: The port for the proxy service.
+ #: :username: Optional username for accessing the proxy.
+ #: :password: Optional password for accessing the proxy.
self.proxy_config = {}
+ #: The default namespace of the stream content, not of the
+ #: stream wrapper itself.
self.default_ns = ''
+
+ #: The namespace of the enveloping stream element.
self.stream_ns = ''
+
+ #: The default opening tag for the stream element.
self.stream_header = "<stream>"
+
+ #: The default closing tag for the stream element.
self.stream_footer = "</stream>"
+ #: If ``True``, periodically send a whitespace character over the
+ #: wire to keep the connection alive. Mainly useful for connections
+ #: traversing NAT.
self.whitespace_keepalive = True
+
+ #: The default interval between keepalive signals when
+ #: :attr:`whitespace_keepalive` is enabled.
self.whitespace_keepalive_interval = 300
+ #: An :class:`~threading.Event` to signal that the application
+ #: is stopping, and that all threads should shutdown.
self.stop = threading.Event()
+
+ #: An :class:`~threading.Event` to signal receiving a closing
+ #: stream tag from the server.
self.stream_end_event = threading.Event()
self.stream_end_event.set()
+
+ #: An :class:`~threading.Event` to signal the start of a stream
+ #: session. Until this event fires, the send queue is not used
+ #: and data is sent immediately over the wire.
self.session_started_event = threading.Event()
+
+ #: The default time in seconds to wait for a session to start
+ #: after connecting before reconnecting and trying again.
self.session_timeout = 45
+ #: A queue of stream, custom, and scheduled events to be processed.
self.event_queue = queue.Queue()
+
+ #: A queue of string data to be sent over the stream.
self.send_queue = queue.Queue()
- self.__failed_send_stanza = None
+
+ #: A :class:`~sleekxmpp.xmlstream.scheduler.Scheduler` instance for
+ #: executing callbacks in the future based on time delays.
self.scheduler = Scheduler(self.stop)
+ self.__failed_send_stanza = None
+ #: A mapping of XML namespaces to well-known prefixes.
self.namespace_map = {StanzaBase.xml_ns: 'xml'}
self.__thread = {}
@@ -238,7 +272,18 @@ class XMLStream(object):
self._id = 0
self._id_lock = threading.Lock()
+ #: The :attr:`auto_reconnnect` setting controls whether or not
+ #: the stream will be restarted in the event of an error.
self.auto_reconnect = True
+
+ #: The :attr:`disconnect_wait` setting is the default value
+ #: for controlling if the system waits for the send queue to
+ #: empty before ending the stream. This may be overridden by
+ #: passing ``wait=True`` or ``wait=False`` to :meth:`disconnect`.
+ #: The default :attr:`disconnect_wait` value is ``False``.
+ self.disconnect_wait = False
+
+ #: A list of DNS results that have not yet been tried.
self.dns_answers = []
self.add_event_handler('connected', self._handle_connected)
@@ -246,17 +291,16 @@ class XMLStream(object):
self.add_event_handler('session_end', self._end_keepalive)
def use_signals(self, signals=None):
- """
- Register signal handlers for SIGHUP and SIGTERM, if possible,
- which will raise a "killed" event when the application is
- terminated.
+ """Register signal handlers for ``SIGHUP`` and ``SIGTERM``.
+
+ By using signals, a ``'killed'`` event will be raised when the
+ application is terminated.
If a signal handler already existed, it will be executed first,
- before the "killed" event is raised.
+ before the ``'killed'`` event is raised.
- Arguments:
- signals -- A list of signal names to be monitored.
- Defaults to ['SIGHUP', 'SIGTERM'].
+ :param list signals: A list of signal names to be monitored.
+ Defaults to ``['SIGHUP', 'SIGTERM']``.
"""
if signals is None:
signals = ['SIGHUP', 'SIGTERM']
@@ -272,7 +316,7 @@ class XMLStream(object):
def handle_kill(signum, frame):
"""
Capture kill event and disconnect cleanly after first
- spawning the "killed" event.
+ spawning the ``'killed'`` event.
"""
if signum in existing_handlers and \
@@ -293,8 +337,7 @@ class XMLStream(object):
"SleekXMPP is not running from a main thread.")
def new_id(self):
- """
- Generate and return a new stream ID in hexadecimal form.
+ """Generate and return a new stream ID in hexadecimal form.
Many stanzas, handlers, or matchers may require unique
ID values. Using this method ensures that all new ID values
@@ -305,26 +348,25 @@ class XMLStream(object):
return self.get_id()
def get_id(self):
- """
- Return the current unique stream ID in hexadecimal form.
- """
+ """Return the current unique stream ID in hexadecimal form."""
return "%X" % self._id
def connect(self, host='', port=0, use_ssl=False,
use_tls=True, reattempt=True):
- """
- Create a new socket and connect to the server.
-
- Setting reattempt to True will cause connection attempts to be made
- every second until a successful connection is established.
-
- Arguments:
- host -- The name of the desired server for the connection.
- port -- Port to connect to on the server.
- use_ssl -- Flag indicating if SSL should be used.
- use_tls -- Flag indicating if TLS should be used.
- reattempt -- Flag indicating if the socket should reconnect
- after disconnections.
+ """Create a new socket and connect to the server.
+
+ Setting ``reattempt`` to ``True`` will cause connection attempts to
+ be made every second until a successful connection is established.
+
+ :param host: The name of the desired server for the connection.
+ :param port: Port to connect to on the server.
+ :param use_ssl: Flag indicating if SSL should be used by connecting
+ directly to a port using SSL.
+ :param use_tls: Flag indicating if TLS should be used, allowing for
+ connecting to a port without using SSL immediately and
+ later upgrading the connection.
+ :param reattempt: Flag indicating if the socket should reconnect
+ after disconnections.
"""
if host and port:
self.address = (host, int(port))
@@ -343,7 +385,7 @@ class XMLStream(object):
# is established.
connected = self.state.transition('disconnected', 'connected',
func=self._connect)
- while reattempt and not connected:
+ while reattempt and not connected and not self.stop.is_set():
connected = self.state.transition('disconnected', 'connected',
func=self._connect)
return connected
@@ -362,8 +404,18 @@ class XMLStream(object):
else:
delay = min(self.reconnect_delay * 2, self.reconnect_max_delay)
delay = random.normalvariate(delay, delay * 0.1)
- log.debug('Waiting %s seconds before connecting.' % delay)
- time.sleep(delay)
+ log.debug('Waiting %s seconds before connecting.', delay)
+ elapsed = 0
+ try:
+ while elapsed < delay and not self.stop.is_set():
+ time.sleep(0.1)
+ elapsed += 0.1
+ except KeyboardInterrupt:
+ self.stop.set()
+ return False
+ except SystemExit:
+ self.stop.set()
+ return False
if self.use_proxy:
connected = self._connect_proxy()
@@ -391,7 +443,7 @@ class XMLStream(object):
try:
if not self.use_proxy:
- log.debug("Connecting to %s:%s" % self.address)
+ log.debug("Connecting to %s:%s", *self.address)
self.socket.connect(self.address)
self.set_socket(self.socket, ignore=True)
@@ -402,8 +454,8 @@ class XMLStream(object):
except Socket.error as serr:
error_msg = "Could not connect to %s:%s. Socket Error #%s: %s"
self.event('socket_error', serr)
- log.error(error_msg % (self.address[0], self.address[1],
- serr.errno, serr.strerror))
+ log.error(error_msg, self.address[0], self.address[1],
+ serr.errno, serr.strerror)
self.reconnect_delay = delay
return False
@@ -435,18 +487,18 @@ class XMLStream(object):
headers = '\r\n'.join(headers) + '\r\n\r\n'
try:
- log.debug("Connecting to proxy: %s:%s" % address)
+ log.debug("Connecting to proxy: %s:%s", address)
self.socket.connect(address)
self.send_raw(headers, now=True)
resp = ''
- while '\r\n\r\n' not in resp:
+ while '\r\n\r\n' not in resp and not self.stop.is_set():
resp += self.socket.recv(1024).decode('utf-8')
- log.debug('RECV: %s' % resp)
+ log.debug('RECV: %s', resp)
lines = resp.split('\r\n')
if '200' not in lines[0]:
self.event('proxy_error', resp)
- log.error('Proxy Error: %s' % lines[0])
+ log.error('Proxy Error: %s', lines[0])
return False
# Proxy connection established, continue connecting
@@ -455,8 +507,8 @@ class XMLStream(object):
except Socket.error as serr:
error_msg = "Could not connect to %s:%s. Socket Error #%s: %s"
self.event('socket_error', serr)
- log.error(error_msg % (self.address[0], self.address[1],
- serr.errno, serr.strerror))
+ log.error(error_msg, self.address[0], self.address[1],
+ serr.errno, serr.strerror)
return False
def _handle_connected(self, event=None):
@@ -466,42 +518,48 @@ class XMLStream(object):
"""
def _handle_session_timeout():
- if not self.session_started_event.isSet():
+ if not self.session_started_event.is_set():
log.debug("Session start has taken more " + \
- "than %d seconds" % self.session_timeout)
+ "than %d seconds", self.session_timeout)
self.disconnect(reconnect=self.auto_reconnect)
self.schedule("Session timeout check",
self.session_timeout,
_handle_session_timeout)
-
- def disconnect(self, reconnect=False, wait=False):
- """
- Terminate processing and close the XML streams.
+ def disconnect(self, reconnect=False, wait=None):
+ """Terminate processing and close the XML streams.
Optionally, the connection may be reconnected and
resume processing afterwards.
If the disconnect should take place after all items
- in the send queue have been sent, use wait=True. However,
- take note: If you are constantly adding items to the queue
- such that it is never empty, then the disconnect will
- not occur and the call will continue to block.
-
- Arguments:
- reconnect -- Flag indicating if the connection
- and processing should be restarted.
- Defaults to False.
- wait -- Flag indicating if the send queue should
- be emptied before disconnecting.
- """
- self.state.transition('connected', 'disconnected', wait=0.0,
+ in the send queue have been sent, use ``wait=True``.
+
+ .. warning::
+
+ If you are constantly adding items to the queue
+ such that it is never empty, then the disconnect will
+ not occur and the call will continue to block.
+
+ :param reconnect: Flag indicating if the connection
+ and processing should be restarted.
+ Defaults to ``False``.
+ :param wait: Flag indicating if the send queue should
+ be emptied before disconnecting, overriding
+ :attr:`disconnect_wait`.
+ """
+ self.state.transition('connected', 'disconnected',
func=self._disconnect, args=(reconnect, wait))
- def _disconnect(self, reconnect=False, wait=False):
+ def _disconnect(self, reconnect=False, wait=None):
+ self.event('session_end', direct=True)
+
# Wait for the send queue to empty.
- if wait:
+ if wait is not None:
+ if wait:
+ self.send_queue.join()
+ elif self.disconnect_wait:
self.send_queue.join()
# Send the end of stream marker.
@@ -510,7 +568,7 @@ class XMLStream(object):
# Wait for confirmation that the stream was
# closed in the other direction.
self.auto_reconnect = reconnect
- log.debug('Waiting for %s from server' % self.stream_footer)
+ log.debug('Waiting for %s from server', self.stream_footer)
self.stream_end_event.wait(4)
if not self.auto_reconnect:
self.stop.set()
@@ -522,35 +580,33 @@ class XMLStream(object):
self.event('socket_error', serr)
finally:
#clear your application state
- self.event('session_end', direct=True)
self.event("disconnected", direct=True)
return True
- def reconnect(self):
- """
- Reset the stream's state and reconnect to the server.
- """
+ def reconnect(self, reattempt=True):
+ """Reset the stream's state and reconnect to the server."""
log.debug("reconnecting...")
- self.state.transition('connected', 'disconnected', wait=2.0,
- func=self._disconnect, args=(True,))
+ if self.state.ensure('connected'):
+ self.state.transition('connected', 'disconnected', wait=2.0,
+ func=self._disconnect, args=(True,))
log.debug("connecting...")
connected = self.state.transition('disconnected', 'connected',
wait=2.0, func=self._connect)
- while not connected:
+ while reattempt and not connected and not self.stop.is_set():
connected = self.state.transition('disconnected', 'connected',
wait=2.0, func=self._connect)
+ connected = connected or self.state.ensure('connected')
return connected
def set_socket(self, socket, ignore=False):
- """
- Set the socket to use for the stream.
+ """Set the socket to use for the stream.
The filesocket will be recreated as well.
- Arguments:
- socket -- The new socket to use.
- ignore -- don't set the state
+ :param socket: The new socket object to use.
+ :param bool ignore: If ``True``, don't set the connection
+ state to ``'connected'``.
"""
self.socket = socket
if socket is not None:
@@ -568,8 +624,7 @@ class XMLStream(object):
self.state._set_state('connected')
def configure_socket(self):
- """
- Set timeout and other options for self.socket.
+ """Set timeout and other options for self.socket.
Meant to be overridden.
"""
@@ -577,31 +632,30 @@ class XMLStream(object):
def configure_dns(self, resolver, domain=None, port=None):
"""
- Configure and set options for a dns.resolver.Resolver
+ Configure and set options for a :class:`~dns.resolver.Resolver`
instance, and other DNS related tasks. For example, you
- can also check Socket.getaddrinfo to see if you need to
- call out to libresolv.so.2 to run res_init().
+ can also check :meth:`~socket.socket.getaddrinfo` to see
+ if you need to call out to ``libresolv.so.2`` to
+ run ``res_init()``.
Meant to be overridden.
- Arguments:
- resolver -- A dns.resolver.Resolver instance, or None
- if dnspython is not installed.
- domain -- The initial domain under consideration.
- port -- The initial port under consideration.
+ :param resolver: A :class:`~dns.resolver.Resolver` instance
+ or ``None`` if ``dnspython`` is not installed.
+ :param domain: The initial domain under consideration.
+ :param port: The initial port under consideration.
"""
pass
def start_tls(self):
- """
- Perform handshakes for TLS.
+ """Perform handshakes for TLS.
If the handshake is successful, the XML stream will need
to be restarted.
"""
if self.ssl_support:
log.info("Negotiating TLS")
- log.info("Using SSL version: %s" % str(self.ssl_version))
+ log.info("Using SSL version: %s", str(self.ssl_version))
if self.ca_certs is None:
cert_policy = ssl.CERT_NONE
else:
@@ -627,13 +681,14 @@ class XMLStream(object):
return False
def _start_keepalive(self, event):
- """
- Begin sending whitespace periodically to keep the connection alive.
+ """Begin sending whitespace periodically to keep the connection alive.
+
+ May be disabled by setting::
- May be disabled by setting:
self.whitespace_keepalive = False
- The keepalive interval can be set using:
+ The keepalive interval can be set using::
+
self.whitespace_keepalive_interval = 300
"""
@@ -651,18 +706,18 @@ class XMLStream(object):
self.scheduler.remove('Whitespace Keepalive')
def start_stream_handler(self, xml):
- """
- Perform any initialization actions, such as handshakes, once the
- stream header has been sent.
+ """Perform any initialization actions, such as handshakes,
+ once the stream header has been sent.
Meant to be overridden.
"""
pass
def register_stanza(self, stanza_class):
- """
- Add a stanza object class as a known root stanza. A root stanza is
- one that appears as a direct child of the stream's root element.
+ """Add a stanza object class as a known root stanza.
+
+ A root stanza is one that appears as a direct child of the stream's
+ root element.
Stanzas that appear as substanzas of a root stanza do not need to
be registered here. That is done using register_stanza_plugin() from
@@ -672,15 +727,15 @@ class XMLStream(object):
stanza objects, but may still be processed using handlers and
matchers.
- Arguments:
- stanza_class -- The top-level stanza object's class.
+ :param stanza_class: The top-level stanza object's class.
"""
self.__root_stanza.append(stanza_class)
def remove_stanza(self, stanza_class):
- """
- Remove a stanza from being a known root stanza. A root stanza is
- one that appears as a direct child of the stream's root element.
+ """Remove a stanza from being a known root stanza.
+
+ A root stanza is one that appears as a direct child of the stream's
+ root element.
Stanzas that are not registered will not be converted into
stanza objects, but may still be processed using handlers and
@@ -690,22 +745,24 @@ class XMLStream(object):
def add_handler(self, mask, pointer, name=None, disposable=False,
threaded=False, filter=False, instream=False):
- """
- A shortcut method for registering a handler using XML masks.
-
- Arguments:
- mask -- An XML snippet matching the structure of the
- stanzas that will be passed to this handler.
- pointer -- The handler function itself.
- name -- A unique name for the handler. A name will
- be generated if one is not provided.
- disposable -- Indicates if the handler should be discarded
- after one use.
- threaded -- Deprecated. Remains for backwards compatibility.
- filter -- Deprecated. Remains for backwards compatibility.
- instream -- Indicates if the handler should execute during
- stream processing and not during normal event
- processing.
+ """A shortcut method for registering a handler using XML masks.
+
+ The use of :meth:`register_handler()` is preferred.
+
+ :param mask: An XML snippet matching the structure of the
+ stanzas that will be passed to this handler.
+ :param pointer: The handler function itself.
+ :parm name: A unique name for the handler. A name will
+ be generated if one is not provided.
+ :param disposable: Indicates if the handler should be discarded
+ after one use.
+ :param threaded: **DEPRECATED**.
+ Remains for backwards compatibility.
+ :param filter: **DEPRECATED**.
+ Remains for backwards compatibility.
+ :param instream: Indicates if the handler should execute during
+ stream processing and not during normal event
+ processing.
"""
# To prevent circular dependencies, we must load the matcher
# and handler classes here.
@@ -716,23 +773,20 @@ class XMLStream(object):
once=disposable, instream=instream))
def register_handler(self, handler, before=None, after=None):
- """
- Add a stream event handler that will be executed when a matching
+ """Add a stream event handler that will be executed when a matching
stanza is received.
- Arguments:
- handler -- The handler object to execute.
+ :param handler: The :class:`~sleekxmpp.xmlstream.handler.base.BaseHandler`
+ derived object to execute.
"""
if handler.stream is None:
self.__handlers.append(handler)
handler.stream = weakref.ref(self)
def remove_handler(self, name):
- """
- Remove any stream event handlers with the given name.
+ """Remove any stream event handlers with the given name.
- Arguments:
- name -- The name of the handler.
+ :param name: The name of the handler.
"""
idx = 0
for handler in self.__handlers:
@@ -743,12 +797,10 @@ class XMLStream(object):
return False
def get_dns_records(self, domain, port=None):
- """
- Get the DNS records for a domain.
+ """Get the DNS records for a domain.
- Arguments:
- domain -- The domain in question.
- port -- If the results don't include a port, use this one.
+ :param domain: The domain in question.
+ :param port: If the results don't include a port, use this one.
"""
if port is None:
port = self.default_port
@@ -759,11 +811,11 @@ class XMLStream(object):
try:
answers = resolver.query(domain, dns.rdatatype.A)
except (dns.resolver.NXDOMAIN, dns.resolver.NoAnswer):
- log.warning("No A records for %s" % domain)
+ log.warning("No A records for %s", domain)
return [((domain, port), 0, 0)]
except dns.exception.Timeout:
log.warning("DNS resolution timed out " + \
- "for A record of %s" % domain)
+ "for A record of %s", domain)
return [((domain, port), 0, 0)]
else:
return [((ans.address, port), 0, 0) for ans in answers]
@@ -774,14 +826,13 @@ class XMLStream(object):
return [((domain, port), 0, 0)]
def pick_dns_answer(self, domain, port=None):
- """
- Pick a server and port from DNS answers.
+ """Pick a server and port from DNS answers.
+
Gets DNS answers if none available.
Removes used answer from available answers.
- Arguments:
- domain -- The domain in question.
- port -- If the results don't include a port, use this one.
+ :param domain: The domain in question.
+ :param port: If the results don't include a port, use this one.
"""
if not self.dns_answers:
self.dns_answers = self.get_dns_records(domain, port)
@@ -808,35 +859,31 @@ class XMLStream(object):
if self.dns_answers[0] == address:
break
self.dns_answers.pop(idx)
- log.debug("Trying to connect to %s:%s" % address)
+ log.debug("Trying to connect to %s:%s", *address)
return address
def add_event_handler(self, name, pointer,
threaded=False, disposable=False):
- """
- Add a custom event handler that will be executed whenever
+ """Add a custom event handler that will be executed whenever
its event is manually triggered.
- Arguments:
- name -- The name of the event that will trigger
- this handler.
- pointer -- The function to execute.
- threaded -- If set to True, the handler will execute
- in its own thread. Defaults to False.
- disposable -- If set to True, the handler will be
- discarded after one use. Defaults to False.
+ :param name: The name of the event that will trigger
+ this handler.
+ :param pointer: The function to execute.
+ :param threaded: If set to ``True``, the handler will execute
+ in its own thread. Defaults to ``False``.
+ :param disposable: If set to ``True``, the handler will be
+ discarded after one use. Defaults to ``False``.
"""
if not name in self.__event_handlers:
self.__event_handlers[name] = []
self.__event_handlers[name].append((pointer, threaded, disposable))
def del_event_handler(self, name, pointer):
- """
- Remove a function as a handler for an event.
+ """Remove a function as a handler for an event.
- Arguments:
- name -- The name of the event.
- pointer -- The function to remove as a handler.
+ :param name: The name of the event.
+ :param pointer: The function to remove as a handler.
"""
if not name in self.__event_handlers:
return
@@ -851,42 +898,42 @@ class XMLStream(object):
self.__event_handlers[name]))
def event_handled(self, name):
- """
- Indicates if an event has any associated handlers.
-
- Returns the number of registered handlers.
+ """Returns the number of registered handlers for an event.
- Arguments:
- name -- The name of the event to check.
+ :param name: The name of the event to check.
"""
return len(self.__event_handlers.get(name, []))
def event(self, name, data={}, direct=False):
- """
- Manually trigger a custom event.
-
- Arguments:
- name -- The name of the event to trigger.
- data -- Data that will be passed to each event handler.
- Defaults to an empty dictionary.
- direct -- Runs the event directly if True, skipping the
- event queue. All event handlers will run in the
- same thread.
- """
- for handler in self.__event_handlers.get(name, []):
+ """Manually trigger a custom event.
+
+ :param name: The name of the event to trigger.
+ :param data: Data that will be passed to each event handler.
+ Defaults to an empty dictionary, but is usually
+ a stanza object.
+ :param direct: Runs the event directly if True, skipping the
+ event queue. All event handlers will run in the
+ same thread.
+ """
+ handlers = self.__event_handlers.get(name, [])
+ for handler in handlers:
+ #TODO: Data should not be copied, but should be read only,
+ # but this might break current code so it's left for future.
+
+ out_data = copy.copy(data) if len(handlers) > 1 else data
+ old_exception = getattr(data, 'exception', None)
if direct:
try:
- handler[0](copy.copy(data))
+ handler[0](out_data)
except Exception as e:
error_msg = 'Error processing event handler: %s'
- log.exception(error_msg % str(handler[0]))
- if hasattr(data, 'exception'):
- data.exception(e)
+ log.exception(error_msg, str(handler[0]))
+ if old_exception:
+ old_exception(e)
else:
self.exception(e)
else:
- self.event_queue.put(('event', handler, copy.copy(data)))
-
+ self.event_queue.put(('event', handler, out_data))
if handler[2]:
# If the handler is disposable, we will go ahead and
# remove it now instead of waiting for it to be
@@ -900,25 +947,22 @@ class XMLStream(object):
def schedule(self, name, seconds, callback, args=None,
kwargs=None, repeat=False):
- """
- Schedule a callback function to execute after a given delay.
-
- Arguments:
- name -- A unique name for the scheduled callback.
- seconds -- The time in seconds to wait before executing.
- callback -- A pointer to the function to execute.
- args -- A tuple of arguments to pass to the function.
- kwargs -- A dictionary of keyword arguments to pass to
- the function.
- repeat -- Flag indicating if the scheduled event should
- be reset and repeat after executing.
+ """Schedule a callback function to execute after a given delay.
+
+ :param name: A unique name for the scheduled callback.
+ :param seconds: The time in seconds to wait before executing.
+ :param callback: A pointer to the function to execute.
+ :param args: A tuple of arguments to pass to the function.
+ :param kwargs: A dictionary of keyword arguments to pass to
+ the function.
+ :param repeat: Flag indicating if the scheduled event should
+ be reset and repeat after executing.
"""
self.scheduler.add(name, seconds, callback, args, kwargs,
repeat, qpointer=self.event_queue)
def incoming_filter(self, xml):
- """
- Filter incoming XML objects before they are processed.
+ """Filter incoming XML objects before they are processed.
Possible uses include remapping namespaces, or correcting elements
from sources with incorrect behavior.
@@ -928,23 +972,23 @@ class XMLStream(object):
return xml
def send(self, data, mask=None, timeout=None, now=False):
- """
- A wrapper for send_raw for sending stanza objects.
+ """A wrapper for :meth:`send_raw()` for sending stanza objects.
May optionally block until an expected response is received.
- Arguments:
- data -- The stanza object to send on the stream.
- mask -- Deprecated. An XML snippet matching the structure
- of the expected response. Execution will block
- in this thread until the response is received
- or a timeout occurs.
- timeout -- Time in seconds to wait for a response before
- continuing. Defaults to RESPONSE_TIMEOUT.
- now -- Indicates if the send queue should be skipped,
- sending the stanza immediately. Useful mainly
- for stream initialization stanzas.
- Defaults to False.
+ :param data: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+ stanza to send on the stream.
+ :param mask: **DEPRECATED**
+ An XML string snippet matching the structure
+ of the expected response. Execution will block
+ in this thread until the response is received
+ or a timeout occurs.
+ :param int timeout: Time in seconds to wait for a response before
+ continuing. Defaults to :attr:`response_timeout`.
+ :param bool now: Indicates if the send queue should be skipped,
+ sending the stanza immediately. Useful mainly
+ for stream initialization stanzas.
+ Defaults to ``False``.
"""
if timeout is None:
timeout = self.response_timeout
@@ -961,53 +1005,64 @@ class XMLStream(object):
return wait_for.wait(timeout)
def send_xml(self, data, mask=None, timeout=None, now=False):
- """
- Send an XML object on the stream, and optionally wait
+ """Send an XML object on the stream, and optionally wait
for a response.
- Arguments:
- data -- The XML object to send on the stream.
- mask -- Deprecated. An XML snippet matching the structure
- of the expected response. Execution will block
- in this thread until the response is received
- or a timeout occurs.
- timeout -- Time in seconds to wait for a response before
- continuing. Defaults to RESPONSE_TIMEOUT.
- now -- Indicates if the send queue should be skipped,
- sending the stanza immediately. Useful mainly
- for stream initialization stanzas.
- Defaults to False.
+ :param data: The :class:`~xml.etree.ElementTree.Element` XML object
+ to send on the stream.
+ :param mask: **DEPRECATED**
+ An XML string snippet matching the structure
+ of the expected response. Execution will block
+ in this thread until the response is received
+ or a timeout occurs.
+ :param int timeout: Time in seconds to wait for a response before
+ continuing. Defaults to :attr:`response_timeout`.
+ :param bool now: Indicates if the send queue should be skipped,
+ sending the stanza immediately. Useful mainly
+ for stream initialization stanzas.
+ Defaults to ``False``.
"""
if timeout is None:
timeout = self.response_timeout
return self.send(tostring(data), mask, timeout, now)
def send_raw(self, data, now=False, reconnect=None):
- """
- Send raw data across the stream.
-
- Arguments:
- data -- Any string value.
- reconnect -- Indicates if the stream should be
- restarted if there is an error sending
- the stanza. Used mainly for testing.
- Defaults to self.auto_reconnect.
+ """Send raw data across the stream.
+
+ :param string data: Any string value.
+ :param bool reconnect: Indicates if the stream should be
+ restarted if there is an error sending
+ the stanza. Used mainly for testing.
+ Defaults to :attr:`auto_reconnect`.
"""
if now:
- log.debug("SEND (IMMED): %s" % data)
+ log.debug("SEND (IMMED): %s", data)
try:
data = data.encode('utf-8')
total = len(data)
sent = 0
count = 0
+ tries = 0
while sent < total and not self.stop.is_set():
- sent += self.socket.send(data[sent:])
- count += 1
+ try:
+ sent += self.socket.send(data[sent:])
+ count += 1
+ except ssl.SSLError as serr:
+ if tries >= self.ssl_retry_max:
+ log.debug('SSL error - max retries reached')
+ self.exception(serr)
+ log.warning("Failed to send %s", data)
+ if reconnect is None:
+ reconnect = self.auto_reconnect
+ self.disconnect(reconnect)
+ log.warning('SSL write error - reattempting')
+ time.sleep(self.ssl_retry_delay)
+ tries += 1
if count > 1:
- log.debug('SENT: %d chunks' % count)
+ log.debug('SENT: %d chunks', count)
except Socket.error as serr:
self.event('socket_error', serr)
- log.warning("Failed to send %s" % data)
+ log.warning("Failed to send %s", data)
if reconnect is None:
reconnect = self.auto_reconnect
self.disconnect(reconnect)
@@ -1016,27 +1071,29 @@ class XMLStream(object):
return True
def process(self, **kwargs):
- """
- Initialize the XML streams and begin processing events.
+ """Initialize the XML streams and begin processing events.
The number of threads used for processing stream events is determined
- by HANDLER_THREADS.
-
- Arguments:
- block -- If block=False then event dispatcher will run
- in a separate thread, allowing for the stream to be
- used in the background for another application.
- Otherwise, process(block=True) blocks the current thread.
- Defaults to False.
-
- **threaded is deprecated and included for API compatibility**
- threaded -- If threaded=True then event dispatcher will run
- in a separate thread, allowing for the stream to be
- used in the background for another application.
- Defaults to True.
-
- Event handlers and the send queue will be threaded
- regardless of these parameters.
+ by :data:`HANDLER_THREADS`.
+
+ :param bool block: If ``False``, then event dispatcher will run
+ in a separate thread, allowing for the stream to be
+ used in the background for another application.
+ Otherwise, ``process(block=True)`` blocks the current
+ thread. Defaults to ``False``.
+ :param bool threaded: **DEPRECATED**
+ If ``True``, then event dispatcher will run
+ in a separate thread, allowing for the stream to be
+ used in the background for another application.
+ Defaults to ``True``. This does **not** mean that no
+ threads are used at all if ``threaded=False``.
+
+ Regardless of these threading options, these threads will
+ always exist:
+
+ - The event queue processor
+ - The send queue processor
+ - The scheduler
"""
if 'threaded' in kwargs and 'block' in kwargs:
raise ValueError("process() called with both " + \
@@ -1050,7 +1107,6 @@ class XMLStream(object):
def start_thread(name, target):
self.__thread[name] = threading.Thread(name=name, target=target)
- self.__thread[name].daemon = True
self.__thread[name].start()
for t in range(0, HANDLER_THREADS):
@@ -1066,8 +1122,7 @@ class XMLStream(object):
self._process()
def _process(self):
- """
- Start processing the XML streams.
+ """Start processing the XML streams.
Processing will continue after any recoverable errors
if reconnections are allowed.
@@ -1077,6 +1132,7 @@ class XMLStream(object):
# Additional passes will be made only if an error occurs and
# reconnecting is permitted.
while True:
+ shutdown = False
try:
# The call to self.__read_xml will block and prevent
# the body of the loop from running until a disconnect
@@ -1094,33 +1150,36 @@ class XMLStream(object):
if not self.__read_xml():
# If the server terminated the stream, end processing
break
- except SyntaxError as e:
- log.error("Error reading from XML stream.")
- self.exception(e)
except KeyboardInterrupt:
log.debug("Keyboard Escape Detected in _process")
- self.stop.set()
+ self.event('killed', direct=True)
+ shutdown = True
except SystemExit:
log.debug("SystemExit in _process")
- self.stop.set()
- self.scheduler.quit()
+ shutdown = True
+ except SyntaxError as e:
+ log.error("Error reading from XML stream.")
+ shutdown = True
+ self.exception(e)
except Socket.error as serr:
self.event('socket_error', serr)
log.exception('Socket Error')
- except:
+ except Exception as e:
if not self.stop.is_set():
log.exception('Connection error.')
+ self.exception(e)
- if not self.stop.is_set() and self.auto_reconnect:
+ if not shutdown and not self.stop.is_set() \
+ and self.auto_reconnect:
self.reconnect()
else:
self.disconnect()
break
def __read_xml(self):
- """
- Parse the incoming XML stream, raising stream events for
- each received stanza.
+ """Parse the incoming XML stream
+
+ Stream events are raised for each received stanza.
"""
depth = 0
root = None
@@ -1156,16 +1215,16 @@ class XMLStream(object):
log.debug("Ending read XML loop")
def _build_stanza(self, xml, default_ns=None):
- """
- Create a stanza object from a given XML object.
+ """Create a stanza object from a given XML object.
If a specialized stanza type is not found for the XML, then
- a generic StanzaBase stanza will be returned.
+ a generic :class:`~sleekxmpp.xmlstream.stanzabase.StanzaBase`
+ stanza will be returned.
- Arguments:
- xml -- The XML object to convert into a stanza object.
- default_ns -- Optional default namespace to use instead of the
- stream's current default namespace.
+ :param xml: The :class:`~xml.etree.ElementTree.Element` XML object
+ to convert into a stanza object.
+ :param default_ns: Optional default namespace to use instead of the
+ stream's current default namespace.
"""
if default_ns is None:
default_ns = self.default_ns
@@ -1184,11 +1243,10 @@ class XMLStream(object):
objects if applicable and queue stream events to be processed
by matching handlers.
- Arguments:
- xml -- The XML stanza to analyze.
+ :param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+ stanza to analyze.
"""
- log.debug("RECV: %s" % tostring(xml,
- xmlns=self.default_ns,
+ log.debug("RECV: %s", tostring(xml, xmlns=self.default_ns,
stream=self))
# Apply any preprocessing filters.
xml = self.incoming_filter(xml)
@@ -1201,17 +1259,20 @@ class XMLStream(object):
# to run "in stream" will be executed immediately; the rest will
# be queued.
unhandled = True
- for handler in self.__handlers:
- if handler.match(stanza):
+ matched_handlers = [h for h in self.__handlers if h.match(stanza)]
+ for handler in matched_handlers:
+ if len(matched_handlers) > 1:
stanza_copy = copy.copy(stanza)
- handler.prerun(stanza_copy)
- self.event_queue.put(('stanza', handler, stanza_copy))
- try:
- if handler.check_delete():
- self.__handlers.remove(handler)
- except:
- pass # not thread safe
- unhandled = False
+ else:
+ stanza_copy = stanza
+ handler.prerun(stanza_copy)
+ self.event_queue.put(('stanza', handler, stanza_copy))
+ try:
+ if handler.check_delete():
+ self.__handlers.remove(handler)
+ except:
+ pass # not thread safe
+ unhandled = False
# Some stanzas require responses, such as Iq queries. A default
# handler will be executed immediately for this case.
@@ -1219,28 +1280,26 @@ class XMLStream(object):
stanza.unhandled()
def _threaded_event_wrapper(self, func, args):
- """
- Capture exceptions for event handlers that run
+ """Capture exceptions for event handlers that run
in individual threads.
- Arguments:
- func -- The event handler to execute.
- args -- Arguments to the event handler.
+ :param func: The event handler to execute.
+ :param args: Arguments to the event handler.
"""
- orig = copy.copy(args[0])
+ # this is always already copied before this is invoked
+ orig = args[0]
try:
func(*args)
except Exception as e:
error_msg = 'Error processing event handler: %s'
- log.exception(error_msg % str(func))
+ log.exception(error_msg, str(func))
if hasattr(orig, 'exception'):
orig.exception(e)
else:
self.exception(e)
def _event_runner(self):
- """
- Process the event queue and execute handlers.
+ """Process the event queue and execute handlers.
The number of event runner threads is controlled by HANDLER_THREADS.
@@ -1249,7 +1308,7 @@ class XMLStream(object):
"""
log.debug("Loading event runner")
try:
- while not self.stop.isSet():
+ while not self.stop.is_set():
try:
wait = self.wait_timeout
event = self.event_queue.get(True, timeout=wait)
@@ -1267,19 +1326,18 @@ class XMLStream(object):
handler.run(args[0])
except Exception as e:
error_msg = 'Error processing stream handler: %s'
- log.exception(error_msg % handler.name)
+ log.exception(error_msg, handler.name)
orig.exception(e)
elif etype == 'schedule':
name = args[1]
try:
- log.debug('Scheduled event: %s: %s' % (name, args[0]))
+ log.debug('Scheduled event: %s: %s', name, args[0])
handler(*args[0])
except Exception as e:
log.exception('Error processing scheduled task')
self.exception(e)
elif etype == 'event':
func, threaded, disposable = handler
- orig = copy.copy(args[0])
try:
if threaded:
x = threading.Thread(
@@ -1291,7 +1349,7 @@ class XMLStream(object):
func(*args)
except Exception as e:
error_msg = 'Error processing event handler: %s'
- log.exception(error_msg % str(func))
+ log.exception(error_msg, str(func))
if hasattr(orig, 'exception'):
orig.exception(e)
else:
@@ -1310,12 +1368,12 @@ class XMLStream(object):
return
def _send_thread(self):
- """
- Extract stanzas from the send queue and send them on the stream.
- """
+ """Extract stanzas from the send queue and send them on the stream."""
try:
while not self.stop.is_set():
- self.session_started_event.wait()
+ while not self.stop.is_set and \
+ not self.session_started_event.is_set():
+ self.session_started_event.wait(timeout=1)
if self.__failed_send_stanza is not None:
data = self.__failed_send_stanza
self.__failed_send_stanza = None
@@ -1324,37 +1382,48 @@ class XMLStream(object):
data = self.send_queue.get(True, 1)
except queue.Empty:
continue
- log.debug("SEND: %s" % data)
+ log.debug("SEND: %s", data)
+ enc_data = data.encode('utf-8')
+ total = len(enc_data)
+ sent = 0
+ count = 0
+ tries = 0
try:
- enc_data = data.encode('utf-8')
- total = len(enc_data)
- sent = 0
- count = 0
while sent < total and not self.stop.is_set():
- sent += self.socket.send(enc_data[sent:])
- count += 1
+ try:
+ sent += self.socket.send(enc_data[sent:])
+ count += 1
+ except ssl.SSLError as serr:
+ if tries >= self.ssl_retry_max:
+ log.debug('SSL error - max retries reached')
+ self.exception(serr)
+ log.warning("Failed to send %s", data)
+ if reconnect is None:
+ reconnect = self.auto_reconnect
+ self.disconnect(reconnect)
+ log.warning('SSL write error - reattempting')
+ time.sleep(self.ssl_retry_delay)
+ tries += 1
if count > 1:
- log.debug('SENT: %d chunks' % count)
+ log.debug('SENT: %d chunks', count)
self.send_queue.task_done()
except Socket.error as serr:
self.event('socket_error', serr)
- log.warning("Failed to send %s" % data)
+ log.warning("Failed to send %s", data)
self.__failed_send_stanza = data
self.disconnect(self.auto_reconnect)
except Exception as ex:
- log.exception('Unexpected error in send thread: %s' % ex)
+ log.exception('Unexpected error in send thread: %s', ex)
self.exception(ex)
if not self.stop.is_set():
self.disconnect(self.auto_reconnect)
def exception(self, exception):
- """
- Process an unknown exception.
+ """Process an unknown exception.
Meant to be overridden.
- Arguments:
- exception -- An unhandled exception object.
+ :param exception: An unhandled exception object.
"""
pass