scipy-doctest 1.1__py3-none-any.whl

scipy_doctest/tests/stopwords_cases.py

@@ -0,0 +1,9 @@
+__all__ = ['func8']
+
+def func8():
+    """Handle MPL stopwords.
+    >>> import matplotlib.pyplot as plt
+    >>> plt.show()
+
+    >>> plt.xlim([1, 2])
+    """

scipy_doctest/tests/test_finder.py

@@ -0,0 +1,170 @@
+import pytest
+
+from . import finder_cases
+from ..util import get_all_list, get_public_objects
+from ..impl import DTFinder, DTConfig
+from ..frontend import find_doctests
+
+def test_get_all_list():
+    items, depr, other = get_all_list(finder_cases)
+    assert sorted(items) == ['Klass', 'func']
+
+
+def test_get_all_list_no_all():
+    # test get_all_list on a module which does not define all.
+    # Remove __all__, test, reload on exit to not depend on the test order.
+    try:
+        del finder_cases.__all__
+        items, depr, other = get_all_list(finder_cases)
+        assert items == []
+    finally:
+        from importlib import reload
+        reload(finder_cases)
+
+
+def test_get_objects():
+    (items, names), failures = get_public_objects(finder_cases)
+    assert items == [finder_cases.func, finder_cases.Klass]
+    assert names == [obj.__name__ for obj in items]
+    assert failures == []
+
+
+def test_get_objects_extra_items():
+    # test get_all_list on a module which defines an incorrect all.
+    # Patch __all__, test, reload on exit to not depend on the test order.
+    try:
+        finder_cases.__all__ += ['spurious']
+        (items, names), failures = get_public_objects(finder_cases)
+
+        assert items == [finder_cases.func, finder_cases.Klass]
+        assert len(failures) == 1
+
+        failed = failures[0]
+        assert failed[0].endswith(".spurious")
+        assert failed[2].startswith("Missing item")
+
+    finally:
+        from importlib import reload
+        reload(finder_cases)
+
+
+def test_find_doctests_extra_items():
+    # test find_doctests on a module which defines an incorrect all.
+    # Patch __all__, test, reload on exit to not depend on the test order.
+    try:
+        finder_cases.__all__ += ['spurious', 'missing']
+        with pytest.raises(ValueError):
+            find_doctests(finder_cases, strategy='api')
+    finally:
+        from importlib import reload
+        reload(finder_cases)
+
+
+class TestSkiplist:
+    """Test skipping items via skiplists."""
+    def test_get_objects_skiplist(self):
+        skips = [finder_cases.__name__ + '.' + 'func']
+        (items, name), failures = get_public_objects(finder_cases, skiplist=skips)
+
+        assert items == [finder_cases.Klass]
+        assert failures == []
+
+    def test_get_doctests_no_skiplist(self):
+        # strategy=None is equivalent to vanilla doctest module: finds all objects
+        tests = find_doctests(finder_cases)
+        names = [t.name for t in tests]
+
+        wanted_names = ['Klass', 'Klass.meth', 'Klass.meth_2', 'func',
+                        'private_func', '_underscored_private_func']
+        base = finder_cases.__name__
+        wanted_names = [base] + [base + '.' + n for n in wanted_names]
+
+        assert sorted(names) == sorted(wanted_names)
+
+    def test_get_doctests_strategy_None(self):
+        # Add a skiplist: strategy=None skips listed items 
+        base = finder_cases.__name__  
+        skips = [base + '.func', base + '.Klass.meth_2']
+        config = DTConfig(skiplist=skips)
+
+        tests = find_doctests(finder_cases, config=config)
+        names = [t.name for t in tests]
+
+        # note the lack of `func` and `Klass.meth_2`, as requested
+        wanted_names = ['Klass', 'Klass.meth',
+                        'private_func', '_underscored_private_func']
+        wanted_names = [base] + [base + '.' + n for n in wanted_names]
+
+        assert sorted(names) == sorted(wanted_names)
+
+    def test_get_doctests_strategy_api(self):
+        # Add a skiplist: strategy='api' skips listed items 
+        base = finder_cases.__name__  
+        skips = [base + '.func', base + '.Klass.meth_2']
+        config = DTConfig(skiplist=skips)
+
+        tests = find_doctests(finder_cases, strategy='api', config=config)
+        names = [t.name for t in tests]
+
+        # note the lack of
+        #   - `func` and `Klass.meth_2`, as requested (via the skiplist)
+        #   - *private* stuff, which is not in `__all__`
+        wanted_names = ['Klass', 'Klass.meth']
+        wanted_names = [base] + [base + '.' + n for n in wanted_names]
+
+        assert sorted(names) == sorted(wanted_names)
+
+    def test_get_doctests_strategy_list(self):
+        # Add a skiplist: strategy=<list> skips listed items 
+        base = finder_cases.__name__  
+        skips = [base + '.func', base + '.Klass.meth_2']
+        config = DTConfig(skiplist=skips)
+
+        tests = find_doctests(finder_cases,
+                              strategy=[finder_cases.Klass], config=config)
+        names = [t.name for t in tests]
+
+        # note the lack of
+        #   - `Klass.meth_2`, as requested (via the skiplist)
+        #   - the 'base' module (via the strategy=<list>)
+        wanted_names = ['Klass', 'Klass.meth']
+        wanted_names = [base + '.' + n for n in wanted_names]
+
+        assert sorted(names) == sorted(wanted_names)
+
+
+def test_explicit_object_list():
+    objs = [finder_cases.Klass]
+    tests = find_doctests(finder_cases, strategy=objs)
+
+    base = 'scipy_doctest.tests.finder_cases'
+    assert ([test.name for test in tests] ==
+            [base + '.Klass', base + '.Klass.meth', base + '.Klass.meth_2'])
+
+
+def test_explicit_object_list_with_module():
+    # Module docstrings are examined literally, without looking into other objects
+    # in the module. These other objects need to be listed explicitly.
+    # In the `doctest`-speak: do not recurse.
+    objs = [finder_cases, finder_cases.Klass]
+    tests = find_doctests(finder_cases, strategy=objs)
+
+    base = 'scipy_doctest.tests.finder_cases'
+    assert ([test.name for test in tests] ==
+            [base, base + '.Klass', base + '.Klass.meth', base + '.Klass.meth_2'])
+
+
+def test_find_doctests_api():
+    # Test that the module itself is included with strategy='api'
+    tests = find_doctests(finder_cases, strategy='api')
+
+    base = 'scipy_doctest.tests.finder_cases'
+    assert ([test.name for test in tests] ==
+            [base + '.func', base + '.Klass', base + '.Klass.meth',
+             base + '.Klass.meth_2', base])
+
+
+def test_dtfinder_config():
+    config = DTConfig()
+    finder = DTFinder(config=config)
+    assert finder.config is config

