mktestdocs 0.1.2__py2.py3-none-any.whl → 0.2.1__py2.py3-none-any.whl

mktestdocs/__init__.py

@@ -1,4 +1,5 @@
 from mktestdocs.__main__ import (
+    register_executor,
     check_codeblock,
     grab_code_blocks,
     check_docstring,
@@ -6,10 +7,11 @@ from mktestdocs.__main__ import (
     get_codeblock_members,
 )
 
-__version__ = "0.1.2"
+__version__ = "0.2.1"
 
 __all__ = [
     "__version__",
+    "register_executor",
     "check_codeblock",
     "grab_code_blocks",
     "check_docstring",

mktestdocs/__main__.py

@@ -1,8 +1,56 @@
 import inspect
 import pathlib
+import subprocess
 import textwrap
 
 
+_executors = {}
+
+
+def register_executor(lang, executor):
+    """Add a new executor for markdown code blocks
+
+    lang should be the tag used after the opening ```
+    executor should be a callable that takes one argument:
+        the code block found
+    """
+    _executors[lang] = executor
+
+
+def exec_bash(source):
+    """Exec the bash source given in a new subshell
+
+    Does not return anything, but if any command returns not-0 an error
+    will be raised
+    """
+    command = ["bash", "-e", "-u", "-c", source]
+    try:
+        subprocess.run(command, check=True)
+    except Exception:
+        print(source)
+        raise
+
+
+register_executor("bash", exec_bash)
+
+
+def exec_python(source):
+    """Exec the python source given in a new module namespace
+
+    Does not return anything, but exceptions raised by the source
+    will propagate out unmodified
+    """
+    try:
+        exec(source, {"__MODULE__": "__main__"})
+    except Exception:
+        print(source)
+        raise
+
+
+register_executor("", exec_python)
+register_executor("python", exec_python)
+
+
 def get_codeblock_members(*classes):
     """
     Grabs the docstrings of any methods of any classes that are passed in.
@@ -61,49 +109,54 @@ def check_docstring(obj, lang=""):
     """
     Given a function, test the contents of the docstring.
     """
+    if lang not in _executors:
+        raise LookupError(
+            f"{lang} is not a supported language to check\n"
+            "\tHint: you can add support for any language by using register_executor"
+        )
+    executor = _executors[lang]
     for b in grab_code_blocks(obj.__doc__, lang=lang):
-        try:
-            exec(b, {"__MODULE__": "__main__"})
-        except Exception:
-            print(f"Error Encountered in `{obj.__name__}`. Caused by:\n")
-            print(b)
-            raise
+        executor(b)
 
 
 def check_raw_string(raw, lang="python"):
     """
     Given a raw string, test the contents.
     """
+    if lang not in _executors:
+        raise LookupError(
+            f"{lang} is not a supported language to check\n"
+            "\tHint: you can add support for any language by using register_executor"
+        )
+    executor = _executors[lang]
     for b in grab_code_blocks(raw, lang=lang):
-        try:
-            exec(b, {"__MODULE__": "__main__"})
-        except Exception:
-            print(b)
-            raise
+        executor(b)
 
 
 def check_raw_file_full(raw, lang="python"):
+    if lang not in _executors:
+        raise LookupError(
+            f"{lang} is not a supported language to check\n"
+            "\tHint: you can add support for any language by using register_executor"
+        )
+    executor = _executors[lang]
     all_code = ""
     for b in grab_code_blocks(raw, lang=lang):
         all_code = f"{all_code}\n{b}"
-    try:
-        exec(all_code, {"__MODULE__": "__main__"})
-    except Exception:
-        print(all_code)
-        raise
-    
+    executor(all_code)
+
 
-def check_md_file(fpath, memory=False):
+def check_md_file(fpath, memory=False, lang="python"):
     """
     Given a markdown file, parse the contents for python code blocks
-    and check that each independant block does not cause an error.
+    and check that each independent block does not cause an error.
 
     Arguments:
         fpath: path to markdown file
-        memory: wheather or not previous code-blocks should be remembered
+        memory: whether or not previous code-blocks should be remembered
     """
     text = pathlib.Path(fpath).read_text()
     if not memory:
-        check_raw_string(text, lang="python")
+        check_raw_string(text, lang=lang)
     else:
-        check_raw_file_full(text, lang="python")
+        check_raw_file_full(text, lang=lang)

{mktestdocs-0.1.2.dist-info → mktestdocs-0.2.1.dist-info}/METADATA

@@ -1,13 +1,7 @@
 Metadata-Version: 2.1
 Name: mktestdocs
-Version: 0.1.2
-Summary: UNKNOWN
-Home-page: UNKNOWN
-License: UNKNOWN
-Platform: UNKNOWN
+Version: 0.2.1
+License-File: LICENSE
 Provides-Extra: test
 Requires-Dist: pytest (>=4.0.2) ; extra == 'test'
 
-UNKNOWN
-
-

mktestdocs-0.2.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+mktestdocs/__init__.py,sha256=_iVQPmcuxkjOr-bEOP4DEygx6mnG_6fP4wJBhbc2G8E,371
+mktestdocs/__main__.py,sha256=BO5LopXLAeKFFuKcT0KaeErUeFXt8ekjIiyrTymBG3k,4508
+mktestdocs-0.2.1.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+mktestdocs-0.2.1.dist-info/METADATA,sha256=67xAXa_sIfpXAHDaOiKJPxRUqXQekbdMhZDqXQzL5Ec,148
+mktestdocs-0.2.1.dist-info/WHEEL,sha256=a-zpFRIJzOq5QfuhBzbhiA1eHTzNCJn8OdRvhdNX0Rk,110
+mktestdocs-0.2.1.dist-info/top_level.txt,sha256=1XGYsQSl3FsAtilWThIet3WOJQSuzQXXn6sQA7hxlho,11
+mktestdocs-0.2.1.dist-info/RECORD,,

{mktestdocs-0.1.2.dist-info → mktestdocs-0.2.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.36.2)
+Generator: bdist_wheel (0.40.0)
 Root-Is-Purelib: true
 Tag: py2-none-any
 Tag: py3-none-any

{mktestdocs-0.1.2.dist-info → mktestdocs-0.2.1.dist-info}/top_level.txt

@@ -1,2 +1 @@
 mktestdocs
-tests

mktestdocs-0.1.2.dist-info/RECORD

@@ -1,12 +0,0 @@
-mktestdocs/__init__.py,sha256=OFT05l99yabbzwBSEyoxcy6EOeQ8OJZ-Aj42-6DaB2U,323
-mktestdocs/__main__.py,sha256=xZoRTfWCTJltef-katbq9XY_OK0GDaFggwhcXIBfMTk,3069
-tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-tests/test_actual_docstrings.py,sha256=N1yIuHOBNhv2qR2yO1DkqiBNvHK3_o_pbLJCHLKUa68,940
-tests/test_class.py,sha256=lkZ73We8Hb4IvPbQVn8w5LX5zMHptFHkUcJ3xfBJqgc,1220
-tests/test_codeblock.py,sha256=FxyPZZw1lVLFWXB1BErciHP6h-kFNBLLPU9UX_6uBfE,903
-tests/test_markdown.py,sha256=ndriPDsL5rI0mPhDJDeTRwmDWod6DXXlm05CRNKhDdk,827
-mktestdocs-0.1.2.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-mktestdocs-0.1.2.dist-info/METADATA,sha256=e0ET9ESs91i_AtXs_TifyTbZa0aGledTBv_TTzXO-ss,207
-mktestdocs-0.1.2.dist-info/WHEEL,sha256=Z-nyYpwrcSqxfdux5Mbn_DQ525iP7J2DG3JgGvOYyTQ,110
-mktestdocs-0.1.2.dist-info/top_level.txt,sha256=Wh9mCrbRZsALS8VKzSi8ifKBj95gf-BHeWQCoTTNBKc,17
-mktestdocs-0.1.2.dist-info/RECORD,,

tests/test_actual_docstrings.py

@@ -1,60 +0,0 @@
-import pytest
-from mktestdocs import check_docstring
-
-
-def foobar_good(a, b):
-    """
-    Returns a + b.
-
-    Examples:
-
-    ```python
-    import random
-
-    random.random()
-    assert 'a' + 'b' == 'ab'
-    assert 1 + 2 == 3
-    ```
-    """
-    return a + b
-
-
-def foobar_also_good(a, b):
-    """
-    Returns a + b.
-
-    Examples:
-
-    ```python
-    import random
-
-    assert random.random() < 10
-    ```
-    """
-    return a + b
-
-
-def foobar_bad(a, b):
-    """
-    Returns a + b.
-
-    Examples:
-
-    ```python
-    assert foobar(1, 2) == 4
-    ```
-    """
-    return a + b
-
-
-@pytest.mark.parametrize("func", [foobar_good, foobar_also_good])
-def test_base_docstrings(func):
-    check_docstring(func)
-
-
-@pytest.mark.parametrize("func", [foobar_bad])
-def test_base_docstrings_bad(func, capsys):
-    with pytest.raises(Exception):
-        check_docstring(func)
-        capsys.readouterr()
-        assert func.__name__ in capsys.readouterr().out

tests/test_class.py

@@ -1,73 +0,0 @@
-import pytest
-
-from mktestdocs import get_codeblock_members, check_docstring
-
-
-class Dinosaur:
-    """
-    This is a dino.
-
-    ```python
-    from dinosaur import Dinosaur
-
-    assert Dinosaur().name == 'trex'
-    ```
-    """
-
-    def __init__(self):
-        self.name = "trex"
-
-    @staticmethod
-    def a(value):
-        """
-        Returns value
-
-        Example:
-
-        ```python
-        from dinosaur import Dinosaur
-
-        dino = Dinosaur()
-        assert dino.a(1) == 1
-        ```
-        """
-        return value
-
-    @classmethod
-    def b(cls, value):
-        """
-        Returns value
-
-        Example:
-
-        ```python
-        from dinosaur import Dinosaur
-        assert Dinosaur.b(1) == 1
-        ```
-        """
-        return value
-
-    def hello(self):
-        """
-        Returns value
-
-        Example:
-
-        ```python
-        from dinosaur import Dinosaur
-        assert Dinosaur().name == 'trex'
-        ```
-        """
-        return self.name
-
-
-members = get_codeblock_members(Dinosaur)
-
-
-def test_grab_methods():
-    assert len(get_codeblock_members(Dinosaur)) == 4
-
-
-@pytest.mark.parametrize("obj", members, ids=lambda d: d.__qualname__)
-def test_member(obj):
-    check_docstring(obj)

tests/test_codeblock.py

@@ -1,56 +0,0 @@
-import pytest
-
-from mktestdocs import check_codeblock, grab_code_blocks
-
-exibit_a = """
-This is an example docstring. 
-
-Arguments:
-    a: a parameter 
-    
-There is no example
-"""
-
-exibit_b = """
-This is an example docstring. 
-
-Arguments:
-    a: a parameter 
-
-```python
-assert 1 == 1
-```
-"""
-
-exibit_c = """
-This is an example docstring. 
-
-Arguments:
-    a: a parameter 
-
-```
-assert 1 == 1
-```
-
-```python
-assert 1 == 1
-```
-"""
-
-
-@pytest.mark.parametrize(
-    "doc, n",
-    [(exibit_a, 0), (exibit_b, 1), (exibit_c, 1)],
-    ids=["exibit_a", "exibit_b", "exibit_c"],
-)
-def test_number_of_codeblocks(doc, n):
-    assert len(grab_code_blocks(doc, lang="python")) == n
-
-
-@pytest.mark.parametrize(
-    "doc, n",
-    [(exibit_a, 0), (exibit_b, 1), (exibit_c, 2)],
-    ids=["exibit_a", "exibit_b", "exibit_c"],
-)
-def test_number_of_codeblocks_any(doc, n):
-    assert len(grab_code_blocks(doc, lang=None)) == n

tests/test_markdown.py

@@ -1,27 +0,0 @@
-import pathlib
-import pytest
-
-from mktestdocs import check_md_file
-
-
-@pytest.mark.parametrize("fpath", pathlib.Path("tests/data/good").glob("*.md"), ids=str)
-def test_files_good(fpath):
-    check_md_file(fpath=fpath)
-
-
-@pytest.mark.parametrize("fpath", pathlib.Path("tests/data/bad").glob("*.md"), ids=str)
-def test_files_bad(fpath):
-    with pytest.raises(Exception):
-        check_md_file(fpath=fpath)
-
-
-def test_big_files_good():
-    """Confirm that we can deal with multi-cell markdown cells."""
-    check_md_file(fpath="tests/data/big-good.md", memory=True)
-
-
-def test_big_file_independant():
-    """Confirm that different files don't influence eachother."""
-    check_md_file(fpath="tests/data/big-good.md", memory=True)
-    with pytest.raises(Exception):
-        check_md_file(fpath="tests/data/big-bad.md", memory=True)