scipy-doctest 1.1__py3-none-any.whl

scipy_doctest/plugin.py

@@ -0,0 +1,336 @@
+"""
+A pytest plugin that provides enhanced doctesting for Pydata libraries
+"""
+import bdb
+import warnings
+import doctest
+
+import pytest
+import _pytest
+from _pytest import doctest as pydoctest, outcomes
+from _pytest.doctest import DoctestModule, DoctestTextfile
+from _pytest.pathlib import import_path
+
+from .impl import DTParser, DebugDTRunner
+from .conftest import dt_config
+from .util import np_errstate, matplotlib_make_nongui, temp_cwd
+from .frontend import find_doctests
+
+
+def pytest_addoption(parser):
+    group = parser.getgroup("collect")
+
+    group.addoption(
+        "--doctest-collect",
+        action="store",
+        default="None",
+        help="Doctest collection strategy: vanilla pytest ('None', default), or 'api'",
+        choices=("None", "api"),
+        dest="collection_strategy"
+    )
+
+
+def pytest_configure(config):
+    """
+    Perform initial configuration for the pytest plugin.
+    """
+
+    # Create a dt config attribute within pytest's config object for easy access.
+    config.dt_config = dt_config
+
+    # Override doctest's objects with the plugin's alternative implementation.
+    pydoctest.DoctestModule = DTModule
+    pydoctest.DoctestTextfile = DTTextfile
+
+
+def pytest_ignore_collect(collection_path, config):
+    """
+    Determine whether to ignore the specified collection path.
+    This function is used to exclude the 'tests' directory and test modules when
+    the '--doctest-modules' option is used.
+    """
+    if config.getoption("--doctest-modules"):
+        path_str = str(collection_path)
+        if "tests" in path_str or "test_" in path_str:
+            return True
+
+    for entry in config.dt_config.pytest_extra_ignore:
+        if entry in str(collection_path):
+            return True
+
+
+def is_private(item):
+    """Decide if an DocTestItem `item` is private.
+
+    Private items are ignored in pytest_collect_modifyitem`.
+    """
+    # Here we look at the name of a test module/object. A seemingly less
+    # hacky alternative is to populate a set of seen `item.dtest` attributes
+    # (which are actual DocTest objects). The issue with that is it's tricky
+    # for explicit skips/ignores. Do we skip linalg.det or linalg._basic.det?
+    # (collection order is not guaranteed)
+    parent_full_name = item.parent.module.__name__
+    is_private = "._" in parent_full_name
+    return is_private
+
+
+def _maybe_add_markers(item, config):
+    """Add xfail/skip markers to `item` if DTConfig says so.
+
+    Modifies the item in-place.
+    """
+    dt_config = config.dt_config
+
+    extra_skip = dt_config.pytest_extra_skip
+    skip_it = item.name in extra_skip
+    if skip_it:
+        reason = extra_skip[item.name] or ''
+        item.add_marker(
+            pytest.mark.skip(reason=reason)
+        )
+
+    extra_xfail = dt_config.pytest_extra_xfail
+    fail_it = item.name in extra_xfail
+    if fail_it:
+        reason = extra_xfail[item.name] or ''
+        item.add_marker(
+            pytest.mark.xfail(reason=reason)
+        )
+
+
+def pytest_collection_modifyitems(config, items):
+    """
+    This hook is executed after test collection and allows you to modify the list of collected items.
+
+    The function removes
+        - duplicate Doctest items (e.g., scipy.stats.norm and scipy.stats.distributions.norm)
+        - Doctest items from underscored or otherwise private modules (e.g., scipy.special._precompute)
+
+    Note that this functions cooperates with and cleans up after `DTModule.collect`, which does the
+    bulk of the collection work.
+    """
+    # XXX: The logic in this function can probably be folded into DTModule.collect.
+    # I (E.B.) quickly tried it and it does not seem to just work. Apparently something
+    # pytest-y runs in between DTModule.collect and this hook (should that something
+    # be the proper home for all collection?).
+    # Also note that DTTextfile needs _maybe_add_markers, too.
+
+    need_filter_unique = (
+        config.getoption("--doctest-modules") and
+        config.getvalue("collection_strategy") == 'api'
+    )
+
+    unique_items = []
+
+    for item in items:
+        if isinstance(item.parent, DTModule) and need_filter_unique:
+            # objects are collected twice: from their public module + from the impl module
+            # e.g. for `levy_stable` we have
+            # (Pdb) p item.name, item.parent.name
+            # ('scipy.stats.levy_stable', 'build-install/lib/python3.10/site-packages/scipy/stats/__init__.py')
+            # and
+            # ('scipy.stats.distributions.levy_stable', 'distributions.py')
+            # so we filter out the second occurence
+            #
+            # There are two options:
+            #  - either the impl module has a leading underscore (scipy.linalg._basic), or
+            #  - it needs to be explicitly listed in the 'extra_ignore' config key (distributions.py)
+            #
+            # Note that the last part cannot be automated: scipy.cluster.vq is public, but
+            # scipy.stats.distributions is not
+            extra_ignore = config.dt_config.pytest_extra_ignore
+            parent_full_name = item.parent.module.__name__
+            is_duplicate = parent_full_name in extra_ignore or item.name in extra_ignore
+
+            if is_duplicate or is_private(item):
+                # ignore it
+                continue
+
+        _maybe_add_markers(item, config)
+        unique_items.append(item)
+
+    # Replace the original list of test items with the unique ones
+    items[:] = unique_items
+
+
+def _is_deprecated(module):
+    """Detect if a module is deprecated (i.e., raises or warns on getattr)."""
+    names = dir(module)
+    if not names:
+        return False
+
+    res = False
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter('error', DeprecationWarning)
+            getattr(module, names[0])
+            res = False
+    except DeprecationWarning:
+        res = True
+
+    return res
+
+
+class DTModule(DoctestModule):
+    """
+    This class extends the DoctestModule class provided by pytest.
+    
+    DTModule is responsible for overriding the behavior of the collect method.
+    The collect method is called by pytest to collect and generate test items for doctests
+    in the specified module or file.
+    """
+    def collect(self):
+        if pytest.__version__ < '8':
+            # Part of this code is copy-pasted from the `_pytest.doctest` module(pytest 7.4.0):
+            # https://github.com/pytest-dev/pytest/blob/448563caaac559b8a3195edc58e8806aca8d2c71/src/_pytest/doctest.py#L497
+            if self.path.name == "setup.py":
+                return
+            if self.path.name == "conftest.py":
+                module = self.config.pluginmanager._importconftest(
+                    self.path,
+                    self.config.getoption("importmode"),
+                    rootpath=self.config.rootpath
+                )
+            else:
+                try:
+                    module = import_path(
+                        self.path,
+                        root=self.config.rootpath,
+                        mode=self.config.getoption("importmode"),
+                    )
+                except ImportError:
+                    if self.config.getvalue("doctest_ignore_import_errors"):
+                        outcomes.skip("unable to import module %r" % self.path)
+                    else:
+                        raise
+
+            # XXX: `assert module == self.obj` seems to work (so is it all automatic?)
+            # but what are failure modes
+        else:
+            # https://github.com/pytest-dev/pytest/blob/8.1.0/src/_pytest/doctest.py#L561
+            try:
+                module = self.obj
+            except _pytest.nodes.Collector.CollectError:
+                if self.config.getvalue("doctest_ignore_import_errors"):
+                    outcomes.skip("unable to import module %r" % self.path)
+                else:
+                    raise
+
+        if _is_deprecated(module):
+            # bail out early
+            return
+
+        optionflags = dt_config.optionflags
+
+        # Plug in the custom runner: `PytestDTRunner` 
+        runner = _get_runner(self.config,
+            verbose=False,
+            optionflags=optionflags,
+        )
+
+        # strategy='api': discover doctests in public, non-deprecated objects in module
+        # strategy=None : use vanilla stdlib doctest discovery
+        strategy = self.config.getvalue("collection_strategy")
+        if strategy == 'None':
+            strategy = None
+
+        # NB: additional postprocessing in pytest_collection_modifyitems
+        for test in find_doctests(module, strategy=strategy, name=module.__name__, config=dt_config):
+            if test.examples: # skip empty doctests
+                yield pydoctest.DoctestItem.from_parent(
+                    self, name=test.name, runner=runner, dtest=test
+                )
+
+
+class DTTextfile(DoctestTextfile):
+    """
+    This class extends the DoctestTextfile class provided by pytest.
+    
+    DTTextfile is responsible for overriding the behavior of the collect method.
+    The collect method is called by pytest to collect and generate test items for doctests
+    in the specified text files.
+    """
+    def collect(self):
+        # Part of this code is copy-pasted from `_pytest.doctest` module(pytest 7.4.0):
+        # https://github.com/pytest-dev/pytest/blob/448563caaac559b8a3195edc58e8806aca8d2c71/src/_pytest/doctest.py#L417
+        encoding = self.config.getini("doctest_encoding")
+        text = self.path.read_text(encoding)
+        filename = str(self.path)
+        name = self.path.name
+        globs = {"__name__": "__main__"}
+
+        optionflags = dt_config.optionflags
+
+        # Plug in the custom runner: `PytestDTRunner`
+        runner = _get_runner(self.config,
+            verbose=False,
+            optionflags=optionflags,
+        )
+
+        # Plug in an instance of `DTParser` which parses the doctest examples from the text file and
+        # filters out stopwords and pseudocode.
+        parser = DTParser(config=self.config.dt_config)
+
+        # This part of the code is unchanged
+        test = parser.get_doctest(text, globs, name, filename, 0)
+        if test.examples:
+            yield pydoctest.DoctestItem.from_parent(
+                self, name=test.name, runner=runner, dtest=test
+            )
+
+
+def _get_runner(config, verbose, optionflags):
+    """
+    Override function to return an instance of PytestDTRunner.
+    
+    This function creates and returns an instance of PytestDTRunner, a custom runner class
+    that extends the behavior of DebugDTRunner for running doctests in pytest.
+    """
+    class PytestDTRunner(DebugDTRunner):
+        def run(self, test, compileflags=None, out=None, clear_globs=False):
+            """
+            Run tests in context managers.
+            
+            Restore the errstate/print state after each docstring.
+            Also, make MPL backend non-GUI and close the figures.
+            
+            The order of context managers is actually relevant. Consider
+            user_context_mgr that turns warnings into errors.
+            
+            Additionally, suppose that MPL deprecates something and plt.something
+            starts issuing warnings. Now all of those become errors
+            *unless* the `mpl()` context mgr has a chance to filter them out
+            *before* they become errors in `config.user_context_mgr()`.
+            """
+            dt_config = config.dt_config
+
+            with np_errstate():
+                with dt_config.user_context_mgr(test):
+                    with matplotlib_make_nongui():
+                        # XXX: local_resourses needed? they seem to be, w/o pytest
+                        with temp_cwd(test, dt_config.local_resources):
+                            super().run(test, compileflags=compileflags, out=out, clear_globs=clear_globs)
+
+        """
+        Almost verbatim copy of `_pytest.doctest.PytestDoctestRunner` except we utilize
+        DTConfig's `nameerror_after_exception` attribute in place of doctest's `continue_on_failure`.
+        """
+        def report_failure(self, out, test, example, got):
+            failure = doctest.DocTestFailure(test, example, got)
+            if config.dt_config.nameerror_after_exception:
+                out.append(failure)
+            else:
+                raise failure
+
+        def report_unexpected_exception(self, out, test, example, exc_info):
+            if isinstance(exc_info[1], outcomes.OutcomeException):
+                raise exc_info[1]
+            if isinstance(exc_info[1], bdb.BdbQuit):
+                outcomes.exit("Quitting debugger")
+            failure = doctest.UnexpectedException(test, example, exc_info)
+            if config.dt_config.nameerror_after_exception:
+                out.append(failure)
+            else:
+                raise failure
+
+    return PytestDTRunner(verbose=verbose, optionflags=optionflags, config=config.dt_config)

