mktestdocs 0.2.1__tar.gz → 0.2.5__tar.gz

mktestdocs-0.2.5/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: mktestdocs
+Version: 0.2.5
+Summary: A tool for testing markdown documentation
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+<img src="icon.png" width=125 height=125 align="right">
+
+### mktestdocs
+
+Run pytest against markdown files/docstrings.
+
+# Installation 
+
+```
+pip install mktestdocs
+```
+
+## Usage 
+
+Let's say that you're using [mkdocs](https://squidfunk.github.io/mkdocs-material/getting-started/) 
+for your documentation. Then you're writing down markdown to explain how your Python packages work. 
+It'd be a shame if a codeblock had an error in it, so it'd be 
+great if you could run your unit tests against them. 
+
+This package allows you to do _just that_. Here's an example:
+
+```python
+import pathlib
+import pytest
+
+from mktestdocs import check_md_file
+
+# Note the use of `str`, makes for pretty output
+@pytest.mark.parametrize('fpath', pathlib.Path("docs").glob("**/*.md"), ids=str)
+def test_files_good(fpath):
+    check_md_file(fpath=fpath)
+```
+
+This will take any codeblock that starts with *\`\`\`python* and run it, checking
+for any errors that might happen. This means that if your docs contain asserts, that
+you get some unit-tests for free! 
+
+## Multiple Code Blocks 
+
+Let's suppose that you have the following markdown file: 
+
+    This is a code block
+
+    ```python
+    from operator import add
+    a = 1
+    b = 2
+    ```
+
+    This code-block should run fine.
+
+    ```python
+    assert add(1, 2) == 3
+    ```
+
+Then in this case the second code-block depends on the first code-block. The standard settings of `check_md_file` assume that each code-block needs to run independently. If you'd like to test markdown files with these sequential code-blocks be sure to set `memory=True`. 
+
+```python
+import pathlib
+
+from mktestdocs import check_md_file
+
+fpath = pathlib.Path("docs") / "multiple-code-blocks.md"
+
+try:
+    # Assume that cell-blocks are independent.
+    check_md_file(fpath=fpath)
+except NameError:
+    # But they weren't
+    pass
+
+# Assumes that cell-blocks depend on each other.
+check_md_file(fpath=fpath, memory=True)
+```
+
+## Markdown in Docstrings
+
+You might also have docstrings written in markdown. Those can be easily checked
+as well. 
+
+```python
+# I'm assuming that we've got a library called dinosaur
+from dinosaur import roar, super_roar
+
+import pytest
+from mktestdocs import check_docstring
+
+# Note the use of `__name__`, makes for pretty output
+@pytest.mark.parametrize('func', [roar, super_roar], ids=lambda d: d.__name__)
+def test_docstring(func):
+    check_docstring(obj=func)
+```
+
+There's even some utilities for grab all the docstrings from classes that you've defined. 
+
+```python
+# I'm assuming that we've got a library called dinosaur
+from dinosaur import Dinosaur
+
+import pytest
+from mktestdocs import check_docstring, get_codeblock_members
+
+# This retrieves all methods/properties that have a docstring.
+members = get_codeblock_members(Dinosaur)
+
+# Note the use of `__qualname__`, makes for pretty output
+@pytest.mark.parametrize("obj", members, ids=lambda d: d.__qualname__)
+def test_member(obj):
+    check_docstring(obj)
+```
+
+When you run these commands via `pytest --verbose` you should see informative test info being run. 
+
+If you're wondering why you'd want to write markdown in a docstring feel free to check out [mkdocstrings](https://github.com/mkdocstrings/mkdocstrings).
+
+## Bash Support
+
+Be default, bash code blocks are also supported. A markdown file that contains
+both python and bash code blocks can have each executed separately.
+
+    This will print the python version to the terminal
+
+    ```bash
+    python --version
+    ```
+
+    This will print the exact same version string
+
+    ```python
+    import sys
+
+    print(f"Python {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")
+    ```
+
+This markdown could be fully tested like this
+
+```python
+import pathlib
+
+from mktestdocs import check_md_file
+
+fpath = pathlib.Path("docs") / "bash-support.md"
+
+check_md_file(fpath=fpath, lang="python")
+check_md_file(fpath=fpath, lang="bash")
+```
+
+## Additional Language Support
+
+You can add support for languages other than python and bash by first
+registering a new executor for that language. The `register_executor` function
+takes a tag to specify the code block type supported, and a function that will
+be passed any code blocks found in markdown files.
+
+For example if you have a markdown file like this
+
+````markdown
+This is an example REST response
+
+```json
+{"body": {"results": ["spam", "eggs"]}, "errors": []}
+```
+````
+
+You could create a json validator that tested the example was always valid json like this
+
+```python
+import json
+import pathlib
+
+from mktestdocs import check_md_file, register_executor
+
+def parse_json(json_text):
+    json.loads(json_text)
+
+register_executor("json", parse_json)
+
+check_md_file(fpath=pathlib.Path("docs") / "additional-language-support.md", lang="json")
+```

{mktestdocs-0.2.1 → mktestdocs-0.2.5}/README.md

@@ -1,6 +1,6 @@
 <img src="icon.png" width=125 height=125 align="right">
 
-# mktestdocs
+### mktestdocs
 
 Run pytest against markdown files/docstrings.
 

mktestdocs-0.2.5/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mktestdocs"
+version = "0.2.5"
+description = "A tool for testing markdown documentation"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

{mktestdocs-0.2.1 → mktestdocs-0.2.5/src}/mktestdocs/__init__.py

@@ -1,4 +1,5 @@
-from mktestdocs.__main__ import (
+import importlib.metadata
+from .__main__ import (
     register_executor,
     check_codeblock,
     grab_code_blocks,
@@ -7,7 +8,7 @@ from mktestdocs.__main__ import (
     get_codeblock_members,
 )
 
-__version__ = "0.2.1"
+__version__ = importlib.metadata.version("mktestdocs")
 
 __all__ = [
     "__version__",

{mktestdocs-0.2.1 → mktestdocs-0.2.5/src}/mktestdocs/__main__.py

@@ -3,7 +3,6 @@ import pathlib
 import subprocess
 import textwrap
 
-
 _executors = {}
 
 
@@ -41,7 +40,7 @@ def exec_python(source):
     will propagate out unmodified
     """
     try:
-        exec(source, {"__MODULE__": "__main__"})
+        exec(source, {"__name__": "__main__"})
     except Exception:
         print(source)
         raise
@@ -51,7 +50,7 @@ register_executor("", exec_python)
 register_executor("python", exec_python)
 
 
-def get_codeblock_members(*classes):
+def get_codeblock_members(*classes, lang="python"):
     """
     Grabs the docstrings of any methods of any classes that are passed in.
     """
@@ -62,7 +61,7 @@ def get_codeblock_members(*classes):
         for name, member in inspect.getmembers(cl):
             if member.__doc__:
                 results.append(member)
-    return [m for m in results if len(grab_code_blocks(m.__doc__)) > 0]
+    return [m for m in results if len(grab_code_blocks(m.__doc__, lang=lang)) > 0]
 
 
 def check_codeblock(block, lang="python"):
@@ -77,7 +76,7 @@ def check_codeblock(block, lang="python"):
     """
     first_line = block.split("\n")[0]
     if lang:
-        if first_line[3:] != lang:
+        if first_line.lstrip()[3:] != lang:
             return ""
     return "\n".join(block.split("\n")[1:])
 
@@ -90,19 +89,27 @@ def grab_code_blocks(docstring, lang="python"):
         docstring: the docstring to analyse
         lang: if not None, the language that is assigned to the codeblock
     """
+    docstring = format_docstring(docstring)
     docstring = textwrap.dedent(docstring)
     in_block = False
     block = ""
     codeblocks = []
     for idx, line in enumerate(docstring.split("\n")):
-        if line.startswith("```"):
+        if "```" in line:
             if in_block:
                 codeblocks.append(check_codeblock(block, lang=lang))
                 block = ""
             in_block = not in_block
         if in_block:
             block += line + "\n"
-    return [c for c in codeblocks if c != ""]
+    return [textwrap.dedent(c) for c in codeblocks if c != ""]
+
+
+def format_docstring(docstring):
+    """Formats docstring to be able to successfully go through dedent."""
+    if docstring[:1] != "\n":
+        return f"\n    {docstring}"
+    return docstring
 
 
 def check_docstring(obj, lang=""):

mktestdocs-0.2.5/src/mktestdocs.egg-info/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: mktestdocs
+Version: 0.2.5
+Summary: A tool for testing markdown documentation
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+<img src="icon.png" width=125 height=125 align="right">
+
+### mktestdocs
+
+Run pytest against markdown files/docstrings.
+
+# Installation 
+
+```
+pip install mktestdocs
+```
+
+## Usage 
+
+Let's say that you're using [mkdocs](https://squidfunk.github.io/mkdocs-material/getting-started/) 
+for your documentation. Then you're writing down markdown to explain how your Python packages work. 
+It'd be a shame if a codeblock had an error in it, so it'd be 
+great if you could run your unit tests against them. 
+
+This package allows you to do _just that_. Here's an example:
+
+```python
+import pathlib
+import pytest
+
+from mktestdocs import check_md_file
+
+# Note the use of `str`, makes for pretty output
+@pytest.mark.parametrize('fpath', pathlib.Path("docs").glob("**/*.md"), ids=str)
+def test_files_good(fpath):
+    check_md_file(fpath=fpath)
+```
+
+This will take any codeblock that starts with *\`\`\`python* and run it, checking
+for any errors that might happen. This means that if your docs contain asserts, that
+you get some unit-tests for free! 
+
+## Multiple Code Blocks 
+
+Let's suppose that you have the following markdown file: 
+
+    This is a code block
+
+    ```python
+    from operator import add
+    a = 1
+    b = 2
+    ```
+
+    This code-block should run fine.
+
+    ```python
+    assert add(1, 2) == 3
+    ```
+
+Then in this case the second code-block depends on the first code-block. The standard settings of `check_md_file` assume that each code-block needs to run independently. If you'd like to test markdown files with these sequential code-blocks be sure to set `memory=True`. 
+
+```python
+import pathlib
+
+from mktestdocs import check_md_file
+
+fpath = pathlib.Path("docs") / "multiple-code-blocks.md"
+
+try:
+    # Assume that cell-blocks are independent.
+    check_md_file(fpath=fpath)
+except NameError:
+    # But they weren't
+    pass
+
+# Assumes that cell-blocks depend on each other.
+check_md_file(fpath=fpath, memory=True)
+```
+
+## Markdown in Docstrings
+
+You might also have docstrings written in markdown. Those can be easily checked
+as well. 
+
+```python
+# I'm assuming that we've got a library called dinosaur
+from dinosaur import roar, super_roar
+
+import pytest
+from mktestdocs import check_docstring
+
+# Note the use of `__name__`, makes for pretty output
+@pytest.mark.parametrize('func', [roar, super_roar], ids=lambda d: d.__name__)
+def test_docstring(func):
+    check_docstring(obj=func)
+```
+
+There's even some utilities for grab all the docstrings from classes that you've defined. 
+
+```python
+# I'm assuming that we've got a library called dinosaur
+from dinosaur import Dinosaur
+
+import pytest
+from mktestdocs import check_docstring, get_codeblock_members
+
+# This retrieves all methods/properties that have a docstring.
+members = get_codeblock_members(Dinosaur)
+
+# Note the use of `__qualname__`, makes for pretty output
+@pytest.mark.parametrize("obj", members, ids=lambda d: d.__qualname__)
+def test_member(obj):
+    check_docstring(obj)
+```
+
+When you run these commands via `pytest --verbose` you should see informative test info being run. 
+
+If you're wondering why you'd want to write markdown in a docstring feel free to check out [mkdocstrings](https://github.com/mkdocstrings/mkdocstrings).
+
+## Bash Support
+
+Be default, bash code blocks are also supported. A markdown file that contains
+both python and bash code blocks can have each executed separately.
+
+    This will print the python version to the terminal
+
+    ```bash
+    python --version
+    ```
+
+    This will print the exact same version string
+
+    ```python
+    import sys
+
+    print(f"Python {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")
+    ```
+
+This markdown could be fully tested like this
+
+```python
+import pathlib
+
+from mktestdocs import check_md_file
+
+fpath = pathlib.Path("docs") / "bash-support.md"
+
+check_md_file(fpath=fpath, lang="python")
+check_md_file(fpath=fpath, lang="bash")
+```
+
+## Additional Language Support
+
+You can add support for languages other than python and bash by first
+registering a new executor for that language. The `register_executor` function
+takes a tag to specify the code block type supported, and a function that will
+be passed any code blocks found in markdown files.
+
+For example if you have a markdown file like this
+
+````markdown
+This is an example REST response
+
+```json
+{"body": {"results": ["spam", "eggs"]}, "errors": []}
+```
+````
+
+You could create a json validator that tested the example was always valid json like this
+
+```python
+import json
+import pathlib
+
+from mktestdocs import check_md_file, register_executor
+
+def parse_json(json_text):
+    json.loads(json_text)
+
+register_executor("json", parse_json)
+
+check_md_file(fpath=pathlib.Path("docs") / "additional-language-support.md", lang="json")
+```

mktestdocs-0.2.5/src/mktestdocs.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/mktestdocs/__init__.py
+src/mktestdocs/__main__.py
+src/mktestdocs.egg-info/PKG-INFO
+src/mktestdocs.egg-info/SOURCES.txt
+src/mktestdocs.egg-info/dependency_links.txt
+src/mktestdocs.egg-info/requires.txt
+src/mktestdocs.egg-info/top_level.txt
+tests/test_actual_docstrings.py
+tests/test_class.py
+tests/test_codeblock.py
+tests/test_format_docstring.py
+tests/test_markdown.py
+tests/test_mktestdocs.py

mktestdocs-0.2.5/src/mktestdocs.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest

mktestdocs-0.2.5/tests/test_actual_docstrings.py

@@ -0,0 +1,74 @@
+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
+    ```
+    """
+    pass
+
+
+def foobar_also_good(a, b):
+    """
+    ```python
+    import random
+
+    assert random.random() < 10
+    ```
+    """
+    pass
+
+
+def foobar_bad(a, b):
+    """
+    ```python
+    assert foobar(1, 2) == 4
+    ```
+    """
+    pass
+
+
+def admonition_edge_cases():
+    """
+    !!! note
+
+        All cells of a table are initialized with an empty string. Therefore, to delete the content of a cell,
+        you need to assign an empty string, i.e. `''`. For instance, to delete the first row after the header:
+
+        ```python
+        assert 1 + 2 == 3
+        ```"""
+    pass
+
+def adminition_edge_case_bad():
+    """Test that we can handle the edge cases of admonitions."""
+    example = """!!! note
+
+    Another one. 
+    ```python
+    assert 1 + 2 == 4
+    ```"""
+    pass
+
+@pytest.mark.parametrize("func", [foobar_good, foobar_also_good, admonition_edge_cases])
+def test_base_docstrings(func):
+    check_docstring(func)
+
+
+@pytest.mark.parametrize("func", [foobar_bad, adminition_edge_case_bad])
+def test_base_docstrings_bad(func, capsys):
+    with pytest.raises(Exception):
+        check_docstring(func)
+        capsys.readouterr()
+        assert func.__name__ in capsys.readouterr().out

{mktestdocs-0.2.1 → mktestdocs-0.2.5}/tests/test_class.py

@@ -60,12 +60,27 @@ class Dinosaur:
         """
         return self.name
 
+    def hfdocs_style(self, value):
+        """
+        Returns value
+
+        Example:
+
+            ```python
+            from dinosaur import Dinosaur
+
+            dino = Dinosaur()
+            assert dino.a(1) == 1
+            ```
+        """
+        return value
+
 
 members = get_codeblock_members(Dinosaur)
 
 
 def test_grab_methods():
-    assert len(get_codeblock_members(Dinosaur)) == 4
+    assert len(get_codeblock_members(Dinosaur)) == 5
 
 
 @pytest.mark.parametrize("obj", members, ids=lambda d: d.__qualname__)

mktestdocs-0.2.5/tests/test_format_docstring.py

@@ -0,0 +1,61 @@
+import pytest
+
+from mktestdocs import get_codeblock_members
+from mktestdocs.__main__ import format_docstring
+
+
+def test_docstring_formatted():
+    # given (a docstring not prepared for dedent)
+    docstring = "Some class with a header and a code block"
+    # when (we go through the format_docstring function)
+    formatted = format_docstring(docstring)
+    # then (a new line and tab are added to the docstring)
+    assert formatted == "\n    Some class with a header and a code block"
+
+def test_docstring_not_formatted():
+    # given (a docstring prepared for dedent)
+    docstring = "\n    Some class with a header and a code block"
+    # when (we go through the format_docstring function)
+    formatted = format_docstring(docstring)
+    # then (the docstring doesn't change)
+    assert formatted == docstring
+
+
+
+# The docstring of the first class starts like
+# """Some class ...
+# The docstring of the second class starts like
+# """
+# Some class ...
+# The tests are checking that regardless of how the class docstring starts we should always be able to read the tests
+class BadClass:
+    """Some class with a header and a code block.
+
+    ```python
+    assert False, "this should fail."
+    ```
+    
+    """
+    def __init__(self):
+        pass
+
+class BadClassNewLine:
+    """
+    Some class with a header and a code block.
+
+    ```python
+    assert False, "this should fail."
+    ```
+    
+    """
+    def __init__(self):
+        pass
+
+
+
+@pytest.mark.parametrize("cls", [BadClass, BadClassNewLine], ids=lambda d: d.__qualname__)
+def test_grab_bad_methods(cls):
+    bad_members = get_codeblock_members(cls)
+    assert len(bad_members) == 1
+
+

{mktestdocs-0.2.1 → mktestdocs-0.2.5}/tests/test_mktestdocs.py

@@ -2,9 +2,10 @@ import pathlib
 
 from mktestdocs import check_md_file
 
+
 def test_readme(monkeypatch):
     test_dir = pathlib.Path(__file__).parent
     fpath = test_dir.parent / "README.md"
     monkeypatch.chdir(test_dir)
 
-    check_md_file(fpath=fpath)
+    check_md_file(fpath=fpath, memory=True)

mktestdocs-0.2.1/PKG-INFO

@@ -1,5 +0,0 @@
-Metadata-Version: 2.1
-Name: mktestdocs
-Version: 0.2.1
-Provides-Extra: test
-License-File: LICENSE

mktestdocs-0.2.1/mktestdocs.egg-info/PKG-INFO

@@ -1,5 +0,0 @@
-Metadata-Version: 2.1
-Name: mktestdocs
-Version: 0.2.1
-Provides-Extra: test
-License-File: LICENSE

mktestdocs-0.2.1/mktestdocs.egg-info/SOURCES.txt

@@ -1,15 +0,0 @@
-LICENSE
-README.md
-setup.py
-mktestdocs/__init__.py
-mktestdocs/__main__.py
-mktestdocs.egg-info/PKG-INFO
-mktestdocs.egg-info/SOURCES.txt
-mktestdocs.egg-info/dependency_links.txt
-mktestdocs.egg-info/requires.txt
-mktestdocs.egg-info/top_level.txt
-tests/test_actual_docstrings.py
-tests/test_class.py
-tests/test_codeblock.py
-tests/test_markdown.py
-tests/test_mktestdocs.py

mktestdocs-0.2.1/mktestdocs.egg-info/requires.txt

@@ -1,3 +0,0 @@
-
-[test]
-pytest>=4.0.2

mktestdocs-0.2.1/setup.py

@@ -1,14 +0,0 @@
-from mktestdocs import __version__
-from setuptools import setup, find_packages
-
-test_packages = ["pytest>=4.0.2"]
-
-setup(
-    name="mktestdocs",
-    version=__version__,
-    packages=find_packages(exclude=["tests"]),
-    install_requires=[],
-    extras_require={
-        "test": test_packages,
-    },
-)

mktestdocs-0.2.1/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