push

Author: aaazzam

README.md

@@ -210,7 +210,7 @@ expected output
 You can also register a runner as the default for one or more fence languages:
 
 ```python
-@pytest_markdown_docs._runners.register_runner(languages=("text",))
+@pytest_markdown_docs._runners.register_runner(default_for=("text",))
 class TextRunner(pytest_markdown_docs._runners.DefaultRunner):
     def runtest(self, test, args):
         assert "expected output" in test.source
@@ -224,6 +224,17 @@ expected output
 ```
 ````
 
+Runner selection uses this order:
+
+1. A fence with `runner:<name>` uses that named runner.
+2. A fence whose language is listed in `default_for` uses that runner.
+3. Built-in Python fences (`py`, `python`, `python3`) use the global default
+   runner.
+
+This means `default_for=("python",)` affects only ```` ```python ```` fences,
+while `default=True` changes the global default used by Python fences that do
+not have a more specific runner.
+
 ### Compatibility with Material for MkDocs
 
 Material for Mkdocs is not compatible with the default syntax.

src/pytest_markdown_docs/_runners.py

@@ -33,7 +33,7 @@ def repr_failure(
 def register_runner(
     *,
     default: bool = False,
-    languages: typing.Collection[str] = (),
+    default_for: typing.Collection[str] = (),
 ):
     """Decorator for adding custom runners
 
@@ -49,7 +49,7 @@ def decorator(r: RUNNER_TYPE) -> RUNNER_TYPE:
         _registered_runners[r.__name__] = runner
         if default:
             _default_runner = runner
-        for language in languages:
+        for language in default_for:
             _registered_language_runner_names[language] = r.__name__
         return r
 

tests/plugin_test.py

@@ -526,8 +526,8 @@ def test_language_runner_collects_non_python_fence(testdir):
         import pytest_markdown_docs
         import pytest_markdown_docs._runners
 
-        @pytest_markdown_docs._runners.register_runner(languages=("text",))
-        class LanguageTextRunner(pytest_markdown_docs._runners.DefaultRunner):
+        @pytest_markdown_docs._runners.register_runner(default_for=("text",))
+        class DefaultForTextRunner(pytest_markdown_docs._runners.DefaultRunner):
             def runtest(self, test, args):
                 pytest_markdown_docs.language_text_fence = test.source.strip()
     """
@@ -549,6 +549,109 @@ def runtest(self, test, args):
     delattr(pytest_markdown_docs, "language_text_fence")
 
 
+def test_default_for_python_language_does_not_replace_global_default(testdir):
+    import pytest_markdown_docs._runners
+
+    pytest_markdown_docs._runners._registered_language_runner_names.pop("python", None)
+    if hasattr(pytest_markdown_docs, "default_for_python_runs"):
+        delattr(pytest_markdown_docs, "default_for_python_runs")
+
+    testdir.makeconftest(
+        """
+        import pytest_markdown_docs
+        import pytest_markdown_docs._runners
+
+        @pytest_markdown_docs._runners.register_runner(default_for=("python",))
+        class DefaultForPythonRunner(pytest_markdown_docs._runners.DefaultRunner):
+            def runtest(self, test, args):
+                runs = getattr(pytest_markdown_docs, "default_for_python_runs", [])
+                runs.append(test.source.strip())
+                pytest_markdown_docs.default_for_python_runs = runs
+    """
+    )
+    testdir.makefile(
+        ".md",
+        """
+        ```python
+        handled by language default
+        ```
+
+        ```py
+        handled by global default
+        ```
+    """,
+    )
+    result = testdir.runpytest("--markdown-docs")
+    result.assert_outcomes(passed=1, failed=1)
+    assert getattr(pytest_markdown_docs, "default_for_python_runs", None) == [
+        "handled by language default"
+    ]
+    pytest_markdown_docs._runners._registered_language_runner_names.pop("python", None)
+    delattr(pytest_markdown_docs, "default_for_python_runs")
+
+
+def test_explicit_runner_takes_precedence_over_default_for(testdir):
+    if hasattr(pytest_markdown_docs, "selected_text_runner"):
+        delattr(pytest_markdown_docs, "selected_text_runner")
+
+    testdir.makeconftest(
+        """
+        import pytest_markdown_docs
+        import pytest_markdown_docs._runners
+
+        @pytest_markdown_docs._runners.register_runner(default_for=("text",))
+        class DefaultForTextRunner(pytest_markdown_docs._runners.DefaultRunner):
+            def runtest(self, test, args):
+                pytest_markdown_docs.selected_text_runner = "default_for"
+
+        @pytest_markdown_docs._runners.register_runner()
+        class ExplicitTextRunner(pytest_markdown_docs._runners.DefaultRunner):
+            def runtest(self, test, args):
+                pytest_markdown_docs.selected_text_runner = "explicit"
+    """
+    )
+    testdir.makefile(
+        ".md",
+        """
+        ```text runner:ExplicitTextRunner
+        hello from explicit text
+        ```
+    """,
+    )
+    result = testdir.runpytest("--markdown-docs")
+    result.assert_outcomes(passed=1)
+    assert getattr(pytest_markdown_docs, "selected_text_runner", None) == "explicit"
+    delattr(pytest_markdown_docs, "selected_text_runner")
+
+
+def test_notest_takes_precedence_over_default_for(testdir):
+    if hasattr(pytest_markdown_docs, "default_for_notest_fence"):
+        delattr(pytest_markdown_docs, "default_for_notest_fence")
+
+    testdir.makeconftest(
+        """
+        import pytest_markdown_docs
+        import pytest_markdown_docs._runners
+
+        @pytest_markdown_docs._runners.register_runner(default_for=("text",))
+        class DefaultForTextRunner(pytest_markdown_docs._runners.DefaultRunner):
+            def runtest(self, test, args):
+                pytest_markdown_docs.default_for_notest_fence = test.source.strip()
+    """
+    )
+    testdir.makefile(
+        ".md",
+        """
+        ```text notest
+        this should not run
+        ```
+    """,
+    )
+    result = testdir.runpytest("--markdown-docs")
+    result.assert_outcomes(passed=0)
+    assert not hasattr(pytest_markdown_docs, "default_for_notest_fence")
+
+
 def test_multiple_runner_options_error_for_non_python_fence(testdir):
     testdir.makefile(
         ".md",