scipy_doctest/tests/failure_cases.py

@@ -0,0 +1,17 @@
+__all__ = ['func9', 'func10']
+
+def func9():
+    """
+    Wrong output.
+    >>> import numpy as np
+    >>> np.array([1, 2, 3])
+    array([2, 3, 4])
+    """
+
+
+def func10():
+    """
+    NameError
+    >>> import numpy as np
+    >>> np.arraY([1, 2, 3])
+    """

scipy_doctest/tests/failure_cases_2.py

@@ -0,0 +1,27 @@
+__all__ = ['func_depr', 'func_name_error']
+
+def func_depr():
+    """
+    A test case for the user context mgr to turn warnings to errors.
+
+    >>> import warnings; warnings.warn('Sample deprecation warning', DeprecationWarning)
+    """
+
+
+def func_name_error():
+    """After an example fails, next examples may emit NameErrors. Suppress them.
+
+    Note that the suppresion is in effect for the duration of the DocTest, i.e.
+    for the whole docstring. Maybe this can be fixed at some point.
+
+    >>> def func():
+    ...     raise ValueError("oops")
+    ...     return 42
+    >>> res = func()
+    >>> res
+    >>> raise NameError('This is legitimate, but is suppressed')
+
+    Further name errors are also suppressed (which is a bug, too):
+    >>> raise NameError('Also legit')
+    """
+

