scipy-doctest 1.1__tar.gz → 1.2.0__tar.gz

{scipy_doctest-1.1 → scipy_doctest-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: scipy_doctest
-Version: 1.1
+Version: 1.2.0
 Summary: Doctests on steroids.
 Maintainer-email: SciPy developers <scipy-dev@python.org>
 Requires-Python: >=3.8
@@ -19,6 +19,15 @@ Provides-Extra: test
 
 # Floating-point aware, human readable, numpy-compatible doctesting.
 
+## TL;DR
+
+This project extends the standard library `doctest` module to allow flexibility
+and easy customization of finding, parsing and checking code examples in
+documentation. 
+
+Can be used either as drop-in `doctest` replacement or through the `pytest`
+integration. Uses a floating-point aware doctest checker by default.
+
 ## Motivation and scope
 
 Having examples in the documentation is great. Having wrong examples in the
@@ -92,7 +101,7 @@ the output. Thus the example source needs to be valid python code still.
 
 ```
 $ pip install -e .
-$ pytest --pyargs scpdt
+$ pytest --pyargs scipy_doctest
 ```
 
 ## Usage
@@ -110,7 +119,7 @@ For example,
 
 ```
 >>> from scipy import linalg
->>> from scpdt import testmod
+>>> from scipy_doctest import testmod
 >>> res, hist = testmod(linalg, strategy='api')
 >>> res
 TestResults(failed=0, attempted=764)
@@ -126,7 +135,7 @@ the behavior of the eponymous functions of the `doctest` module).
 
 There is a basic CLI, which also mimics that of the `doctest` module:
 ```
-$ python -m scpdt foo.py
+$ python -m scipy_doctest foo.py
 ```
 
 Note that, just like `$ python -m doctest foo.py`, this may
@@ -134,7 +143,7 @@ fail if `foo.py` is a part of a package due to package imports.
 
 Text files can also be CLI-checked:
 ```
-$ python -m scpdt bar.rst
+$ python -m scipy_doctest bar.rst
 ```
 
 
@@ -158,25 +167,24 @@ passing the instance to `testmod` or constructors of `DT*` objects. Defaults
 are provided, based on a long-term usage in SciPy.
 
 
-### The Scpdt Pytest Plugin
+### The SciPy Doctest Pytest Plugin
 
-The pytest plugin enables the use of scpdt tools to perform doctests. 
+The pytest plugin enables the use of `scipy_doctest` tools to perform doctests.
 
 Follow the given instructions to utilize the pytest plugin for doctesting.
 
-### Running doctests on Scipy
-1. **Install plugin**
+### Running Doctests on SciPy
 
-Start by installing the pytest plugin via pip:
+1. **Install plugin**
 
 ```bash
-pip install git+https://github.com/ev-br/scpdt.git@main
+pip install scipy-doctest
 ```
 
 2. **Configure Your Doctesting Experience**
 
 To tailor your doctesting experience, you can utilize an instance of `DTConfig`.
-An in-depth explanation is given in the [tailoring your doctesting experience](https://github.com/ev-br/scpdt#tailoring-your-doctesting-experience) section.
+An in-depth explanation is given in the [tailoring your doctesting experience](https://github.com/scipy/scipy_doctest#tailoring-your-doctesting-experience) section.
 
 3. **Run Doctests**
 
@@ -184,13 +192,13 @@ Doctesting is configured to execute on SciPy using the `dev.py` module.
 
 To run all doctests, use the following command:
 ```bash
-python dev.py test --doctests
+python dev.py smoke-docs
 ```
 
 To run doctests on specific SciPy modules, e.g: `cluster`, use the following command:
 
 ```bash
-python dev.py test --doctests -s cluster
+python dev.py smoke-docs -s cluster
 ```
 
 ### Running Doctests on Other Packages/Projects
@@ -200,7 +208,7 @@ If you want to run doctests on packages or projects other than SciPy, follow the
 1. **Install the plugin**
 
 ```bash
-pip install git+https://github.com/ev-br/scpdt.git@main
+pip install scipy-doctest
 ```
 
 2. **Register or Load the Plugin**
@@ -212,14 +220,14 @@ To do this, add the following line of code:
 ```python
 # In your conftest.py file or test module
 
-pytest_plugins = "scpdt"
+pytest_plugins = "scipy_doctest"
 ```
 
 Check out the [pytest documentation](https://docs.pytest.org/en/stable/how-to/writing_plugins.html#requiring-loading-plugins-in-a-test-module-or-conftest-file) for more information on requiring/loading plugins in a test module or `conftest.py` file.
 
 3. **Configure your doctesting experience**
 
-An in-depth explanation is given in the [tailoring your doctesting experience](https://github.com/ev-br/scpdt#tailoring-your-doctesting-experience) section.
+An in-depth explanation is given in the [tailoring your doctesting experience](https://github.com/scipy/scipy_doctest#tailoring-your-doctesting-experience) section.
 
 4. **Run doctests** 
 
@@ -242,7 +250,7 @@ $ pytest --pyargs <your-package> --doctest-modules --doctest-collect=api
 
 ### Tailoring Your Doctesting Experience
 
-[DTConfig](https://github.com/ev-br/scpdt/blob/671083d65b54111770cee71c9bc790ac652d59ab/scpdt/impl.py#L16) offers a variety of attributes that allow you to fine-tune your doctesting experience. 
+[DTConfig](https://github.com/scipy/scipy_doctest/blob/main/scipy_doctest/impl.py#L23) offers a variety of attributes that allow you to fine-tune your doctesting experience.
 
 These attributes include:
 1. **default_namespace (dict):** Defines the namespace in which examples are executed.
@@ -262,7 +270,7 @@ Typically, it is entered for each DocTest (especially in API documentation), ens
 12. **nameerror_after_exception (bool):** Controls whether subsequent examples in the same test, after one has failed, may raise spurious NameErrors. Set to `True` if you want to observe these errors or if your test is expected to raise NameErrors. The default is `False`.
 
 To set any of these attributes, create an instance of `DTConfig` called `dt_config`. 
-This instance is already set as an [attribute of pytest's `Config` object](https://github.com/ev-br/scpdt/blob/671083d65b54111770cee71c9bc790ac652d59ab/scpdt/plugin.py#L27).
+This instance is already set as an [attribute of pytest's `Config` object](https://github.com/scipy/scipy_doctest/blob/58ff06a837b7bff1dbac6560013fc6fd07952ae2/scipy_doctest/plugin.py#L39).
 
 **Example:**
 
@@ -270,8 +278,8 @@ This instance is already set as an [attribute of pytest's `Config` object](https
 dt_config = DTConfig()
 dt_config.stopwords = {'plt.', '.hist', '.show'}
 dt_config.local_resources = {
-    'scpdt.tests.local_file_cases.local_files': ['scpdt/tests/local_file.txt'],
-    'scpdt.tests.local_file_cases.sio': ['scpdt/tests/octave_a.mat']
+    'scipy_doctest.tests.local_file_cases.local_files': ['scipy_doctest/tests/local_file.txt'],
+    'scipy_doctest.tests.local_file_cases.sio': ['scipy_doctest/tests/octave_a.mat']
 }
 dt_config.skiplist = {
     'scipy.special.sinc',
@@ -280,9 +288,9 @@ dt_config.skiplist = {
 }
 ```
 
-If you don't set these attributes, the [default settings](https://github.com/ev-br/scpdt/blob/671083d65b54111770cee71c9bc790ac652d59ab/scpdt/impl.py#L73) of the attributes are used.
+If you don't set these attributes, the [default settings](https://github.com/scipy/scipy_doctest/blob/58ff06a837b7bff1dbac6560013fc6fd07952ae2/scipy_doctest/impl.py#L94) of the attributes are used.
 
-By following these steps, you will be able to effectively use the Scpdt pytest plugin for doctests in your Python projects.
+By following these steps, you will be able to effectively use the SciPy Doctest pytest plugin for doctests in your Python projects.
 
 Happy testing!
 
@@ -309,7 +317,7 @@ instead of `$ pytest --pyargs scipy`.
 If push comes to shove, you may try using the magic env variable:
 ` PY_IGNORE_IMPORTMISMATCH=1 pytest ...`,
 however the need usually indicates an issue with the package itself.
-(see [gh-107](https://github.com/ev-br/scpdt/pull/107) for an example).
+(see [gh-107](https://github.com/scipy/scipy_doctest/pull/107) for an example).
 
 - *Optional dependencies are not that optional*
 

{scipy_doctest-1.1 → scipy_doctest-1.2.0}/README.md

@@ -1,5 +1,14 @@
 # Floating-point aware, human readable, numpy-compatible doctesting.
 
+## TL;DR
+
+This project extends the standard library `doctest` module to allow flexibility
+and easy customization of finding, parsing and checking code examples in
+documentation. 
+
+Can be used either as drop-in `doctest` replacement or through the `pytest`
+integration. Uses a floating-point aware doctest checker by default.
+
 ## Motivation and scope
 
 Having examples in the documentation is great. Having wrong examples in the
@@ -73,7 +82,7 @@ the output. Thus the example source needs to be valid python code still.
 
 ```
 $ pip install -e .
-$ pytest --pyargs scpdt
+$ pytest --pyargs scipy_doctest
 ```
 
 ## Usage
@@ -91,7 +100,7 @@ For example,
 
 ```
 >>> from scipy import linalg
->>> from scpdt import testmod
+>>> from scipy_doctest import testmod
 >>> res, hist = testmod(linalg, strategy='api')
 >>> res
 TestResults(failed=0, attempted=764)
@@ -107,7 +116,7 @@ the behavior of the eponymous functions of the `doctest` module).
 
 There is a basic CLI, which also mimics that of the `doctest` module:
 ```
-$ python -m scpdt foo.py
+$ python -m scipy_doctest foo.py
 ```
 
 Note that, just like `$ python -m doctest foo.py`, this may
@@ -115,7 +124,7 @@ fail if `foo.py` is a part of a package due to package imports.
 
 Text files can also be CLI-checked:
 ```
-$ python -m scpdt bar.rst
+$ python -m scipy_doctest bar.rst
 ```
 
 
@@ -139,25 +148,24 @@ passing the instance to `testmod` or constructors of `DT*` objects. Defaults
 are provided, based on a long-term usage in SciPy.
 
 
-### The Scpdt Pytest Plugin
+### The SciPy Doctest Pytest Plugin
 
-The pytest plugin enables the use of scpdt tools to perform doctests. 
+The pytest plugin enables the use of `scipy_doctest` tools to perform doctests.
 
 Follow the given instructions to utilize the pytest plugin for doctesting.
 
-### Running doctests on Scipy
-1. **Install plugin**
+### Running Doctests on SciPy
 
-Start by installing the pytest plugin via pip:
+1. **Install plugin**
 
 ```bash
-pip install git+https://github.com/ev-br/scpdt.git@main
+pip install scipy-doctest
 ```
 
 2. **Configure Your Doctesting Experience**
 
 To tailor your doctesting experience, you can utilize an instance of `DTConfig`.
-An in-depth explanation is given in the [tailoring your doctesting experience](https://github.com/ev-br/scpdt#tailoring-your-doctesting-experience) section.
+An in-depth explanation is given in the [tailoring your doctesting experience](https://github.com/scipy/scipy_doctest#tailoring-your-doctesting-experience) section.
 
 3. **Run Doctests**
 
@@ -165,13 +173,13 @@ Doctesting is configured to execute on SciPy using the `dev.py` module.
 
 To run all doctests, use the following command:
 ```bash
-python dev.py test --doctests
+python dev.py smoke-docs
 ```
 
 To run doctests on specific SciPy modules, e.g: `cluster`, use the following command:
 
 ```bash
-python dev.py test --doctests -s cluster
+python dev.py smoke-docs -s cluster
 ```
 
 ### Running Doctests on Other Packages/Projects
@@ -181,7 +189,7 @@ If you want to run doctests on packages or projects other than SciPy, follow the
 1. **Install the plugin**
 
 ```bash
-pip install git+https://github.com/ev-br/scpdt.git@main
+pip install scipy-doctest
 ```
 
 2. **Register or Load the Plugin**
@@ -193,14 +201,14 @@ To do this, add the following line of code:
 ```python
 # In your conftest.py file or test module
 
-pytest_plugins = "scpdt"
+pytest_plugins = "scipy_doctest"
 ```
 
 Check out the [pytest documentation](https://docs.pytest.org/en/stable/how-to/writing_plugins.html#requiring-loading-plugins-in-a-test-module-or-conftest-file) for more information on requiring/loading plugins in a test module or `conftest.py` file.
 
 3. **Configure your doctesting experience**
 
-An in-depth explanation is given in the [tailoring your doctesting experience](https://github.com/ev-br/scpdt#tailoring-your-doctesting-experience) section.
+An in-depth explanation is given in the [tailoring your doctesting experience](https://github.com/scipy/scipy_doctest#tailoring-your-doctesting-experience) section.
 
 4. **Run doctests** 
 
@@ -223,7 +231,7 @@ $ pytest --pyargs <your-package> --doctest-modules --doctest-collect=api
 
 ### Tailoring Your Doctesting Experience
 
-[DTConfig](https://github.com/ev-br/scpdt/blob/671083d65b54111770cee71c9bc790ac652d59ab/scpdt/impl.py#L16) offers a variety of attributes that allow you to fine-tune your doctesting experience. 
+[DTConfig](https://github.com/scipy/scipy_doctest/blob/main/scipy_doctest/impl.py#L23) offers a variety of attributes that allow you to fine-tune your doctesting experience.
 
 These attributes include:
 1. **default_namespace (dict):** Defines the namespace in which examples are executed.
@@ -243,7 +251,7 @@ Typically, it is entered for each DocTest (especially in API documentation), ens
 12. **nameerror_after_exception (bool):** Controls whether subsequent examples in the same test, after one has failed, may raise spurious NameErrors. Set to `True` if you want to observe these errors or if your test is expected to raise NameErrors. The default is `False`.
 
 To set any of these attributes, create an instance of `DTConfig` called `dt_config`. 
-This instance is already set as an [attribute of pytest's `Config` object](https://github.com/ev-br/scpdt/blob/671083d65b54111770cee71c9bc790ac652d59ab/scpdt/plugin.py#L27).
+This instance is already set as an [attribute of pytest's `Config` object](https://github.com/scipy/scipy_doctest/blob/58ff06a837b7bff1dbac6560013fc6fd07952ae2/scipy_doctest/plugin.py#L39).
 
 **Example:**
 
@@ -251,8 +259,8 @@ This instance is already set as an [attribute of pytest's `Config` object](https
 dt_config = DTConfig()
 dt_config.stopwords = {'plt.', '.hist', '.show'}
 dt_config.local_resources = {
-    'scpdt.tests.local_file_cases.local_files': ['scpdt/tests/local_file.txt'],
-    'scpdt.tests.local_file_cases.sio': ['scpdt/tests/octave_a.mat']
+    'scipy_doctest.tests.local_file_cases.local_files': ['scipy_doctest/tests/local_file.txt'],
+    'scipy_doctest.tests.local_file_cases.sio': ['scipy_doctest/tests/octave_a.mat']
 }
 dt_config.skiplist = {
     'scipy.special.sinc',
@@ -261,9 +269,9 @@ dt_config.skiplist = {
 }
 ```
 
-If you don't set these attributes, the [default settings](https://github.com/ev-br/scpdt/blob/671083d65b54111770cee71c9bc790ac652d59ab/scpdt/impl.py#L73) of the attributes are used.
+If you don't set these attributes, the [default settings](https://github.com/scipy/scipy_doctest/blob/58ff06a837b7bff1dbac6560013fc6fd07952ae2/scipy_doctest/impl.py#L94) of the attributes are used.
 
-By following these steps, you will be able to effectively use the Scpdt pytest plugin for doctests in your Python projects.
+By following these steps, you will be able to effectively use the SciPy Doctest pytest plugin for doctests in your Python projects.
 
 Happy testing!
 
@@ -290,7 +298,7 @@ instead of `$ pytest --pyargs scipy`.
 If push comes to shove, you may try using the magic env variable:
 ` PY_IGNORE_IMPORTMISMATCH=1 pytest ...`,
 however the need usually indicates an issue with the package itself.
-(see [gh-107](https://github.com/ev-br/scpdt/pull/107) for an example).
+(see [gh-107](https://github.com/scipy/scipy_doctest/pull/107) for an example).
 
 - *Optional dependencies are not that optional*
 

{scipy_doctest-1.1 → scipy_doctest-1.2.0}/scipy_doctest/__init__.py

@@ -5,7 +5,7 @@ Whitespace-insensitive, numpy-aware, floating-point-aware doctest helpers.
 """
 
 
-__version__ = "1.1"
+__version__ = "1.2.0"
 
 from .impl import DTChecker, DTFinder, DTParser, DTRunner, DebugDTRunner, DTConfig  # noqa
 from .frontend import testmod, testfile, find_doctests, run_docstring_examples      # noqa

{scipy_doctest-1.1 → scipy_doctest-1.2.0}/scipy_doctest/frontend.py

@@ -70,8 +70,11 @@ def find_doctests(module, strategy=None,
         return tests
 
     if strategy == "api":
-        (items, names), failures = get_public_objects(module,
-                                                      skiplist=config.skiplist)
+
+        with config.user_context_mgr():
+            # user_context_mgr may want to e.g. filter warnings on imports?
+            (items, names), failures = get_public_objects(module,
+                                                          skiplist=config.skiplist)
         if failures:
             mesg = "\n".join([_[2] for _ in failures])
             raise ValueError(mesg)

{scipy_doctest-1.1 → scipy_doctest-1.2.0}/scipy_doctest/impl.py

@@ -2,6 +2,7 @@ import re
 import warnings
 import doctest
 from doctest import NORMALIZE_WHITESPACE, ELLIPSIS, IGNORE_EXCEPTION_DETAIL
+from itertools import zip_longest
 
 import numpy as np
 
@@ -219,6 +220,30 @@ def try_convert_namedtuple(got):
     return got_again
 
 
+def try_convert_printed_array(got):
+    """Printed arrays: reinsert commas.
+    """
+    # a minimal version is `s_got = ", ".join(got[1:-1].split())`
+    # but it fails if there's a space after the opening bracket: "[ 0 1 2 ]"
+    # For 2D arrays, split into rows, drop spurious entries, then reassemble.
+    if not got.startswith('['):
+        return got
+
+    g1 = got[1:-1]  # strip outer "[...]"-s
+    rows = [x for x in g1.split("[") if x]
+    rows2 = [", ".join(row.split()) for row in rows]
+
+    if got.startswith("[["):
+        # was a 2D array, restore the opening brackets in rows; XXX clean up
+        rows3 = ["[" + row for row in rows2]
+    else:
+        rows3 = rows2
+
+    # add back the outer brackets
+    s_got = "[" + ", ".join(rows3) + "]"
+    return s_got
+
+
 def has_masked(got):
     return 'masked_array' in got and '--' in got
 
@@ -280,8 +305,9 @@ class DTChecker(doctest.OutputChecker):
             cond = (s_want.startswith("[") and s_want.endswith("]") and
                     s_got.startswith("[") and s_got.endswith("]"))
             if cond:
-                s_want = ", ".join(s_want[1:-1].split())
-                s_got = ", ".join(s_got[1:-1].split())
+                s_want = try_convert_printed_array(s_want)
+                s_got = try_convert_printed_array(s_got)
+
                 return self.check_output(s_want, s_got, optionflags)
             
             #handle array abbreviation for n-dimensional arrays, n >= 1
@@ -322,13 +348,19 @@ class DTChecker(doctest.OutputChecker):
             else:
                 return self.check_output(want_again, got_again, optionflags)
 
+        # Validate data type if list or tuple
+        is_list_or_tuple = (isinstance(a_want, (list, tuple)) and
+                            isinstance(a_got, (list, tuple)))
+        if is_list_or_tuple and type(a_want) is not type(a_got):
+            return False
+
         # ... and defer to numpy
         try:
             return self._do_check(a_want, a_got)
         except Exception:
             # heterog tuple, eg (1, np.array([1., 2.]))
             try:
-                return all(self._do_check(w, g) for w, g in zip(a_want, a_got))
+                return all(self._do_check(w, g) for w, g in zip_longest(a_want, a_got))
             except (TypeError, ValueError):
                 return False
 

scipy_doctest-1.2.0/scipy_doctest/tests/failure_cases.py

@@ -0,0 +1,47 @@
+__all__ = ['func9', 'func10', 'iterable_length_1', 'iterable_length_2',
+           'tuple_and_list_1', 'tuple_and_list_2']
+
+
+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])
+    """
+
+
+def iterable_length_1():
+    """
+    >>> [1, 2, 3]
+    [1, 2, 3, 4]
+    """
+
+
+def iterable_length_2():
+    """
+    >>> [1, 2, 3]
+    [1, 2]
+    """
+
+
+def tuple_and_list_1():
+    """
+    >>> [0, 1, 2]
+    (0, 1, 2)
+    """
+
+
+def tuple_and_list_2():
+    """
+    >>> (0, 1, 2)
+    [0, 1, 2]
+    """

{scipy_doctest-1.1 → scipy_doctest-1.2.0}/scipy_doctest/tests/module_cases.py

@@ -44,6 +44,32 @@ def func3():
     """
 
 
+def func_printed_arrays():
+    """
+    Check various ways handling of printed arrays can go wrong.
+
+    >>> import numpy as np
+    >>> a = np.arange(8).reshape(2, 4) / 3
+    >>> print(a)  # numpy 1.26.4
+    [[0.         0.33333333 0.66666667 1.        ]
+     [1.33333333 1.66666667 2.         2.33333333]]
+
+    >>> print(a)   # add spaces (older repr?)
+    [[ 0.         0.33333333 0.66666667 1.         ]
+     [ 1.33333333 1.66666667 2.         2.33333333 ]]
+
+    Also check 1D arrays
+    >>> a1 = np.arange(3)
+    >>> print(a1)
+    [0 1 2]
+    >>> print(a1)
+    [ 0 1 2]
+    >>> print(a1)
+    [ 0 1 2 ]
+
+    """
+
+
 def func4():
     """
     Test `# may vary` markers : these should not break doctests (but the code
@@ -190,3 +216,19 @@ def test_cmplx_nan():
     >>> 1j*np.complex128(np.nan)
     np.complex128(nan+nanj)
     """
+
+
+def array_and_list_1():
+    """
+    >>> import numpy as np
+    >>> np.array([1, 2, 3])
+    [1, 2, 3]
+    """
+
+
+def array_and_list_2():
+    """
+    >>> import numpy as np
+    >>> [1, 2, 3]
+    array([1, 2, 3])
+    """

{scipy_doctest-1.1 → scipy_doctest-1.2.0}/scipy_doctest/tests/test_testmod.py

@@ -99,6 +99,24 @@ def test_user_context():
                 config=config)
 
 
+def test_wrong_lengths():
+    config = DTConfig()
+    res, _ = _testmod(failure_cases,
+                      strategy=[failure_cases.iterable_length_1,
+                                failure_cases.iterable_length_2],
+                      config=config)
+    assert res.failed == 2
+
+
+def test_tuple_and_list():
+    config = DTConfig()
+    res, _ = _testmod(failure_cases,
+                      strategy=[failure_cases.tuple_and_list_1,
+                                failure_cases.tuple_and_list_2],
+                      config=config)
+    assert res.failed == 2
+
+
 class TestLocalFiles:
     def test_local_files(self):
         # A doctest tries to open a local file. Test that it works

{scipy_doctest-1.1 → scipy_doctest-1.2.0}/scipy_doctest/util.py

@@ -98,7 +98,7 @@ def numpy_rndm_state():
 
 
 @contextmanager
-def noop_context_mgr(test):
+def noop_context_mgr(test=None):
     """Do nothing.
 
     This is a stub context manager to serve as a default for
@@ -117,7 +117,7 @@ def np_errstate():
 
 
 @contextmanager
-def warnings_errors(test):
+def warnings_errors(test=None):
     """Temporarily turn all warnings to errors."""
     with warnings.catch_warnings():
         warnings.simplefilter('error', Warning)

scipy_doctest-1.1/scipy_doctest/tests/failure_cases.py

@@ -1,17 +0,0 @@
-__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])
-    """