Fix up places that treated warnings as Exceptions and enable doctests (…

…#7)

* Fix documentation: warnings aren't exceptions

run() will warn, not raise an exception, if the FPGA is already
running. Fix examples to reflect this.

Also fixup the indentation.

* remove dead code

Since warnings aren't exceptions, this code path is dead.

* Fix documentation and turn it into a doctest

Rework the documentation to demonstrate how to handle a warning, and
turn it into a doctest so it doesn't become stale again.

.travis.yml

@@ -10,4 +10,4 @@ install:
 before_script:
   - "flake8 nifpga --ignore=E501"
 script:
-  - "nosetests"
+  - "nosetests --with-doctest"

README.md

@@ -30,10 +30,7 @@ information on sessions view our Read the docs documentation
 Example usage of FPGA configuration functions:
 
     with Session(bitfile="BitfilePath.lvbitx", resource="RIO0") as session:
-       try:
-          session.run()
-       except FpgaAlreadyRunningWarning:
-          pass
+       session.run()
        session.download()
        session.abort()
        session.reset()

docs/examples/basic_examples.rst

@@ -15,10 +15,7 @@ Recommended usage is to open a Session as follows:
    from nifpga import Session
 
    with Session(bitfile="MyBitfile.lvbitx", resource="RIO0") as session:
-      try:
-         session.run()
-      except FpgaAlreadyRunningWarning:
-         pass
+      session.run()
       session.download()
       session.abort()
       session.reset()
@@ -37,7 +34,7 @@ Example Usage:
 
 .. code-block:: python
 
-   from nifpga import Session, FpgaAlreadyRunningWarning
+   from nifpga import Session
 
    with Session("MyBitfile.lvbitx", "RIO0") as session:
        my_control = session.registers['My Control']

nifpga/session.py

@@ -8,7 +8,7 @@
                      OPEN_ATTRIBUTE_NO_RUN, RUN_ATTRIBUTE_WAIT_UNTIL_DONE,
                      CLOSE_ATTRIBUTE_NO_RESET_IF_LAST_SESSION)
 from .bitfile import Bitfile
-from .status import IrqTimeoutWarning, InvalidSessionError
+from .status import InvalidSessionError
 from collections import namedtuple
 import ctypes
 from builtins import bytes
@@ -27,11 +27,10 @@ class Session(object):
     Example usage of FPGA configuration functions::
 
         with Session(bitfile="myBitfilePath.lvbitx", resource="RIO0") as session:
-            try: session.run()
-                except: FpgaAlreadyRunningWarning: pass
-                session.download()
-                session.abort()
-                session.reset()
+            session.run()
+            session.download()
+            session.abort()
+            session.reset()
 
     Note:
         It is always recommended that you use a Session with a context manager
@@ -214,10 +213,6 @@ def wait_on_irqs(self, irqs, timeout_ms):
                                     timeout_ms,
                                     irqs_asserted_bitmask,
                                     timed_out)
-        except IrqTimeoutWarning:
-            # We pass timed_out to the C API, so we can ignore this warning
-            # and just always return timed_out.
-            pass
         finally:
             self._nifpga.UnreserveIrqContext(self._session, context)
         irqs_asserted = [i for i in range(32) if irqs_asserted_bitmask.value & (1 << i)]

nifpga/status.py

@@ -7,18 +7,33 @@
 Error and Warning exception class names are auto-generated from the
 strings in 'codeToString' in this file.
 For example, handle a fatal error like this:
-    try:
-        check_status(-61141, ...)
-    except FpgaBusyError as e:
-        # handle a fatal "FpgaBusy" status code
-        ...
+
+    >>> @check_status('frob', ['foo', 'bar', 'baz'])
+    ... def frob(foo, bar, baz):
+    ...     return -61141
+    ...
+    >>> try:
+    ...     frob(0, 1, 2)
+    ... except FpgaBusyError as e:
+    ...     print(e)  # doctest: +NORMALIZE_WHITESPACE
+    Error: FpgaBusy (-61141) when calling 'frob' with arguments:
+        foo: 0x0
+        bar: 0x1
+        baz: 0x2
 
 Or handle a warning like this:
-    try:
-        check_status(61003, ...)
-    except FpgaAlreadyRunningWarning as e:
-        # handle a "FpgaAlreadyRunning" warning status code
-        ...
+
+    >>> @check_status('frob', ['foo', 'bar', 'baz'])
+    ... def frob(foo, bar, baz):
+    ...     return 61003
+    ...
+    >>> with warnings.catch_warnings(record=True) as w:
+    ...     frob(0, 1, 2)
+    ...     print(w[0].message)  # doctest: +NORMALIZE_WHITESPACE
+    Warning: FpgaAlreadyRunning (61003) when calling 'frob' with arguments:
+        foo: 0x0
+        bar: 0x1
+        baz: 0x2
 
 Copyright (c) 2017 National Instruments
 """