scipy_doctest/tests/test_parser.py

@@ -0,0 +1,36 @@
+from ..impl import DTConfig, DTParser
+
+
+def test_parser_default_config():
+    # Test that parser adds the _ignore marker for stopwords
+    parser = DTParser()
+
+    string = "Text text \n >>> 1 + plt.xlim([1, 2])\n\n More text"
+    examples = parser.get_examples(string)
+
+    assert len(examples) == 1
+    assert examples[0].source == "1 + plt.xlim([1, 2])\n"
+    assert examples[0].want == "  # _ignore\n"
+
+
+def test_parser_vanilla_config():
+    # Test that no stopwords means no markers
+    config = DTConfig()
+    config.stopwords = set()
+    parser = DTParser(config)
+
+    string = "Text text \n >>> 1 + plt.xlim([1, 2])\n\n More text"
+    examples = parser.get_examples(string)
+
+    assert len(examples) == 1
+    assert examples[0].source == "1 + plt.xlim([1, 2])\n"
+    assert examples[0].want == ""
+
+
+def test_config_nocopy():
+    config = DTConfig()
+    parser = DTParser(config)
+    assert parser.config is config
+
+
+

scipy_doctest/tests/test_pytest_configuration.py

@@ -0,0 +1,95 @@
+import pytest
+
+try:
+    import matplotlib.pyplot as plt    # noqa
+    HAVE_MATPLOTLIB = True
+except Exception:
+    HAVE_MATPLOTLIB = False
+
+try:
+    import scipy    # noqa
+    HAVE_SCIPY = True
+except Exception:
+    HAVE_SCIPY = False
+
+from pathlib import Path
+
+from . import module_cases, failure_cases, failure_cases_2, stopwords_cases, local_file_cases
+
+# XXX: this is a bit hacky and repetetive. Can rework?
+
+
+pytest_plugins = ['pytester']
+
+
+@pytest.mark.skipif(not HAVE_SCIPY, reason='need scipy')
+def test_module_cases(pytester):
+    """Test that pytest uses the DTChecker for doctests."""
+    path_str = module_cases.__file__
+    python_file = Path(path_str)
+    result = pytester.inline_run(python_file, "--doctest-modules")
+    assert result.ret == pytest.ExitCode.OK
+
+
+def test_failure_cases(pytester):
+    file_list = [failure_cases, failure_cases_2]
+    for file in file_list:
+        path_str = file.__file__
+        python_file = Path(path_str)
+        result = pytester.inline_run(python_file, "--doctest-modules")
+    assert result.ret == pytest.ExitCode.TESTS_FAILED
+
+    
+@pytest.mark.skipif(not HAVE_MATPLOTLIB, reason='need matplotlib')
+def test_stopword_cases(pytester):
+    """Test that pytest uses the DTParser for doctests."""
+    path_str = stopwords_cases.__file__
+    python_file = Path(path_str)
+    result = pytester.inline_run(python_file, "--doctest-modules")
+    assert result.ret == pytest.ExitCode.OK
+
+
+@pytest.mark.xfail(reason="XXX: passes locally, fails on CI")
+@pytest.mark.skipif(not HAVE_SCIPY, reason='need scipy')
+def test_local_file_cases(pytester):
+    """Test that local files are found for use in doctests.
+    """
+    path_str = local_file_cases.__file__
+    python_file = Path(path_str)
+    result = pytester.inline_run(python_file, "--doctest-modules")
+    assert result.ret == pytest.ExitCode.OK
+
+
+def test_alt_checker(pytester):
+    """Test an alternative Checker."""
+
+    # create a temporary conftest.py file
+    pytester.makeconftest(
+        """
+        import doctest
+        from scipy_doctest.conftest import dt_config
+
+        class Vanilla(doctest.OutputChecker):
+            def __init__(self, config):
+                pass
+
+        dt_config.CheckerKlass = Vanilla
+    """
+    )
+
+    # create a temporary pytest test file
+    f = pytester.makepyfile(
+        """
+        def func():
+            '''
+            >>> 2 / 3     # fails with vanilla doctest.OutputChecker
+            0.667
+            '''
+            pass
+    """
+    )
+
+    # run all tests with pytest
+    result = pytester.inline_run(f, '--doctest-modules')
+    assert result.ret == pytest.ExitCode.TESTS_FAILED
+