scipy_doctest/tests/finder_cases.py

@@ -0,0 +1,65 @@
+"""
+A set of simple cases for DocTestFinder / DTFinder and its helpers.
+
+
+
+1. There is a doctest in the module docstring
+
+>>> 1 + 2
+3
+"""
+
+__all__ = ['func', 'Klass']
+
+
+def func():
+    """Two doctests in a module-level function.
+
+    >>> 1 + 3
+    4
+
+    >>> 5 + 6
+    11
+    """
+    pass
+
+
+class Klass:
+    """A class has doctests in a class docstring.
+
+    >>> 1 + 8
+    9
+    """
+    def meth(self):
+        """And a method has its doctests.
+
+        >>> 2 + 11
+        13
+        """
+        pass
+
+    def meth_2(self):
+        """
+        One other method.
+
+        >>> 111 + 1
+        112
+        """
+
+
+def private_func():
+    """A non-public function (not listed in __all__) also has examples.
+
+    >>> 9 + 11
+    20
+    """
+
+
+def _underscored_private_func():
+    """A private function (starts with an undescore) also has examples.
+
+    >>> 9 + 12
+    21
+    """
+
+

scipy_doctest/tests/local_file_cases.py

@@ -0,0 +1,37 @@
+from ..conftest import dt_config
+
+# Specify local files required by doctests
+dt_config.local_resources = {
+    'scipy_doctest.tests.local_file_cases.local_files': ['local_file.txt'],
+    'scipy_doctest.local_file_cases.sio': ['octave_a.mat']
+}
+
+
+__all__ = ['local_files', 'sio']
+
+
+def local_files():
+    """
+    A doctest that tries to read a local file
+
+    >>> with open('local_file.txt', 'r'):
+    ...     pass
+    """
+
+
+def sio():
+    """
+    The .mat file is from scipy/tutorial/io.rst; The test checks that a want/got
+    being a dict is handled correctly.
+
+    >>> import scipy.io as sio
+    >>> sio.loadmat('octave_a.mat')
+    {'__header__': b'MATLAB 5.0 MAT-file, written by Octave 3.2.3, 2010-05-30 02:13:40 UTC',
+     '__version__': '1.0',
+     '__globals__': [],
+     'a': array([[[ 1.,  4.,  7., 10.],
+                  [ 2.,  5.,  8., 11.],
+                  [ 3.,  6.,  9., 12.]]])}
+    """
+
+

