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

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: scipy_doctest
-Version: 1.1
-Summary: Doctests on steroids.
+Version: 1.3
+Summary: Configurable, whitespace-insensitive, floating-point-aware doctest helpers.
 Maintainer-email: SciPy developers <scipy-dev@python.org>
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
@@ -14,11 +14,20 @@ Requires-Dist: numpy>=1.19.5
 Requires-Dist: pytest
 Requires-Dist: scipy ; extra == "test"
 Requires-Dist: matplotlib ; extra == "test"
-Project-URL: Home, https://github.com/ev-br/scpdt
+Project-URL: Home, https://github.com/scipy/scipy_doctest
 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
@@ -91,8 +100,8 @@ the output. Thus the example source needs to be valid python code still.
 ## Install and test
 
 ```
-$ pip install -e .
-$ pytest --pyargs scpdt
+$ pip install scipy-doctest
+$ pytest --pyargs scipy_doctest
 ```
 
 ## Usage
@@ -103,14 +112,61 @@ or nearly so.
 
 The other layer is the `pytest` plugin.
 
+### Run doctests via pytest
+
+To run doctests on your package or project, follow these steps:
+
+1. **Install the plugin**
+
+```bash
+pip install scipy-doctest
+```
+
+2. **Register or load the plugin**
+
+Next, you need to register or load the pytest plugin within your test module or `conftest.py` file. 
+
+To do this, add the following line of code:
+
+```python
+# In your conftest.py file or test module
+
+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. **Run doctests** 
+
+Once the plugin is registered, run the doctests by executing the following command:
+
+```bash
+$ python -m pytest --doctest-modules
+```
+or
+```bash
+$ pytest --pyargs <your-package> --doctest-modules
+```
+
+By default, all doctests are collected. To only collect public objects, `strategy="api"`,
+use the command flag
+
+```bash
+$ pytest --pyargs <your-package> --doctest-modules --doctest-collect=api
+```
+
+See [More fine-grained control](https://github.com/scipy/scipy_doctest#More-fine-grained-control) section
+for details on how to customize the behavior.
+
 
 ### Basic usage
 
+The use of `pytest` is optional, and you can use the `doctest` layer API.
 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)
@@ -122,11 +178,12 @@ For more details, see the `testmod` docstring. Other useful functions are
 `find_doctests`, `run_docstring_examples` and `testfile` (the latter two mimic
 the behavior of the eponymous functions of the `doctest` module).
 
-#### Command-line interface
+
+### Command-line interface
 
 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,11 +191,13 @@ 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
 ```
 
+Notice that the command-line usage only uses the default `DTConfig` settings.
+
 
-#### More fine-grained control
+## More fine-grained control
 
 More fine-grained control of the functionality is available via the following
 classes
@@ -157,134 +216,104 @@ configuration is simply creating an instance, overriding an attribute and
 passing the instance to `testmod` or constructors of `DT*` objects. Defaults
 are provided, based on a long-term usage in SciPy.
 