scipy_doctest/tests/test_runner.py

@@ -0,0 +1,105 @@
+import io
+
+import doctest
+
+import pytest
+
+from . import (failure_cases as module,
+               finder_cases as finder_module,
+               module_cases)
+from .. import DTFinder, DTRunner, DebugDTRunner, DTConfig
+
+
+### Smoke test DTRunner methods. Mainly to check that they are runnable.
+
+def test_single_failure():
+    finder = DTFinder()
+    tests = finder.find(module.func9)
+    runner = DTRunner(verbose=False)
+    stream = io.StringIO()
+    for test in tests:
+        runner.run(test, out=stream.write)
+
+    stream.seek(0)
+    output = stream.read()
+    assert output.startswith('\n func9\n -----\n')
+
+
+def test_exception():
+    finder = DTFinder()
+    tests = finder.find(module.func10)
+    runner = DTRunner(verbose=False)
+    stream = io.StringIO()
+    for test in tests:
+        runner.run(test, out=stream.write)
+
+    stream.seek(0)
+    output = stream.read()
+    assert output.startswith('\n func10\n ------\n')
+
+
+def test_get_history():
+    finder = DTFinder()
+    tests = finder.find(finder_module)
+    runner = DTRunner(verbose=False)
+    for test in tests:
+        runner.run(test)
+
+    dct = runner.get_history()
+    assert len(dct) == 7
+
+
+class TestDebugDTRunner:
+    def test_debug_runner_failure(self):
+        finder = DTFinder()
+        tests = finder.find(module.func9)
+        runner = DebugDTRunner(verbose=False)
+
+        with pytest.raises(doctest.DocTestFailure) as exc:
+            for t in tests:
+                runner.run(t)
+
+        # pytest wraps the original exception, unwrap it
+        orig_exception = exc.value
+
+        # DocTestFailure carries the doctest and the run result
+        assert orig_exception.test is tests[0]
+        assert orig_exception.test.name == 'func9'
+        assert orig_exception.got == 'array([1, 2, 3])\n'
+        assert orig_exception.example.want == 'array([2, 3, 4])\n'
+
+    def test_debug_runner_exception(self):
+        finder = DTFinder()
+        tests = finder.find(module.func10)
+        runner = DebugDTRunner(verbose=False)
+
+        with pytest.raises(doctest.UnexpectedException) as exc:
+            for t in tests:
+                runner.run(t)
+        orig_exception = exc.value
+
+        # exception carries the original test
+        assert orig_exception.test is tests[0]
+
+
+class VanillaOutputChecker(doctest.OutputChecker):
+    """doctest.OutputChecker to drop in for DTChecker.
+
+    LSP break: OutputChecker does not have __init__,
+    here we add it to agree with DTChecker.
+    """
+    def __init__(self, config):
+        pass
+
+class TestCheckerDropIn:
+    """Test DTChecker and vanilla doctest OutputChecker being drop-in replacements.
+    """
+    def test_vanilla_checker(self):
+        config = DTConfig(CheckerKlass=VanillaOutputChecker)
+        runner = DebugDTRunner(config=config)
+        tests = DTFinder().find(module_cases.func)
+
+        with pytest.raises(doctest.DocTestFailure):
+            for t in tests:
+                runner.run(t)
+

