Remove pytest, add documentation

Author: David Walker

README.rst

@@ -59,6 +59,13 @@ in the root of the source tree:
 
 This will automatically install the package for you.
 
+Install with Tornado Support
+----------------------------
+
+::
+    pip install xbee[tornado]
+
+
 Documentation
 =============
 
@@ -80,7 +87,9 @@ PySerial
 Additional Dependencies
 -----------------------
 
-To run automated tests: `Nose <https://github.com/nose-devs/nose/>`_
+If wanting to use the Tornado IOLoop: `Tornado <http://www.tornadoweb.org/>`_
+
+To run automated tests: `pytest <https://docs.pytest.org>`_
 
 To build the documentation: `Sphinx <http://sphinx-doc.org/>`_
 
@@ -101,3 +110,4 @@ Contributors
 * Amit Synderman
 * Marco Sangalli
 * James Saunders james@saunders-family.net
+* David Walker dwalker@n.io

docs/source/index.rst

@@ -42,7 +42,12 @@ Usage
    must be enabled. For instructions about how to do this, see
    the documentation for your XBee device.
 
-Synchonous Mode
+.. note::
+    The default implementation of the python-xbee library is to 
+    use threads.  There is an implementation that utilizes the
+    Tornado IOLoop, if imported.
+
+Threaded Synchonous Mode
 ~~~~~~~~~~~~~~~
 
 The following code demonstrates a minimal use-case for the
@@ -67,7 +72,7 @@ print out any data frames which arrive from a connected XBee
 device. Be aware that wait_read_frame() will block until
 a valid frame is received from the associated XBee device.
 
-Asynchronous Mode
+Threaded Asynchronous Mode
 ~~~~~~~~~~~~~~~~~
 
 The xbee package is used only slightly differently when 
@@ -110,6 +115,46 @@ to handle receiving and processing incoming data from an
 XBee device. This example is functionally equivalent to the non-asyncronous
 example above.
 
+Tornado IOLoop
+~~~~~~~~~~~~~~~~~~
+Tornado provides a simple and easy to use IOLoop for asynchronous listening
+for XBee communications.  The library usage is seemingly identical to the
+threaded implementation, excepting importing and yielding.  The example
+highlights the key differences::
+
+    import serial
+    from tornado import ioloop, gen
+    from xbee.tornado import XBee
+
+    serial_port = serial.Serial('/dev/ttyUSB0', 9600)
+
+    def print_data(data):
+        """
+        This method is called whenever data is received
+        from the associated XBee device. Its first and
+        only argument is the data contained within the
+        frame.
+        """
+        print data
+
+    @gen.coroutine
+    def main():
+        xbee = XBee(serial_port, callback=print_data)
+
+        try:
+            while True:
+                yield gen.sleep(0.001)
+        except KeyboardInterrupt:
+            ioloop.IOLoop.current().stop()
+        finally
+            xbee.halt()
+            serial_port.close()
+
+    ioloop.IOLoop.current().spawn_callback(main)
+    ioloop.IOLoop.current().start()
+    ioloop.IOLoop.current().close()
+
+
 Additional Examples
 ~~~~~~~~~~~~~~~~~~~
 

examples/tornado_example.py

@@ -31,7 +31,6 @@ def main():
             xbee.send('at', frame_id='B', command='DL')
     except KeyboardInterrupt:
         ioloop.IOLoop.current().stop()
-        return
     finally:
         xbee.halt()
         ser.close()

xbee/tornado/tests/test_base.py

@@ -8,13 +8,16 @@
 Tests the XBeeBase superclass module for XBee API conformance.
 """
 
-import pytest
-pytest.importorskip("tornado")
+import unittest
+from xbee.tornado import has_tornado
 
-from tornado.testing import AsyncTestCase, gen_test
-from tornado.test.util import unittest
-from xbee.tornado.base import XBeeBase
-from xbee.tests.Fake import Serial
+if not has_tornado:
+    raise unittest.SkipTest("Requires Tornado")
+
+from tornado.testing import AsyncTestCase, gen_test  # noqa
+from tornado.test.util import unittest  # noqa
+from xbee.tornado.base import XBeeBase  # noqa
+from xbee.tests.Fake import Serial  # noqa
 
 
 class TestReadFromDevice(AsyncTestCase):

xbee/tornado/tests/test_digimesh.py

@@ -6,11 +6,13 @@
 
 Tests the XBee DigiMesh implementation class for API compliance
 """
-import pytest
-pytest.importorskip("tornado")
-
 import unittest
-from xbee.tornado.digimesh import DigiMesh
+from xbee.tornado import has_tornado
+
+if not has_tornado:
+    raise unittest.SkipTest("Requires Tornado")
+
+from xbee.tornado.digimesh import DigiMesh  # noqa
 
 
 class TestDigiMesh(unittest.TestCase):

xbee/tornado/tests/test_ieee.py

@@ -7,18 +7,20 @@
 
 Tests the XBee (IEEE 802.15.4) implementation class for XBee API compliance
 """
-import pytest
-pytest.importorskip("tornado")
-
-from xbee.tests.Fake import Serial
-from xbee.tornado.ieee import XBee
-from xbee.frame import APIFrame
-from xbee.python2to3 import intToByte, stringToBytes
-from tornado.testing import AsyncTestCase, gen_test
-from tornado.test.util import unittest
-import sys
-import pytest
-import traceback
+import unittest
+from xbee.tornado import has_tornado
+
+if not has_tornado:
+    raise unittest.SkipTest("Requires Tornado")
+
+from xbee.tests.Fake import Serial  # noqa
+from xbee.tornado.ieee import XBee  # noqa
+from xbee.frame import APIFrame  # noqa
+from xbee.python2to3 import intToByte, stringToBytes  # noqa
+from tornado.testing import AsyncTestCase, gen_test  # noqa
+from tornado.test.util import unittest  # noqa
+import sys  # noqa
+import traceback  # noqa
 
 
 class InitXBee(AsyncTestCase):

xbee/tornado/tests/test_zigbee.py

@@ -6,12 +6,14 @@
 
 Tests the XBee ZB (ZigBee) implementation class for API compliance
 """
-import pytest
-pytest.importorskip("tornado")
-
 import unittest
-from xbee.tornado.zigbee import ZigBee
-from xbee.tests.Fake import Serial
+from xbee.tornado import has_tornado
+
+if not has_tornado:
+    raise unittest.SkipTest("Requires Tornado")
+
+from xbee.tornado.zigbee import ZigBee  # noqa
+from xbee.tests.Fake import Serial  # noqa
 
 
 class TestZigBee(unittest.TestCase):