Use Sybil for doctests (#142)

* Use Sybil for doctests

Signed-off-by: nstarman <[email protected]>

* also test the docs

Signed-off-by: nstarman <[email protected]>

* try fixing basic_usage

Signed-off-by: nstarman <[email protected]>

* implement fixes

Signed-off-by: nstarman <[email protected]>

* push sctype test to future fix

Signed-off-by: nstarman <[email protected]>

* improve _split_parts

---------

Signed-off-by: nstarman <[email protected]>

Author: nstarman

conftest.py

@@ -0,0 +1,52 @@
+"""Doctest configuration."""
+
+from __future__ import annotations
+
+from doctest import ELLIPSIS, NORMALIZE_WHITESPACE
+
+import pytest
+from sybil import Sybil
+from sybil.parsers.myst import DocTestDirectiveParser as MarkdownDocTestParser
+from sybil.parsers.myst import PythonCodeBlockParser as MarkdownPythonCodeBlockParser
+from sybil.parsers.myst import SkipParser as MarkdownSkipParser
+from sybil.parsers.rest import DocTestParser as ReSTDocTestParser
+from sybil.parsers.rest import PythonCodeBlockParser as ReSTPythonCodeBlockParser
+from sybil.parsers.rest import SkipParser as ReSTSkipParser
+
+OPTIONS = ELLIPSIS | NORMALIZE_WHITESPACE
+
+
+@pytest.fixture(scope="module")
+def use_clean_dispatcher():
+    import plum
+
+    # Save the original dispatcher
+    dispatcher = plum.dispatch
+    # Swap the dispatcher with a temporary one
+    temp_dispatcher = plum.Dispatcher()
+    plum.dispatch = temp_dispatcher
+    yield
+    # Restore the original dispatcher
+    plum.dispatch = dispatcher
+
+
+markdown_examples = Sybil(
+    parsers=[
+        MarkdownDocTestParser(optionflags=OPTIONS),
+        MarkdownPythonCodeBlockParser(doctest_optionflags=OPTIONS),
+        MarkdownSkipParser(),
+    ],
+    patterns=["*.md"],
+    fixtures=["use_clean_dispatcher"],
+)
+
+rest_examples = Sybil(
+    parsers=[
+        ReSTDocTestParser(optionflags=OPTIONS),
+        ReSTPythonCodeBlockParser(),
+        ReSTSkipParser(),
+    ],
+    patterns=["*.py"],
+)
+
+pytest_collect_file = (markdown_examples + rest_examples).pytest()

docs/basic_usage.md

@@ -29,8 +29,9 @@ We haven't implemented a method for `float`s, so in that case an exception
 will be raised:
 
 ```python
->>> f(1.0)
-NotFoundLookupError: For function `f`, `(1.0,)` could not be resolved.
+>>> try: f(1.0)
+... except Exception as e: print(f"{type(e).__name__}: {e}")
+NotFoundLookupError: `f(1.0)` could not be resolved...
 ```
 
 Instead of implementing a method for `float`s, let's implement a method for
@@ -62,9 +63,13 @@ For a function `f`, all available methods can be obtained with `f.methods`:
 
 ```python
 >>> f.methods
-[Signature(str, implementation=<function f at 0x7f9f6014f160>),
- Signature(int, implementation=<function f at 0x7f9f6029c280>),
- Signature(numbers.Number, implementation=<function f at 0x7f9f801fdf70>)]
+List of 3 method(s):
+    [0] f(x: str)                                                               
+        <function f at ...> @ ...
+    [1] f(x: int)                                                               
+        <function f at ...> @ ...
+    [2] f(x: numbers.Number)                                                    
+        <function f at ...> @ ...
 ```
 
 For an excellent and way more detailed overview of multiple dispatch, see the

docs/classes.md

@@ -5,7 +5,6 @@ You can use dispatch within classes:
 ```python
 from plum import dispatch
 
-
 class Real:
    @dispatch
    def __add__(self, other: int):
@@ -54,7 +53,7 @@ class MyClass:
 
 >>> a.name = "1"  # OK
 
->>> a.name = 1    # Not OK
+>>> a.name = 1    # Not OK  # doctest:+SKIP
 NotFoundLookupError: For function `name` of `__main__.MyClass`, `(<__main__.MyClass object at 0x7f8cb8813eb0>, 1)` could not be resolved.
 ```
 
@@ -76,6 +75,8 @@ class Real:
 
 If we try to run this, we get the following error:
 
+% skip: next
+
 ```python
 NameError                                 Traceback (most recent call last)
 <ipython-input-1-2c6fe56c8a98> in <module>

docs/comparison.md

@@ -22,6 +22,8 @@ This is not necessarily the case for other packages.
 
 For example,
 
+% skip: start  "multipledispatch is not installed or tested"
+
 ```python
 from numbers import Number
 
@@ -62,6 +64,8 @@ Possible fix, define
   f(::Int64, ::Int64)
 ```
 
+% skip: end
+
 Plum handles this correctly.
 
 ```python
@@ -82,10 +86,14 @@ def f(x: int, y: Number):
 ```
 
 ```python
->>> f(1, 1)
-AmbiguousLookupError: For function `f`, `(1, 1)` is ambiguous among the following:
-  Signature(typing.Union[int, numbers.Number], int, implementation=<function f at 0x7fbbe8e3cdc0>) (precedence: 0)
-  Signature(int, numbers.Number, implementation=<function f at 0x7fbbc81813a0>) (precedence: 0)
+>>> try: f(1, 1)
+... except Exception as e: print(f"{type(e).__name__}: {e}")
+AmbiguousLookupError: `f(1, 1)` is ambiguous.
+Candidates:
+    f(x: typing.Union[int, numbers.Number], y: int)
+        <function f at ...> @ ...
+    f(x: int, y: numbers.Number)
+        <function f at ...> @ ...
 ```
 
 Just to sanity check that things are indeed working correctly:
@@ -104,6 +112,8 @@ Plum takes OOP very seriously.
 
 Consider the following snippet:
 
+% skip: start "other multiple-dispatchers are not installed or tested"
+
 ```python
 from multipledispatch import dispatch
 
@@ -156,6 +166,8 @@ class B(A):
 DispatchError: ('f: 0 methods found', (<class '__main__.B'>, <class 'str'>), [])
 ```
 
+% skip: end
+
 This behaviour is undesirable.
 Since `B.f` isn't matched, according to OOP principles, `A.f` should be tried next.
 Plum correctly implements this:

docs/conversion_promotion.md

@@ -6,6 +6,8 @@
 When a return type is not matched, Plum will attempt to convert the result to the 
 right type.
 
+% clear-namespace
+
 ```python
 from typing import Union
 
@@ -21,7 +23,8 @@ def f(x: Union[int, str]) -> int:
 >>> f(1)
 1
 
->>> f("1")
+>>> try: f("1")
+... except Exception as e: print(f"{type(e).__name__}: {e}")
 TypeError: Cannot convert `1` to `int`.
 ```
 
@@ -60,8 +63,9 @@ class Rational:
 >>> convert(0.5, Number)
 0.5
 
->>> convert(Rational(1, 2), Number)
-TypeError: Cannot convert `<__main__.Rational object at 0x7f88f8369310>` to `numbers.Number`.
+>>> try: convert(Rational(1, 2), Number)
+... except Exception as e: print(f"{type(e).__name__}: {e}")
+TypeError: Cannot convert `<Rational object at ...>` to `numbers.Number`.
 ```
 
 The `TypeError` indicates that `convert` does not know how to convert a
@@ -87,13 +91,16 @@ def rational_to_number(q):
 As above, instead of the decorator `conversion_method`, one can also use
 `add_conversion_method`:
 
+% skip: start
 
 ```python
 >>> from plum import add_conversion_method
 
 >>> add_conversion_method(type_from, type_to, conversion_function)
 ```
 
+% skip: end
+
 ## Promotion
 
 The function `promote` can be used to promote objects to a common type:
@@ -124,7 +131,8 @@ def add(x: float, y: float):
 >>> add(1.0, 2.0)
 3.0
 
->>> add(1, 2.0)
+>>> try: add(1, 2.0)
+... except Exception as e: print(f"{type(e).__name__}: {e}")
 TypeError: No promotion rule for `int` and `float`.
 ```
 
@@ -133,7 +141,8 @@ You can add promotion rules with `add_promotion_rule`:
 ```python
 >>> add_promotion_rule(int, float, float)
 
->>> add(1, 2.0)
+>>> try: add(1, 2.0)
+... except Exception as e: print(f"{type(e).__name__}: {e}")
 TypeError: Cannot convert `1` to `float`.
 
 >>> add_conversion_method(type_from=int, type_to=float, f=float)

docs/dispatch.md

@@ -38,8 +38,11 @@ Then
 
 ```python
 >>> f.methods  # No implementation for `Number`s!
-[Signature(float, float, implementation=<function f at 0x7f8c4015e9d0>),
- Signature(int, int, implementation=<function f at 0x7f8c4015ea60>)]
+List of 2 method(s):
+    [0] f(x: float, y: float)
+        <function f at ...> @ ...
+    [1] f(x: int, y: int)
+        <function f at ...> @ ...
 ```
 
 and calling `help(f)` produces
@@ -68,6 +71,8 @@ f(x: numbers.Number, y: numbers.Number)
 `Function.dispatch` can be used to extend a particular function from an external
 package:
 
+% skip: start "`package` is not a real package"
+
 ```python
 from package import f
 
@@ -85,6 +90,8 @@ def f(x: int):
 'new behaviour'
 ```
 
+% skip: end
+
 ## Directly Invoke a Method
 
 `Function.invoke` can be used to invoke a method given types of the arguments:
@@ -139,6 +146,12 @@ def add(x: Union[int, float], y: Union[int, float]):
 >>> add(1.0, 1.0)
 2.0
 
->>> add(1, 1.0)
-NotFoundLookupError: For function "add", signature Signature(builtins.int, builtins.float) could not be resolved.
+>>> try: add(1, 1.0)
+... except Exception as e: print(f"{type(e).__name__}: {e}")
+NotFoundLookupError: `add(1, 1.0)` could not be resolved.
+Closest candidates are the following:
+    add(x: int, y: int)
+        <function add at ...> @ ...
+    add(x: float, y: float)
+        <function add at ...> @ ...
 ```

docs/keyword_arguments.md

@@ -23,8 +23,9 @@ def f(x: int):
 >>> f(1)    # OK
 1
 
->>> f(x=1)  # Not OK
-NotFoundLookupError: For function `f`, `()` could not be resolved.
+>>> try: f(x=1)  # Not OK
+... except Exception as e: print(f"{type(e).__name__}: {e}")
+NotFoundLookupError: `f()` could not be resolved...
 ```
 
 See [below](why) for why this is the case.
@@ -75,19 +76,20 @@ from plum import dispatch
 
 
 @dispatch
-def f(x, *, option="a"):
+def g(x, *, option="a"):
     return option
 ```
 
 ```python
->>> f(1)
+>>> g(1)
 'a'
 
->>> f(1, option="b")
+>>> g(1, option="b")
 'b'
 
->>> f(1, "b")  # This will not work, because `option` must be given as a keyword.
-NotFoundLookupError: For function `f`, `(1, 'b')` could not be resolved.
+>>> try: g(1, "b")  # This will not work, because `option` must be given as a keyword.
+... except Exception as e: print(f"{type(e).__name__}: {e}")
+NotFoundLookupError: `g(1, 'b')` could not be resolved...
 ```
 
 (why)=
@@ -99,6 +101,8 @@ Is not entirely clear how
 this would work.
 For example, consider the following scenario:
 
+% skip: start "pseudocode"
+
 ```python
 @dispatch
 def f(x: int, y: float):
@@ -139,3 +143,5 @@ and once you position something, the name of the argument becomes irrelevant.
 
 Therefore, if we were to support naming arguments,
 how precisely this would work would have to be spelled out in detail.
+
+% skip: end