util: testing: docs: Add run_doctest function

Add a function to run a doctest of an object and raise an excpetion if
it failed.

Signed-off-by: John Andersen <[email protected]>

Author: pdxjohnny

dffml/util/testing/docs.py

@@ -0,0 +1,30 @@
+import io
+import doctest
+from typing import Dict, Any
+
+
+def run_doctest(obj, state: Dict[str, Any] = None, check: bool = True):
+    """
+    Run doctest on the object provided. Globals should be passed via the
+    ``globs`` key within the ``state`` dict. Globals are a key value mapping of
+    the name of the global to the object it will be.
+
+    You probably want to use state like so
+
+    .. code-block:: python
+
+        run_doctest(func, state={"globs": globals()})
+    """
+    if state is None:
+        state = {}
+    state.setdefault("verbose", False)
+    state.setdefault("globs", {})
+
+    finder = doctest.DocTestFinder(verbose=state["verbose"], recurse=False)
+    runner = doctest.DocTestRunner(verbose=state["verbose"])
+
+    for test in finder.find(obj, obj.__qualname__, globs=state["globs"]):
+        output = io.StringIO()
+        results = runner.run(test, out=output.write)
+        if results.failed and check:
+            raise Exception(output.getvalue())

tests/util/testing/__init__.py

@@ -0,0 +1,25 @@
+import unittest
+
+from dffml.util.testing.docs import run_doctest
+
+def bad_func():
+    """
+    >>> bad_func()
+    True
+    """
+    return False
+
+def good_func():
+    """
+    >>> good_func()
+    True
+    """
+    return True
+
+class TestDocs(unittest.TestCase):
+    def test_run_doctest_bad(self):
+        with self.assertRaisesRegex(Exception, "Failed example:"):
+            run_doctest(bad_func, state={"globs": globals()})
+
+    def test_run_doctest_good(self):
+        run_doctest(good_func, state={"globs": globals()})