added block as process option and updated documentation. added typical use example to ClientXMPP.

3 files changed, 43 insertions, 8 deletions

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):