+See the [DTConfig docstring](https://github.com/scipy/scipy_doctest/blob/main/scipy_doctest/impl.py#L24)
+for the full set of attributes that allow you to fine-tune your doctesting experience.
 
-### The Scpdt Pytest Plugin
+To set any of these attributes, create an instance of `DTConfig` and assign the attributes
+in a usual way. 
 
-The pytest plugin enables the use of scpdt tools to perform doctests. 
+If using the pytest plugin, it is convenient to use the default instance, which
+is predefined in `scipy_doctest/conftest.py`. This instance will be automatically
+passed around via an
+[attribute of pytest's `Config` object](https://github.com/scipy/scipy_doctest/blob/58ff06a837b7bff1dbac6560013fc6fd07952ae2/scipy_doctest/plugin.py#L39).
 
-Follow the given instructions to utilize the pytest plugin for doctesting.
+### Examples
 
-### Running doctests on Scipy
-1. **Install plugin**
+```
+dt_config = DTConfig()
+```
 
-Start by installing the pytest plugin via pip:
+or, if using pytest,
 
-```bash
-pip install git+https://github.com/ev-br/scpdt.git@main
+```python
+from scipy_doctest.conftest import dt_config   # a DTConfig instance with default settings
 ```
 
-2. **Configure Your Doctesting Experience**
+and then
 
-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.
+```
+dt_config.rndm_markers = {'# unintialized'}
 
-3. **Run Doctests**
+dt_config.stopwords = {'plt.', 'plt.hist', 'plt.show'}
 
-Doctesting is configured to execute on SciPy using the `dev.py` module.
+dt_config.local_resources = {
+    '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']
+}
 
-To run all doctests, use the following command:
-```bash
-python dev.py test --doctests
+dt_config.skiplist = {
+    'scipy.special.sinc',
+    'scipy.misc.who',
+    'scipy.optimize.show_options'
+}
 ```
 
-To run doctests on specific SciPy modules, e.g: `cluster`, use the following command:
+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.
 
-```bash
-python dev.py test --doctests -s cluster
-```
 
-### Running Doctests on Other Packages/Projects
+#### Alternative Checkers
 
-If you want to run doctests on packages or projects other than SciPy, follow these steps:
+By default, we use the floating-point aware `DTChecker`. If you want to use an
+alternative checker, all you need to do is to define the corresponding class,
+and add an attribute to the `DTConfig` instance. For example,
 
-1. **Install the plugin**
 
-```bash
-pip install git+https://github.com/ev-br/scpdt.git@main
+```
+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
 ```
 
-2. **Register or Load the Plugin**
+and
 
-Next, you need to register or load the pytest plugin within your test module or `conftest.py` file. 
+```
+dt_config = DTConfig()
+dt_config.CheckerKlass = VanillaOutputChecker
+```
 
-To do this, add the following line of code:
+See [a pytest example](https://github.com/scipy/scipy_doctest/blob/main/scipy_doctest/tests/test_pytest_configuration.py#L63)
+and [a doctest example](https://github.com/scipy/scipy_doctest/blob/main/scipy_doctest/tests/test_runner.py#L94)
+for more details.
 
-```python
-# In your conftest.py file or test module
 
-pytest_plugins = "scpdt"
-```
+### The SciPy Doctest Pytest Plugin
 
-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.
+The pytest plugin enables the use of `scipy_doctest` tools to perform doctests.
 
-3. **Configure your doctesting experience**
+Follow the given instructions to utilize the pytest plugin for doctesting.
 
-An in-depth explanation is given in the [tailoring your doctesting experience](https://github.com/ev-br/scpdt#tailoring-your-doctesting-experience) section.
+### NumPy and SciPy wrappers
 
-4. **Run doctests** 
 
-Once the plugin is registered, you can run your doctests by executing the following command:
+NumPy wraps `scipy-doctest` with the `spin` command
 
-```bash
-$ python -m pytest --doctest-modules
 ```
-or
-```bash
-$ pytest --pyargs <your-package> --doctest-modules
+$ spin check-docs
 ```
 
-By default, all doctests are collected. To only collect public objects, `strategy="api"`,
-use the command flag
+SciPy wraps `scipy-doctest` with custom `dev.py` commands:
 
-```bash
-$ 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. 
-
-These attributes include:
-1. **default_namespace (dict):** Defines the namespace in which examples are executed.
-2. **check_namespace (dict):** Specifies the namespace for conducting checks.
-3. **rndm_markers (set):** Provides additional directives which act like `# doctest: + SKIP`.
-4. **atol (float) and rtol (float):** Sets absolute and relative tolerances for validating doctest examples. 
-Specifically, it governs the check using `np.allclose(want, got, atol=atol, rtol=rtol)`.
-5. **optionflags (int):** These are doctest option flags.
-The default setting includes `NORMALIZE_WHITESPACE` | `ELLIPSIS` | `IGNORE_EXCEPTION_DETAIL`.
-6. **stopwords (set):** If an example contains any of these stopwords, the output is not checked (though the source's validity is still assessed).
-7. **pseudocode (list):** Lists strings that, when found in an example, result in no doctesting. This resembles the `# doctest +SKIP` directive and is useful for pseudocode blocks or similar cases.
-8. **skiplist (set):** A list of names of objects with docstrings known to fail doctesting and are intentionally excluded from testing.
-9. **user_context_mgr:** A context manager for running tests. 
-Typically, it is entered for each DocTest (especially in API documentation), ensuring proper testing isolation.
-10. **local_resources (dict):** Specifies local files needed for specific tests. The format is `{test.name: list-of-files}`. File paths are relative to the path of `test.filename`.
-11. **parse_namedtuples (bool):** Determines whether to perform a literal comparison (e.g., `TTestResult(pvalue=0.9, statistic=42)`) or extract and compare the tuple values (e.g., `(0.9, 42)`). The default is `True`.
-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).
-
-**Example:**
-
-```python
-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']
-}
-dt_config.skiplist = {
-    'scipy.special.sinc',
-    'scipy.misc.who',
-    'scipy.optimize.show_options'
-}
+$ python dev.py smoke-docs    # check docstrings
+$ python dev.py smoke-tutorials   # ReST user guide tutorials
 ```
 
-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.
-
-By following these steps, you will be able to effectively use the Scpdt pytest plugin for doctests in your Python projects.
 
-Happy testing!
 
 ## Rough edges and sharp bits
 
@@ -309,7 +338,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*
 
@@ -318,7 +347,7 @@ being optional. So you either guard the imports in doctests (yikes!), or
 the collections fails if dependencies are not available.
 
 The solution is to explicitly `--ignore` the paths to modules with optionals.
-(or use `DTConfig.pytest_extra_ignore` list):
+(or, equivalently, use `DTConfig.pytest_extra_ignore` list):
 
 ```
 $ pytest --ignore=/build-install/lib/scipy/python3.10/site-packages/scipy/_lib ...
@@ -362,20 +391,17 @@ leads to
   differences are: (i) `pytest-doctestplus` is more sensitive to formatting,
   including whitespace---thus if numpy tweaks its output formatting, doctests
   may start failing; (ii) there is still a need for `# doctest: +FLOAT_CMP`
-  directives; (iii) being a pytest plugin, `pytest-doctestplus` is tightly
-  coupled to `pytest`. It thus needs to follow `pytest` releases, and
-  some maintenance work may be required to adapt when `pytest` publishes a new
-  release.
+  directives.
 
   This project takes a different approach: in addition to plugging into `pytest`,
   we closely follow the `doctest` API and implementation, which are naturally
   way more stable then `pytest`.
 
-- `NumPy` and `SciPy` use modified doctesting in their `refguide-check` utilities.
+- `NumPy` and `SciPy` were using modified doctesting in their `refguide-check` utilities.
   These utilities are tightly coupled to their libraries, and have been reported
   to be not easy to reason about, work with, and extend to other projects.
 
-  This project is nothing but the core functionality of the modified
+  This project is mainly the core functionality of the modified
   `refguide-check` doctesting, extracted to a separate package. 
   We believe having it separate simplifies both addressing the needs of these
   two packages, and potential adoption by other projects.

{scipy_doctest-1.1 → scipy_doctest-1.3}/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
@@ -72,8 +81,8 @@ the output. Thus the example source needs to be valid python code still.
 ## Install and test
 
 ```
-$ pip install -e .
-$ pytest --pyargs scpdt
+$ pip install scipy-doctest
+$ pytest --pyargs scipy_doctest
 ```
 
 ## Usage
@@ -84,14 +93,61 @@ or nearly so.
 
 The other layer is the `pytest` plugin.
 
+### Run doctests via pytest
+
+To run doctests on your package or project, follow these steps:
+
+1. **Install the plugin**
+
+```bash
+pip install scipy-doctest
+```
+
+2. **Register or load the plugin**
+
+Next, you need to register or load the pytest plugin within your test module or `conftest.py` file. 
+
+To do this, add the following line of code:
+
+```python
+# In your conftest.py file or test module
+
+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. **Run doctests** 
+
+Once the plugin is registered, run the doctests by executing the following command:
+
+```bash
+$ python -m pytest --doctest-modules
+```
+or
+```bash
+$ pytest --pyargs <your-package> --doctest-modules
+```
+
+By default, all doctests are collected. To only collect public objects, `strategy="api"`,
+use the command flag
+
+```bash
+$ pytest --pyargs <your-package> --doctest-modules --doctest-collect=api
+```
+
+See [More fine-grained control](https://github.com/scipy/scipy_doctest#More-fine-grained-control) section
+for details on how to customize the behavior.
+
 
 ### Basic usage
 
+The use of `pytest` is optional, and you can use the `doctest` layer API.
 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)
@@ -103,11 +159,12 @@ For more details, see the `testmod` docstring. Other useful functions are
 `find_doctests`, `run_docstring_examples` and `testfile` (the latter two mimic
 the behavior of the eponymous functions of the `doctest` module).
 
-#### Command-line interface
+
+### Command-line interface
 
 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,11 +172,13 @@ 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
 ```
 
+Notice that the command-line usage only uses the default `DTConfig` settings.
+
 
-#### More fine-grained control
+## More fine-grained control
 
 More fine-grained control of the functionality is available via the following
 classes
@@ -138,134 +197,104 @@ configuration is simply creating an instance, overriding an attribute and
 passing the instance to `testmod` or constructors of `DT*` objects. Defaults
 are provided, based on a long-term usage in SciPy.
 
+See the [DTConfig docstring](https://github.com/scipy/scipy_doctest/blob/main/scipy_doctest/impl.py#L24)
+for the full set of attributes that allow you to fine-tune your doctesting experience.
 
-### The Scpdt Pytest Plugin
+To set any of these attributes, create an instance of `DTConfig` and assign the attributes
+in a usual way. 
 
-The pytest plugin enables the use of scpdt tools to perform doctests. 
+If using the pytest plugin, it is convenient to use the default instance, which
+is predefined in `scipy_doctest/conftest.py`. This instance will be automatically
+passed around via an
+[attribute of pytest's `Config` object](https://github.com/scipy/scipy_doctest/blob/58ff06a837b7bff1dbac6560013fc6fd07952ae2/scipy_doctest/plugin.py#L39).
 
-Follow the given instructions to utilize the pytest plugin for doctesting.
+### Examples
 
-### Running doctests on Scipy
-1. **Install plugin**
+```
+dt_config = DTConfig()
+```
 
-Start by installing the pytest plugin via pip:
+or, if using pytest,
 
-```bash
-pip install git+https://github.com/ev-br/scpdt.git@main
+```python
+from scipy_doctest.conftest import dt_config   # a DTConfig instance with default settings
 ```
 
-2. **Configure Your Doctesting Experience**
+and then
 
-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.
+```
+dt_config.rndm_markers = {'# unintialized'}
 
-3. **Run Doctests**
+dt_config.stopwords = {'plt.', 'plt.hist', 'plt.show'}
 
-Doctesting is configured to execute on SciPy using the `dev.py` module.
+dt_config.local_resources = {
+    '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']
+}
 
-To run all doctests, use the following command:
-```bash
-python dev.py test --doctests
+dt_config.skiplist = {
+    'scipy.special.sinc',
+    'scipy.misc.who',
+    'scipy.optimize.show_options'
+}
 ```
 
-To run doctests on specific SciPy modules, e.g: `cluster`, use the following command:
+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.
 
-```bash
-python dev.py test --doctests -s cluster
-```
 
-### Running Doctests on Other Packages/Projects
+#### Alternative Checkers
 
-If you want to run doctests on packages or projects other than SciPy, follow these steps:
+By default, we use the floating-point aware `DTChecker`. If you want to use an
+alternative checker, all you need to do is to define the corresponding class,
+and add an attribute to the `DTConfig` instance. For example,
 
-1. **Install the plugin**
 
-```bash
-pip install git+https://github.com/ev-br/scpdt.git@main
+```
+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
 ```
 
-2. **Register or Load the Plugin**
+and
 
-Next, you need to register or load the pytest plugin within your test module or `conftest.py` file. 
+```
+dt_config = DTConfig()
+dt_config.CheckerKlass = VanillaOutputChecker
+```
 
-To do this, add the following line of code:
+See [a pytest example](https://github.com/scipy/scipy_doctest/blob/main/scipy_doctest/tests/test_pytest_configuration.py#L63)
+and [a doctest example](https://github.com/scipy/scipy_doctest/blob/main/scipy_doctest/tests/test_runner.py#L94)
+for more details.
 
-```python
-# In your conftest.py file or test module
 
-pytest_plugins = "scpdt"
-```
+### The SciPy Doctest Pytest Plugin
 
-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.
+The pytest plugin enables the use of `scipy_doctest` tools to perform doctests.
 
-3. **Configure your doctesting experience**
+Follow the given instructions to utilize the pytest plugin for doctesting.
 
-An in-depth explanation is given in the [tailoring your doctesting experience](https://github.com/ev-br/scpdt#tailoring-your-doctesting-experience) section.
+### NumPy and SciPy wrappers
 
-4. **Run doctests** 
 
-Once the plugin is registered, you can run your doctests by executing the following command:
+NumPy wraps `scipy-doctest` with the `spin` command
 
-```bash
-$ python -m pytest --doctest-modules
 ```
-or
-```bash
-$ pytest --pyargs <your-package> --doctest-modules
+$ spin check-docs
 ```
 
-By default, all doctests are collected. To only collect public objects, `strategy="api"`,
-use the command flag
+SciPy wraps `scipy-doctest` with custom `dev.py` commands:
 
-```bash
-$ 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. 
-
-These attributes include:
-1. **default_namespace (dict):** Defines the namespace in which examples are executed.
-2. **check_namespace (dict):** Specifies the namespace for conducting checks.
-3. **rndm_markers (set):** Provides additional directives which act like `# doctest: + SKIP`.
-4. **atol (float) and rtol (float):** Sets absolute and relative tolerances for validating doctest examples. 
-Specifically, it governs the check using `np.allclose(want, got, atol=atol, rtol=rtol)`.
-5. **optionflags (int):** These are doctest option flags.
-The default setting includes `NORMALIZE_WHITESPACE` | `ELLIPSIS` | `IGNORE_EXCEPTION_DETAIL`.
-6. **stopwords (set):** If an example contains any of these stopwords, the output is not checked (though the source's validity is still assessed).
-7. **pseudocode (list):** Lists strings that, when found in an example, result in no doctesting. This resembles the `# doctest +SKIP` directive and is useful for pseudocode blocks or similar cases.
-8. **skiplist (set):** A list of names of objects with docstrings known to fail doctesting and are intentionally excluded from testing.
-9. **user_context_mgr:** A context manager for running tests. 
-Typically, it is entered for each DocTest (especially in API documentation), ensuring proper testing isolation.
-10. **local_resources (dict):** Specifies local files needed for specific tests. The format is `{test.name: list-of-files}`. File paths are relative to the path of `test.filename`.
-11. **parse_namedtuples (bool):** Determines whether to perform a literal comparison (e.g., `TTestResult(pvalue=0.9, statistic=42)`) or extract and compare the tuple values (e.g., `(0.9, 42)`). The default is `True`.
-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).
-
-**Example:**
-
-```python
-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']
-}
-dt_config.skiplist = {
-    'scipy.special.sinc',
-    'scipy.misc.who',
-    'scipy.optimize.show_options'
-}
+$ python dev.py smoke-docs    # check docstrings
+$ python dev.py smoke-tutorials   # ReST user guide tutorials
 ```
 
-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.
-
-By following these steps, you will be able to effectively use the Scpdt pytest plugin for doctests in your Python projects.
 
-Happy testing!
 
 ## Rough edges and sharp bits
 
@@ -290,7 +319,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*
 
@@ -299,7 +328,7 @@ being optional. So you either guard the imports in doctests (yikes!), or
 the collections fails if dependencies are not available.
 
 The solution is to explicitly `--ignore` the paths to modules with optionals.
-(or use `DTConfig.pytest_extra_ignore` list):
+(or, equivalently, use `DTConfig.pytest_extra_ignore` list):
 
 ```
 $ pytest --ignore=/build-install/lib/scipy/python3.10/site-packages/scipy/_lib ...
@@ -343,20 +372,17 @@ leads to
   differences are: (i) `pytest-doctestplus` is more sensitive to formatting,
   including whitespace---thus if numpy tweaks its output formatting, doctests
   may start failing; (ii) there is still a need for `# doctest: +FLOAT_CMP`
-  directives; (iii) being a pytest plugin, `pytest-doctestplus` is tightly
-  coupled to `pytest`. It thus needs to follow `pytest` releases, and
-  some maintenance work may be required to adapt when `pytest` publishes a new
-  release.
+  directives.
 
   This project takes a different approach: in addition to plugging into `pytest`,
   we closely follow the `doctest` API and implementation, which are naturally
   way more stable then `pytest`.
 
-- `NumPy` and `SciPy` use modified doctesting in their `refguide-check` utilities.
+- `NumPy` and `SciPy` were using modified doctesting in their `refguide-check` utilities.
   These utilities are tightly coupled to their libraries, and have been reported
   to be not easy to reason about, work with, and extend to other projects.
 
-  This project is nothing but the core functionality of the modified
+  This project is mainly the core functionality of the modified
   `refguide-check` doctesting, extracted to a separate package. 
   We believe having it separate simplifies both addressing the needs of these
   two packages, and potential adoption by other projects.

{scipy_doctest-1.1 → scipy_doctest-1.3}/pyproject.toml

@@ -30,7 +30,7 @@ test = [
 ]
 
 [project.urls]
-Home = "https://github.com/ev-br/scpdt"
+Home = "https://github.com/scipy/scipy_doctest"
 
 [tool.pytest.ini_options]
 addopts = "--verbose --color=yes"

scipy_doctest-1.3/scipy_doctest/__init__.py

@@ -0,0 +1,22 @@
+"""
+Configurable, whitespace-insensitive, floating-point-aware doctest helpers.
+"""
+
+
+__version__ = "1.3"
+
+try:
+    # register internal modules with pytest; obscure errors galore otherwise
+    import pytest
+    pytest.register_assert_rewrite(
+        "scipy_doctest.conftest", "scipy_doctest.impl", "scipy_doctest.util",
+        "scipy_doctest.frontend", "scipy_doctest.plugin"
+    )
+except ModuleNotFoundError:
+    # pytest is optional, so nothing to do
+    pass
+
+
+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.3}/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.3}/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
 
@@ -90,6 +91,14 @@ class DTConfig:
         adding `# may vary` to the outputs of all examples.
         Each key is a doctest name to skip, and the corresponding value is
         a string. If not empty, the string value is used as the skip reason.
+    CheckerKlass : object, optional
+        The class for the Checker object. Must mimic the ``DTChecker`` API:
+        subclass the `doctest.OutputChecker` and make the constructor signature
+        read ``__init__(self, config=None)``, where `config` is a ``DTConfig``
+        instance.
+        This class will be instantiated by ``DTRunner``.
+        Defaults to `DTChecker`.
+
     """
     def __init__(self, *, # DTChecker configuration
                           CheckerKlass=None,
@@ -219,6 +228,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 +313,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 +356,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.3/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.3}/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.3}/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.3}/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/__init__.py

@@ -1,12 +0,0 @@
-"""
-Doctests on steroids.
-
-Whitespace-insensitive, numpy-aware, floating-point-aware doctest helpers.
-"""
-
-
-__version__ = "1.1"
-
-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/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])
-    """