scipy_doctest/tests/module_cases.py

@@ -0,0 +1,192 @@
+__all__ = [
+    'func', 'func2', 'func3', 'func4', 'func5', 'func6', 'func8',
+    'func7', 'manip_printoptions', 'array_abbreviation'
+]
+
+import numpy as np
+import pytest
+
+def func():
+    """
+    >>> 2 / 3
+    0.667
+    """
+    pass
+
+
+def func2():
+    """
+    Check that `np.` is imported and the array repr is recognized. Also check
+    that whitespace is irrelevant for the checker.
+    >>> import numpy as np
+    >>> np.array([1,         2,          3.0])
+    array([1, 2, 3])
+
+    Check that the comparison is with atol and rtol: give less digits than
+    what numpy by default prints
+    >>> np.sin([1., 2, 3])
+    array([0.8414, 0.9092, 0.1411])
+
+    Also check that numpy repr for e.g. dtypes is recognized
+    >>> np.array([1, 2, 3], dtype=np.float32)
+    array([1., 2., 3.], dtype=float32)
+
+    """
+
+
+def func3():
+    """
+    Check that printed arrays are checked with atol/rtol
+    >>> import numpy as np
+    >>> a = np.array([1, 2, 3, 4]) / 3
+    >>> print(a)
+    [0.33  0.66  1  1.33]
+    """
+
+
+def func4():
+    """
+    Test `# may vary` markers : these should not break doctests (but the code
+    should still be valid, otherwise it's an error).
+    >>> import numpy as np
+    >>> np.random.randint(50)
+    42      # may vary
+
+    >>> np.random.randint(50)
+    42      # Random
+
+    >>> np.random.randint(50)
+    42      # random
+    """
+
+
+def func5():
+    """
+    Object addresses are ignored:
+    >>> import numpy as np
+    >>> np.array([1, 2, 3]).data
+    <memory at 0x7f119b952400>
+    """
+
+
+def func6():
+    """
+    Masked arrays
+
+    >>> import numpy.ma as ma
+    >>> y = ma.array([1, 2, 3], mask = [0, 1, 0])
+    >>> y
+    masked_array(data=[1, --, 3],
+                 mask=[False,  True, False],
+           fill_value=999999)
+
+    """
+
+
+def func8():
+    """
+    Namedtuples (they are *not* in the namespace)
+
+    >>> from scipy.stats import levene
+    >>> a = [8.88, 9.12, 9.04, 8.98, 9.00, 9.08, 9.01, 8.85, 9.06, 8.99]
+    >>> b = [8.88, 8.95, 9.29, 9.44, 9.15, 9.58, 8.36, 9.18, 8.67, 9.05]
+    >>> c = [8.95, 9.12, 8.95, 8.85, 9.03, 8.84, 9.07, 8.98, 8.86, 8.98]
+
+    # namedtuples are recognized...
+    >>> levene(a, b, c)
+    LeveneResult(statistic=7.58495, pvalue=0.00243)
+
+    # can be reformatted
+    >>> levene(a, b, c)
+    LeveneResult(statistic=7.58495,
+                 pvalue=0.00243)
+
+    # ... or can be given just as tuples
+    >>> levene(a, b, c)
+    (7.58495, 0.00243)
+
+    """
+
+
+def func7():
+    """
+    Multiline namedtuples + nested tuples, see scipy/gh-16082
+
+    >>> from scipy import stats
+    >>> import numpy as np
+    >>> a = np.arange(10)
+    >>> stats.describe(a)
+    DescribeResult(nobs=10, minmax=(0, 9), mean=4.5,
+                   variance=9.16666666666, skewness=0.0,
+                   kurtosis=-1.224242424)
+
+    A single-line form of a namedtuple
+    >>> stats.describe(a)
+    DescribeResult(nobs=10, minmax=(0, 9),      mean=4.5,       variance=9.16666, skewness=0.0, kurtosis=-1.2242424)
+
+    """
+
+
+def manip_printoptions():
+    """Manipulate np.printoptions.
+    >>> import numpy as np
+    >>> np.set_printoptions(linewidth=146)
+    """
+
+
+def array_abbreviation():
+    """
+    Numpy abbreviates arrays, check that it works.
+
+    NB: the implementation might need to change when
+    numpy finally disallows default-creating ragged arrays.
+    Currently, `...` gets interpreted as an Ellipsis,
+    thus the `a_want/a_got` variables in DTChecker are in fact
+    object arrays.
+    >>> import numpy as np
+    >>> np.arange(10000)
+    array([0, 1, 2, ..., 9997, 9998, 9999])
+
+    >>> np.diag(np.arange(33)) / 30
+    array([[0., 0., 0., ..., 0., 0.,0.],
+           [0., 0.03333333, 0., ..., 0., 0., 0.],
+           [0., 0., 0.06666667, ..., 0., 0., 0.],
+           ...,
+           [0., 0., 0., ..., 1., 0., 0.],
+           [0., 0., 0., ..., 0., 1.03333333, 0.],
+           [0., 0., 0., ..., 0., 0., 1.06666667]])
+
+
+    >>> np.diag(np.arange(1, 1001, dtype=float))
+    array([[1,    0,    0, ...,    0,    0,    0],
+           [0,    2,    0, ...,    0,    0,    0],
+           [0,    0,    3, ...,    0,    0,    0],
+            ...,
+           [0,    0,    0, ...,  998,    0,    0],
+           [0,    0,    0, ...,    0,  999,    0],
+           [0,    0,    0, ...,    0,    0, 1000]])
+    """
+
+def nan_equal():
+    """
+    Test that nans are treated as equal.
+
+    >>> import numpy as np
+    >>> np.nan
+    np.float64(nan)
+    """
+
+
+def test_cmplx_nan():
+    """
+    Complex nans
+    >>> import numpy as np
+    >>> np.nan - 1j*np.nan
+    nan + nanj
+
+    >>> np.nan + 1j*np.nan
+    np.complex128(nan+nanj)
+
+    >>> 1j*np.complex128(np.nan)
+    np.complex128(nan+nanj)
+    """