From 7f90de887a7e3ca53103babf5a9acf15a69ab959 Mon Sep 17 00:00:00 2001 From: Nathan Fritz Date: Thu, 4 Aug 2011 21:49:32 -0700 Subject: added block as process option and updated documentation. added typical use example to ClientXMPP. --- sleekxmpp/basexmpp.py | 24 +++++++++++++++++++++--- sleekxmpp/clientxmpp.py | 7 +++++-- sleekxmpp/xmlstream/xmlstream.py | 20 +++++++++++++++++--- 3 files changed, 43 insertions(+), 8 deletions(-) (limited to 'sleekxmpp') diff --git a/sleekxmpp/basexmpp.py b/sleekxmpp/basexmpp.py index b188e767..07726a41 100644 --- a/sleekxmpp/basexmpp.py +++ b/sleekxmpp/basexmpp.py @@ -140,10 +140,28 @@ class BaseXMPP(XMLStream): def process(self, *args, **kwargs): """ - Ensure that plugin inter-dependencies are handled before starting - event processing. - Overrides XMLStream.process. + + 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. """ for name in self.plugin: if not self.plugin[name].post_inited: diff --git a/sleekxmpp/clientxmpp.py b/sleekxmpp/clientxmpp.py index 95ae108b..ad127726 100644 --- a/sleekxmpp/clientxmpp.py +++ b/sleekxmpp/clientxmpp.py @@ -40,9 +40,12 @@ log = logging.getLogger(__name__) class ClientXMPP(BaseXMPP): """ - SleekXMPP's client class. + SleekXMPP's client class. ( Use only for good, not for evil.) - Use only for good, not for evil. + Typical Use: + xmpp = ClientXMPP('user@server.tld/resource', 'password') + xmpp.process(block=False) // when block is True, it blocks the current + // thread. False by default. Attributes: diff --git a/sleekxmpp/xmlstream/xmlstream.py b/sleekxmpp/xmlstream/xmlstream.py index 15bbe655..41c53a3e 100644 --- a/sleekxmpp/xmlstream/xmlstream.py +++ b/sleekxmpp/xmlstream/xmlstream.py @@ -831,7 +831,7 @@ class XMLStream(object): self.send_queue.put(data) return True - def process(self, threaded=True): + def process(self, **kwargs): """ Initialize the XML streams and begin processing events. @@ -839,14 +839,28 @@ class XMLStream(object): 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 this parameter's value. + Event handlers and the send queue will be threaded + regardless of these parameters. """ + if kwargs.has_key('threaded') and kwargs.has_key('block'): + raise ValueError("process() called with both block and threaded arguments") + elif kwargs.has_key('block'): + threaded = not(kwargs.get('block', False)) + else: + threaded = kwargs.get('threaded', True) + self.scheduler.process(threaded=True) def start_thread(name, target): -- cgit v1.2.3