pytest-markdown-docs 0.6.0__tar.gz → 0.7.1__tar.gz

pytest_markdown_docs-0.7.1/Makefile

@@ -0,0 +1,8 @@
+build:
+	uv build
+
+clean:
+	rm -rf dist
+
+publish: clean build
+	uv publish

pytest_markdown_docs-0.6.0/README.md → pytest_markdown_docs-0.7.1/PKG-INFO

@@ -1,3 +1,15 @@
+Metadata-Version: 2.3
+Name: pytest-markdown-docs
+Version: 0.7.1
+Summary: Run markdown code fences through pytest
+Author: Modal Labs
+Author-email: Elias Freider <elias@modal.com>
+License: MIT
+Requires-Python: >=3.8
+Requires-Dist: markdown-it-py<4.0,>=2.2.0
+Requires-Dist: pytest>=7.0.0
+Description-Content-Type: text/markdown
+
 # Pytest Markdown Docs
 
 A plugin for [pytest](https://docs.pytest.org) that uses markdown code snippets from markdown files and docstrings as tests.
@@ -136,6 +148,20 @@ assert a + " world" == "hello world"
 ```
 ````
 
+### Compatibility with Material for MkDocs
+
+Material for Mkdocs is not compatible with the default syntax.
+
+But if the extension `pymdownx.superfences` is configured for mkdocs, the brace format can be used:
+````markdown
+```{.python continuation}
+````
+
+You will need to call pytest with the `--markdown-docs-syntax` option:
+```shell
+pytest --markdown-docs --markdown-docs-syntax=superfences
+```
+
 ## MDX Comments for Metadata Options
 In .mdx files, you can use MDX comments to provide additional options for code blocks. These comments should be placed immediately before the code block and take the following form:
 
@@ -175,4 +201,4 @@ Or for fun, you can use this plugin to include testing of the validity of snippe
   * Line numbers are "wrong" for docstring-inlined snippets (since we don't know where in the file the docstring starts)
   * Line numbers are "wrong" for continuation blocks even in pure markdown files (can be worked out with some refactoring)
 * There are probably more appropriate ways to use pytest internal APIs to get more features "for free" - current state of the code is a bit "patch it til' it works".
-* Assertions are not rewritten w/ pretty data structure inspection like they are with regular pytest tests by default
+* Assertions are not rewritten w/ pretty data structure inspection like they are with regular pytest tests by default

pytest_markdown_docs-0.6.0/PKG-INFO → pytest_markdown_docs-0.7.1/README.md

@@ -1,16 +1,3 @@
-Metadata-Version: 2.3
-Name: pytest-markdown-docs
-Version: 0.6.0
-Summary: Run markdown code fences through pytest
-Author: Modal Labs
-Author-email: Elias Freider <elias@modal.com>
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.8
-Requires-Dist: markdown-it-py<4.0,>=2.2.0
-Requires-Dist: pytest>=7.0.0
-Description-Content-Type: text/markdown
-
 # Pytest Markdown Docs
 
 A plugin for [pytest](https://docs.pytest.org) that uses markdown code snippets from markdown files and docstrings as tests.
@@ -149,6 +136,20 @@ assert a + " world" == "hello world"
 ```
 ````
 
+### Compatibility with Material for MkDocs
+
+Material for Mkdocs is not compatible with the default syntax.
+
+But if the extension `pymdownx.superfences` is configured for mkdocs, the brace format can be used:
+````markdown
+```{.python continuation}
+````
+
+You will need to call pytest with the `--markdown-docs-syntax` option:
+```shell
+pytest --markdown-docs --markdown-docs-syntax=superfences
+```
+
 ## MDX Comments for Metadata Options
 In .mdx files, you can use MDX comments to provide additional options for code blocks. These comments should be placed immediately before the code block and take the following form:
 
@@ -188,4 +189,4 @@ Or for fun, you can use this plugin to include testing of the validity of snippe
   * Line numbers are "wrong" for docstring-inlined snippets (since we don't know where in the file the docstring starts)
   * Line numbers are "wrong" for continuation blocks even in pure markdown files (can be worked out with some refactoring)
 * There are probably more appropriate ways to use pytest internal APIs to get more features "for free" - current state of the code is a bit "patch it til' it works".
-* Assertions are not rewritten w/ pretty data structure inspection like they are with regular pytest tests by default
+* Assertions are not rewritten w/ pretty data structure inspection like they are with regular pytest tests by default

{pytest_markdown_docs-0.6.0 → pytest_markdown_docs-0.7.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytest-markdown-docs"
-version = "0.6.0"
+version = "0.7.1"
 description = "Run markdown code fences through pytest"
 readme = "README.md"
 authors = [
@@ -30,5 +30,3 @@ dev-dependencies = [
     "pytest~=8.1.0",
     "ruff>=0.7.0",
 ]
-
-

pytest_markdown_docs-0.7.1/pytest-markdown-docs.iml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/tests" isTestSource="true" />
+      <excludeFolder url="file://$MODULE_DIR$/dist" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

{pytest_markdown_docs-0.6.0 → pytest_markdown_docs-0.7.1}/src/pytest_markdown_docs/plugin.py

@@ -3,12 +3,17 @@ import inspect
 import traceback
 import types
 import pathlib
+from dataclasses import dataclass
+
 import pytest
 import typing
+from enum import Enum
 
 from _pytest._code import ExceptionInfo
 from _pytest.config.argparsing import Parser
 from _pytest.pathlib import import_path
+import logging
+
 from pytest_markdown_docs import hooks
 
 
@@ -22,9 +27,46 @@ else:
 if typing.TYPE_CHECKING:
     from markdown_it.token import Token
 
+logger = logging.getLogger("pytest-markdown-docs")
+
 MARKER_NAME = "markdown-docs"
 
 
+class FenceSyntax(Enum):
+    default = "default"
+    superfences = "superfences"
+
+
+@dataclass(frozen=True)
+class FenceTest:
+    source: str
+    fixture_names: typing.Tuple[str, ...]
+    start_line: int
+
+
+@dataclass(frozen=True)
+class ObjectTest:
+    intra_object_index: int
+    object_name: str
+    fence_test: FenceTest
+
+
+def get_docstring_start_line(obj) -> typing.Optional[int]:
+    # Get the source lines and the starting line number of the object
+    try:
+        source_lines, start_line = inspect.getsourcelines(obj)
+    except OSError:
+        return None
+
+    # Find the line in the source code that starts with triple quotes (""" or ''')
+    for idx, line in enumerate(source_lines):
+        line = line.strip()
+        if line.startswith(('"""', "'''")):
+            return start_line + idx  # Return the starting line number
+
+    return None  # Docstring not found in source
+
+
 class MarkdownInlinePythonItem(pytest.Item):
     def __init__(
         self,
@@ -33,7 +75,6 @@ class MarkdownInlinePythonItem(pytest.Item):
         code: str,
         fixture_names: typing.List[str],
         start_line: int,
-        fake_line_numbers: bool,
     ) -> None:
         super().__init__(name, parent)
         self.add_marker(MARKER_NAME)
@@ -41,7 +82,6 @@ class MarkdownInlinePythonItem(pytest.Item):
         self.obj = None
         self.user_properties.append(("code", code))
         self.start_line = start_line
-        self.fake_line_numbers = fake_line_numbers
         self.fixturenames = fixture_names
         self.nofuncargs = True
 
@@ -93,58 +133,47 @@ class MarkdownInlinePythonItem(pytest.Item):
         excinfo: ExceptionInfo[BaseException],
         style=None,
     ):
-        rawlines = self.code.split("\n")
+        rawlines = self.code.rstrip("\n").split("\n")
 
         # custom formatted traceback to translate line numbers and markdown files
         traceback_lines = []
         stack_summary = traceback.StackSummary.extract(traceback.walk_tb(excinfo.tb))
         start_capture = False
 
-        start_line = 0 if self.fake_line_numbers else self.start_line
+        start_line = self.start_line
 
         for frame_summary in stack_summary:
             if frame_summary.filename == str(self.path):
-                lineno = (frame_summary.lineno or 0) + start_line
-                start_capture = (
-                    True  # start capturing frames the first time we enter user code
-                )
-                line = (
-                    rawlines[frame_summary.lineno - 1] if frame_summary.lineno else ""
-                )
-            else:
-                lineno = frame_summary.lineno or 0
-                line = frame_summary.line or ""
+                # start capturing frames the first time we enter user code
+                start_capture = True
 
             if start_capture:
+                lineno = frame_summary.lineno
+                line = frame_summary.line or ""
                 linespec = f"line {lineno}"
-                if self.fake_line_numbers:
-                    linespec = f"code block line {lineno}*"
-
                 traceback_lines.append(
                     f"""  File "{frame_summary.filename}", {linespec}, in {frame_summary.name}"""
                 )
                 traceback_lines.append(f"    {line.lstrip()}")
 
-        maxnum = len(str(len(rawlines) + start_line + 1))
+        maxdigits = len(str(len(rawlines)))
+        code_margin = "   "
         numbered_code = "\n".join(
             [
-                f"{i:>{maxnum}}   {line}"
-                for i, line in enumerate(rawlines, start_line + 1)
+                f"{i:>{maxdigits}}{code_margin}{line}"
+                for i, line in enumerate(rawlines[start_line:], start_line + 1)
             ]
         )
 
         pretty_traceback = "\n".join(traceback_lines)
-        note = ""
-        if self.fake_line_numbers:
-            note = ", *-denoted line numbers refer to code block"
-        pt = f"""Traceback (most recent call last{note}):
+        pt = f"""Traceback (most recent call last):
 {pretty_traceback}
 {excinfo.exconly()}"""
 
         return f"""Error in code block:
-```
+{maxdigits * " "}{code_margin}```
 {numbered_code}
-```
+{maxdigits * " "}{code_margin}```
 {pt}
 """
 
@@ -152,10 +181,12 @@ class MarkdownInlinePythonItem(pytest.Item):
         return self.name, 0, self.nodeid
 
 
-def extract_code_blocks(
+def extract_fence_tests(
     markdown_string: str,
+    start_line_offset: int,
     markdown_type: str = "md",
-) -> typing.Generator[typing.Tuple[str, typing.List[str], int], None, None]:
+    fence_syntax: FenceSyntax = FenceSyntax.default,
+) -> typing.Generator[FenceTest, None, None]:
     import markdown_it
 
     mi = markdown_it.MarkdownIt(config="commonmark")
@@ -166,8 +197,10 @@ def extract_code_blocks(
         if block.type != "fence" or not block.map:
             continue
 
-        startline = block.map[0] + 1  # skip the info line when counting
-        code_info = block.info.split()
+        if fence_syntax == FenceSyntax.superfences:
+            code_info = parse_superfences_block_info(block.info)
+        else:
+            code_info = block.info.split()
 
         lang = code_info[0] if code_info else None
         code_options = set(code_info) - {lang}
@@ -187,19 +220,50 @@ def extract_code_blocks(
                 code_options |= extract_options_from_mdx_comment(tokens[i - 2].content)
 
         if lang in ("py", "python", "python3") and "notest" not in code_options:
-            code_block = block.content
+            start_line = (
+                start_line_offset + block.map[0] + 1
+            )  # actual code starts on +1 from the "info" line
+            if "continuation" not in code_options:
+                prev = ""
 
-            if "continuation" in code_options:
-                code_block = prev + code_block
-                startline = -1  # this disables proper line numbers, TODO: adjust line numbers *per snippet*
+            add_blank_lines = start_line - prev.count("\n")
+            code_block = prev + ("\n" * add_blank_lines) + block.content
 
-            fixture_names = [
+            fixture_names = tuple(
                 f[len("fixture:") :] for f in code_options if f.startswith("fixture:")
-            ]
-            yield code_block, fixture_names, startline
+            )
+            yield FenceTest(code_block, fixture_names, start_line)
             prev = code_block
 
 
+def parse_superfences_block_info(block_info: str) -> typing.List[str]:
+    """Parse PyMdown Superfences block info syntax.
+
+    The default `python continuation` format is not compatible with Material for Mkdocs.
+    But, PyMdown Superfences has a special brace format to add options to code fence blocks: `{.<lang> <option1> <option2>}`.
+
+    This function also works if the default syntax is used to allow for mixed usage.
+    """
+    block_info = block_info.strip()
+
+    if not block_info.startswith("{"):
+        # default syntax
+        return block_info.split()
+
+    block_info = block_info.strip("{}")
+    code_info = block_info.split()
+    # Lang may not be the first but is always the first element that starts with a dot.
+    # (https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#injecting-classes-ids-and-attributes)
+    dot_lang = next(
+        (info_part for info_part in code_info if info_part.startswith(".")), None
+    )
+    if dot_lang:
+        code_info.remove(dot_lang)
+        lang = dot_lang[1:]
+        code_info.insert(0, lang)
+    return code_info
+
+
 def is_mdx_comment(block: "Token") -> bool:
     return (
         block.type == "inline"
@@ -219,29 +283,6 @@ def extract_options_from_mdx_comment(comment: str) -> typing.Set[str]:
     return set(option.strip() for option in comment.split(" ") if option)
 
 
-def find_object_tests_recursive(
-    module_name: str, object: typing.Any
-) -> typing.Generator[
-    typing.Tuple[int, typing.Any, typing.Tuple[str, typing.List[str], int]], None, None
-]:
-    docstr = inspect.getdoc(object)
-
-    if docstr:
-        for i, code_block in enumerate(extract_code_blocks(docstr)):
-            yield i, object, code_block
-
-    for member_name, member in inspect.getmembers(object):
-        if member_name.startswith("_"):
-            continue
-
-        if (
-            inspect.isclass(member)
-            or inspect.isfunction(member)
-            or inspect.ismethod(member)
-        ) and member.__module__ == module_name:
-            yield from find_object_tests_recursive(module_name, member)
-
-
 class MarkdownDocstringCodeModule(pytest.Module):
     def collect(self):
         if pytest.version_tuple >= (8, 1, 0):
@@ -250,45 +291,90 @@ class MarkdownDocstringCodeModule(pytest.Module):
                 self.path, root=self.config.rootpath, consider_namespace_packages=True
             )
         else:
-            # but unsupported before 8.1...
+            # but unsupported before pytest 8.1...
             module = import_path(self.path, root=self.config.rootpath)
 
-        for code_block_idx, obj, (
-            test_code,
-            fixture_names,
-            start_line,
-        ) in find_object_tests_recursive(module.__name__, module):
-            obj_name = (
-                getattr(obj, "__qualname__", None)
-                or getattr(obj, "__name__", None)
-                or "<Unnamed obj>"
-            )
+        for object_test in self.find_object_tests_recursive(
+            module.__name__, module, set(), set()
+        ):
+            fence_test = object_test.fence_test
             yield MarkdownInlinePythonItem.from_parent(
                 self,
-                name=f"{obj_name}[CodeBlock#{code_block_idx+1}][rel.line:{start_line}]",
-                code=test_code,
-                fixture_names=fixture_names,
-                start_line=start_line,
-                fake_line_numbers=True,  # TODO: figure out where docstrings are in file to offset line numbers properly
+                name=f"{object_test.object_name}[CodeFence#{object_test.intra_object_index+1}][line:{fence_test.start_line}]",
+                code=fence_test.source,
+                fixture_names=fence_test.fixture_names,
+                start_line=fence_test.start_line,
             )
 
+    def find_object_tests_recursive(
+        self,
+        module_name: str,
+        object: typing.Any,
+        _visited_objects: typing.Set[int],
+        _found_tests: typing.Set[typing.Tuple[str, int]],
+    ) -> typing.Generator[ObjectTest, None, None]:
+        if id(object) in _visited_objects:
+            return
+        _visited_objects.add(id(object))
+        docstr = inspect.getdoc(object)
+
+        for member_name, member in inspect.getmembers(object):
+            if (
+                inspect.isclass(member)
+                or inspect.isfunction(member)
+                or inspect.ismethod(member)
+            ) and member.__module__ == module_name:
+                yield from self.find_object_tests_recursive(
+                    module_name, member, _visited_objects, _found_tests
+                )
+
+        if docstr:
+            docstring_offset = get_docstring_start_line(object)
+            if docstring_offset is None:
+                logger.warning(
+                    f"Could not find line number offset for docstring: {docstr}"
+                )
+            else:
+                obj_name = (
+                    getattr(object, "__qualname__", None)
+                    or getattr(object, "__name__", None)
+                    or "<Unnamed obj>"
+                )
+                fence_syntax = FenceSyntax(self.config.option.markdowndocs_syntax)
+                for i, fence_test in enumerate(
+                    extract_fence_tests(
+                        docstr, docstring_offset, fence_syntax=fence_syntax
+                    )
+                ):
+                    found_test = ObjectTest(i, obj_name, fence_test)
+                    found_test_location = (
+                        module_name,
+                        found_test.fence_test.start_line,
+                    )
+                    if found_test_location not in _found_tests:
+                        _found_tests.add(found_test_location)
+                        yield found_test
+
 
 class MarkdownTextFile(pytest.File):
     def collect(self):
         markdown_content = self.path.read_text("utf8")
-
-        for i, (code_block, fixture_names, start_line) in enumerate(
-            extract_code_blocks(
-                markdown_content, markdown_type=self.path.suffix.replace(".", "")
+        fence_syntax = FenceSyntax(self.config.option.markdowndocs_syntax)
+
+        for i, fence_test in enumerate(
+            extract_fence_tests(
+                markdown_content,
+                start_line_offset=0,
+                markdown_type=self.path.suffix.replace(".", ""),
+                fence_syntax=fence_syntax,
             )
         ):
             yield MarkdownInlinePythonItem.from_parent(
                 self,
-                name=f"[CodeBlock#{i+1}][line:{start_line}]",
-                code=code_block,
-                fixture_names=fixture_names,
-                start_line=start_line,
-                fake_line_numbers=start_line == -1,
+                name=f"[CodeFence#{i+1}][line:{fence_test.start_line}]",
+                code=fence_test.source,
+                fixture_names=fence_test.fixture_names,
+                start_line=fence_test.start_line,
             )
 
 
@@ -321,6 +407,14 @@ def pytest_addoption(parser: Parser) -> None:
         help="run ",
         dest="markdowndocs",
     )
+    group.addoption(
+        "--markdown-docs-syntax",
+        action="store",
+        choices=[choice.value for choice in FenceSyntax],
+        default="default",
+        help="Choose an alternative fences syntax",
+        dest="markdowndocs_syntax",
+    )
 
 
 def pytest_addhooks(pluginmanager):

pytest_markdown_docs-0.7.1/tests/conftest.py

@@ -0,0 +1,10 @@
+from pathlib import Path
+
+import pytest
+
+pytest_plugins = ["pytester"]
+
+
+@pytest.fixture()
+def support_dir():
+    return Path(__file__).parent / "support"

{pytest_markdown_docs-0.6.0 → pytest_markdown_docs-0.7.1}/tests/plugin_test.py

@@ -1,4 +1,7 @@
 import re
+
+from _pytest.pytester import LineMatcher
+
 import pytest_markdown_docs  # hack: used for storing a side effect in one of the tests
 
 
@@ -122,7 +125,7 @@ def test_traceback(testdir):
     # we check the traceback vs a regex pattern since the file paths can change
     expected_output_pattern = r"""
 Error in code block:
-```
+     ```
  4   def foo\(\):
  5       raise Exception\("doh"\)
  6
@@ -130,8 +133,7 @@ Error in code block:
  8       foo\(\)
  9
 10   foo\(\)
-11
-```
+     ```
 Traceback \(most recent call last\):
   File ".*/test_traceback.md", line 10, in <module>
     foo\(\)
@@ -350,3 +352,82 @@ def test_notest_mdx_comment(testdir):
     )
     result = testdir.runpytest("--markdown-docs")
     result.assert_outcomes(passed=0)
+
+
+def test_superfences_format_markdown(testdir):
+    testdir.makefile(
+        ".md",
+        """
+        ```python
+        b = "hello"
+        ```
+
+        ```{.python continuation}
+        assert b + " world" == "hello world"
+        ```
+
+        # the lang may not be the first element
+        ```{other_option .python .other-class continuation}
+        assert b + " world" == "hello world"
+        ```
+    """,
+    )
+    result = testdir.runpytest("--markdown-docs", "--markdown-docs-syntax=superfences")
+    result.assert_outcomes(passed=3)
+
+
+def test_superfences_format_docstring(testdir):
+    testdir.makepyfile(
+        """
+        def simple():
+            \"\"\"
+            ```python
+            b = "hello"
+            ```
+
+            ```{.python continuation}
+            assert b + " world" == "hello world"
+            ```
+            \"\"\"
+        """
+    )
+    result = testdir.runpytest("--markdown-docs", "--markdown-docs-syntax=superfences")
+    result.assert_outcomes(passed=2)
+
+
+def test_error_origin_after_docstring_traceback(testdir, support_dir):
+    sample_file = support_dir / "docstring_error_after.py"
+    testdir.makepyfile(**{sample_file.stem: sample_file.read_text()})
+    result = testdir.runpytest("-v", "--markdown-docs")
+
+    data: LineMatcher = result.stdout
+    data.re_match_lines(
+        [
+            r"Traceback \(most recent call last\):",
+            r'\s*File ".*/docstring_error_after.py", line 5, in <module>',
+            r"\s*docstring_error_after.error_after\(\)",
+            r'\s*File ".*/docstring_error_after.py", line 11, in error_after',
+            r'\s*raise Exception\("bar"\)',
+            r"\s*Exception: bar",
+        ],
+        consecutive=True,
+    )
+
+
+def test_error_origin_before_docstring_traceback(testdir, support_dir):
+    sample_file = support_dir / "docstring_error_before.py"
+    testdir.makepyfile(**{sample_file.stem: sample_file.read_text()})
+    result = testdir.runpytest("-v", "--markdown-docs")
+
+    data: LineMatcher = result.stdout
+    data.re_match_lines(
+        [
+            r"Traceback \(most recent call last\):",
+            r'\s*File ".*/docstring_error_before.py", line 9, in <module>',
+            r"\s*docstring_error_before.error_before\(\)",
+            r'\s*File ".*/docstring_error_before.py", line 2, in error_before',
+            r'\s*raise Exception\("foo"\)',
+            r"\s*Exception: foo",
+        ],
+        consecutive=True,
+    )

pytest_markdown_docs-0.7.1/tests/support/docstring_error_after.py

@@ -0,0 +1,11 @@
+def func():
+    """
+    ```python
+    import docstring_error_after
+    docstring_error_after.error_after()
+    ```
+    """
+
+
+def error_after():
+    raise Exception("bar")

pytest_markdown_docs-0.7.1/tests/support/docstring_error_before.py

@@ -0,0 +1,11 @@
+def error_before():
+    raise Exception("foo")
+
+
+def func():
+    """
+    ```python
+    import docstring_error_before
+    docstring_error_before.error_before()
+    ```
+    """