scipy_doctest/tests/test_skipmarkers.py

@@ -0,0 +1,202 @@
+import doctest
+
+try:
+    import matplotlib.pyplot as plt    # noqa
+    HAVE_MATPLOTLIB = True
+except Exception:
+    HAVE_MATPLOTLIB = False
+
+import pytest
+
+from ..impl import DTConfig, DTParser, DebugDTRunner
+
+
+class TestSyntaxErrors:
+    """Syntax errors trigger a doctest failure *unless* marked.
+
+    Either mark it with +SKIP or as pseudocode.
+    """
+    @pytest.mark.skipif(not HAVE_MATPLOTLIB, reason='need matplotlib')
+    def test_invalid_python(self):
+        # This string raises
+        # TypeError("unsupported operand type(s) for +: 'int' and 'tuple'")
+        string = ">>> import matplotlib.pyplot as plt; 1 + plt.xlim([1, 2])\n"
+
+        config = DTConfig()
+        parser = DTParser(config)
+
+        test = parser.get_doctest(string,
+                                   globs=config.default_namespace,
+                                   name='none: plain',
+                                   filename='none',
+                                   lineno=0)
+        runner = DebugDTRunner()
+
+        with pytest.raises(doctest.UnexpectedException) as exc_info:
+            runner.run(test)
+
+        orig_error = exc_info.value.exc_info  # unwrap pytest -> doctest -> example
+        kind, value, traceback = orig_error
+
+        assert kind is TypeError
+        assert "unsupported operand type(s)" in value.args[0]
+
+    def test_invalid_python_plus_skip(self):
+        # Adding a '# doctest: +SKIP' turns it into pseudocode:
+        # example NOT CHECKED, at all
+        string = ">>> import matplotlib.pyplot as plt; 1 + plt.xlim([1, 2])"
+        string += "  # doctest: +SKIP"
+
+        config = DTConfig()
+        parser = DTParser(config)
+
+        test = parser.get_doctest(string,
+                                   globs=config.default_namespace,
+                                   name='none : +SKIP',
+                                   filename='none',
+                                   lineno=0)
+        runner = DebugDTRunner()
+        runner.run(test)
+        assert runner.get_history() == {'none : +SKIP': (0, 0)}
+
+    def test_invalid_python_pseudocode(self):
+        # Marking a test as pseudocode is equivalent to a +SKIP:
+        # example NOT CHECKED, at all
+        string = ">>> import matplotlib.pyplot as plt; 1 + plt.xlim([1, 2])"
+
+        config = DTConfig(pseudocode=['plt.xlim'])
+        parser = DTParser(config)
+
+        test = parser.get_doctest(string,
+                                   globs=config.default_namespace,
+                                   name='none : pseudocode',
+                                   filename='none',
+                                   lineno=0)
+        runner = DebugDTRunner()
+        runner.run(test)
+        assert runner.get_history() == {'none : pseudocode': (0, 0)}
+
+
+class TestPseudocodeMarkers:
+    """Marking an example as pseudocode is exactly equivalent to a +SKIP."""
+
+    def test_pseudocode_markers(self):
+        # The first string has a +SKIP, the second one doesn't
+        string = ">>> oops #doctest: +SKIP\n>>> ouch\n"
+
+        parser = doctest.DocTestParser()
+        test = parser.get_doctest(string, globs={},
+                                  name='none', filename='none', lineno=0)
+
+        opts_when_skipped = {doctest.OPTIONFLAGS_BY_NAME['SKIP']: True}
+        assert len(test.examples) == 2
+        assert test.examples[0].options == opts_when_skipped
+        assert test.examples[1].options == {}
+
+        # Now mark the second example as pseudocode
+        config = DTConfig(pseudocode=['ouch'])
+        parser = DTParser(config=config)
+        test = parser.get_doctest(string, globs={},
+                                  name='none', filename='none', lineno=0)
+
+        assert len(test.examples) == 2
+        assert test.examples[0].options == opts_when_skipped
+        assert test.examples[1].options == opts_when_skipped
+
+
+class TestStopwords:
+    """If an example contains a stopword, the example still needs to be a valid
+    python code, but the output is not checked.
+    """
+    @pytest.mark.skipif(not HAVE_MATPLOTLIB, reason='need matplotlib')
+    def test_bogus_output(self):
+        # 'plt.xlim(' is a stopword by default in the DTParser. This is because
+        # it returns a tuple, which we don't want to litter our docstrings with.
+        string = ">>> import matplotlib.pyplot as plt; plt.xlim([1, 2])\n"
+        string += "bogus, not what plt.xlim(..) returns\n"
+
+        parser = DTParser()
+        test = parser.get_doctest(string, globs={},
+                                  name='stopwords_bogus_output',
+                                  filename='none', lineno=0)
+        assert "bogus" in test.examples[0].want
+
+        runner = DebugDTRunner()
+        runner.run(test)
+
+        # one example tried, of which zero failed
+        assert runner.get_history() == {'stopwords_bogus_output': (0, 1)}
+
+
+class TestMayVary:
+    """The '# may vary' markers are applied to the example output, not source.
+
+    Otherwise they are equivalent to declaring an example to have a stopword:
+    the source needs to be valid python code, but the output is not checked.
+    """
+    def test_may_vary(self):
+        string = ">>> 1 + 2\n"
+        string += "uhm, not sure  # may vary\n"
+
+        parser = DTParser()
+        test = parser.get_doctest(string, globs={},
+                                  name='may_vary_markers',
+                                  filename='none', lineno=0)
+        assert "uhm" in test.examples[0].want
+
+        runner = DebugDTRunner()
+        runner.run(test)
+
+        # one example tried, of which zero failed
+        assert runner.get_history() == {'may_vary_markers': (0, 1)}
+
+    def test_may_vary_source(self):
+        # The marker needs to be added to the example output, not source.
+        string = ">>> 1 + 2  # may vary\n"
+        string += "uhm, can't say\n"
+
+        parser = DTParser()
+        test = parser.get_doctest(string, globs={},
+                                  name='may_vary_source',
+                                  filename='none', lineno=0)
+
+        runner = DebugDTRunner()
+        with pytest.raises(doctest.DocTestFailure):
+            runner.run(test)
+
+
+string='''\
+
+This is an example string with doctests and skipblocks. A block is a sequence
+of examples (which start with a >>> marker) without an intervening text, like
+below
+
+>>> from some_module import some_function    # doctest: +SKIPBLOCK
+>>> some_function(42)
+
+Note how the block above will fail doctesting unless the second line is
+skipped. A standard solution is to add a +SKIP marker to every line, but this
+is ugly and we skip the whole block instead. 
+
+Once the block is over, we get back to usual doctests, which are not skipped
+
+>>> 1 + 2
+3
+
+'''
+
+def test_SKIPBLOCK():
+    parser = DTParser()
+    test = parser.get_doctest(string,
+                               globs={},
+                               name='SKIPBLOCK test',
+                               filename='none',
+                               lineno=0)
+
+    SKIP = doctest.OPTIONFLAGS_BY_NAME['SKIP']
+
+    assert len(test.examples) == 3
+    assert test.examples[0].options[SKIP] is True
+    assert test.examples[1].options[SKIP] is True
+    assert test.examples[2].options == {}    # not skipped
+

scipy_doctest/tests/test_testfile.py

@@ -0,0 +1,24 @@
+from ..frontend import testfile as doctestfile
+from ..impl import DTConfig
+
+import pytest
+
+
+@pytest.mark.xfail(True, reason="needs the scipy repo at a fixed location")
+def test_one_scipy_tutorial():
+    # FIXME: HACK, will not work if scipy is not installed,
+    path = '/home/br/repos/scipy/scipy/doc/source/tutorial/ndimage.rst'
+
+    config = DTConfig()
+    config.stopwords = {}
+
+    doctestfile(path,
+                module_relative=False, verbose=2, raise_on_error=False,
+                config=config)
+
+
+def test_linalg_clone():
+    # run on a clone of the scipy linalg tutorial
+    path = 'scipy_ndimage_tutorial_clone.rst'
+    doctestfile(path, package='scipy_doctest.tests', verbose=2,
+                raise_on_error=False)