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

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: scipy_doctest
-Version: 1.2.0
-Summary: Doctests on steroids.
+Version: 1.4
+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,7 +14,7 @@ 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.
@@ -67,8 +67,8 @@ Its main features are
   >>> np.random.randint(100)
   42     # may vary
   ```
-Note that the markers (by default, `"# may vary"` and `"# random"`) are applied
-to an example's output, not its source.
+Note that the markers (by default, `"# may vary"` and `"# random"`) can be applied
+to either an example's output, or its source.
 
 Also note a difference with respect to the standard `# doctest: +SKIP`: the latter
 skips the example entirely, while these additional markers only skip checking
@@ -100,7 +100,7 @@ the output. Thus the example source needs to be valid python code still.
 ## Install and test
 
 ```
-$ pip install -e .
+$ pip install scipy-doctest
 $ pytest --pyargs scipy_doctest
 ```
 
@@ -112,9 +112,56 @@ 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,
 
 ```
@@ -131,7 +178,8 @@ 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:
 ```
@@ -146,8 +194,10 @@ Text files can also be CLI-checked:
 $ 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
@@ -166,133 +216,98 @@ 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 SciPy Doctest 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 `scipy_doctest` 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**
-
-```bash
-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/scipy/scipy_doctest#tailoring-your-doctesting-experience) section.
-
-3. **Run Doctests**
-
-Doctesting is configured to execute on SciPy using the `dev.py` module.
-
-To run all doctests, use the following command:
-```bash
-python dev.py smoke-docs
+dt_config = DTConfig()
 ```
 
-To run doctests on specific SciPy modules, e.g: `cluster`, use the following command:
+or, if using pytest,
 
-```bash
-python dev.py smoke-docs -s cluster
+```python
+from scipy_doctest.conftest import dt_config   # a DTConfig instance with default settings
 ```
 
-### Running Doctests on Other Packages/Projects
+and then
 
-If you want to run doctests on packages or projects other than SciPy, follow these steps:
-
-1. **Install the plugin**
-
-```bash
-pip install scipy-doctest
 ```
+dt_config.rndm_markers = {'# unintialized'}
 
-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:
+dt_config.stopwords = {'plt.', 'plt.hist', 'plt.show'}
 
-```python
-# In your conftest.py file or test 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']
+}
 
-pytest_plugins = "scipy_doctest"
+dt_config.skiplist = {
+    'scipy.special.sinc',
+    'scipy.misc.who',
+    'scipy.optimize.show_options'
+}
 ```
 
-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.
+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.
 
-3. **Configure your doctesting experience**
 
-An in-depth explanation is given in the [tailoring your doctesting experience](https://github.com/scipy/scipy_doctest#tailoring-your-doctesting-experience) section.
+#### Alternative Checkers
 
-4. **Run doctests** 
+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,
 
-Once the plugin is registered, you can run your doctests by executing the following command:
 
-```bash
-$ python -m pytest --doctest-modules
 ```
-or
-```bash
-$ pytest --pyargs <your-package> --doctest-modules
+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
 ```
 
-By default, all doctests are collected. To only collect public objects, `strategy="api"`,
-use the command flag
+and
 
-```bash
-$ pytest --pyargs <your-package> --doctest-modules --doctest-collect=api
+```
+dt_config = DTConfig()
+dt_config.CheckerKlass = VanillaOutputChecker
 ```
 
-### Tailoring Your Doctesting Experience
+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.
 
-[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.
-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`.
+### NumPy and SciPy wrappers
 
-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/scipy/scipy_doctest/blob/58ff06a837b7bff1dbac6560013fc6fd07952ae2/scipy_doctest/plugin.py#L39).
 
-**Example:**
+NumPy wraps `scipy-doctest` with the `spin` command
 
-```python
-dt_config = DTConfig()
-dt_config.stopwords = {'plt.', '.hist', '.show'}
-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']
-}
-dt_config.skiplist = {
-    'scipy.special.sinc',
-    'scipy.misc.who',
-    'scipy.optimize.show_options'
-}
+```
+$ spin check-docs
 ```
 
-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.
+SciPy wraps `scipy-doctest` with custom `dev.py` commands:
+
+```
+$ python dev.py smoke-docs    # check docstrings
+$ python dev.py smoke-tutorials   # ReST user guide tutorials
+```
 
-By following these steps, you will be able to effectively use the SciPy Doctest pytest plugin for doctests in your Python projects.
 
-Happy testing!
 
 ## Rough edges and sharp bits
 
@@ -326,7 +341,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 ...
@@ -361,6 +376,19 @@ leads to
 - `scipy.linalg.det`, collected from `scipy/linalg/__init__.py`, is public.
 
 
+- *`pytest`'s assertion rewriting*
+
+In some rare cases you may need to either explicitly register the `scipy_doctest`
+package with the `pytest` assertion rewriting machinery, or ask it to avoid rewriting
+completely, via `pytest --assert=plain`.
+See [the `pytest documentation`](https://docs.pytest.org/en/7.1.x/how-to/assert.html)
+for more details.
+
+In general, rewriting assertions is not very useful for doctests, as the
+output on error is fixed by the doctest machinery anyway. Therefore, we believe
+adding `--assert=plain` is reasonable.
+
+
 ## Prior art and related work
 
 - `pytest` provides some limited floating-point aware `NumericLiteralChecker`.
@@ -370,20 +398,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.2.0 → scipy_doctest-1.4}/README.md

@@ -48,8 +48,8 @@ Its main features are
   >>> np.random.randint(100)
   42     # may vary
   ```
-Note that the markers (by default, `"# may vary"` and `"# random"`) are applied
-to an example's output, not its source.
+Note that the markers (by default, `"# may vary"` and `"# random"`) can be applied
+to either an example's output, or its source.
 
 Also note a difference with respect to the standard `# doctest: +SKIP`: the latter
 skips the example entirely, while these additional markers only skip checking
@@ -81,7 +81,7 @@ the output. Thus the example source needs to be valid python code still.
 ## Install and test
 
 ```
-$ pip install -e .
+$ pip install scipy-doctest
 $ pytest --pyargs scipy_doctest
 ```
 
@@ -93,9 +93,56 @@ 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,
 
 ```
@@ -112,7 +159,8 @@ 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:
 ```
@@ -127,8 +175,10 @@ Text files can also be CLI-checked:
 $ 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
@@ -147,133 +197,98 @@ 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 SciPy Doctest 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 `scipy_doctest` 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**
-
-```bash
-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/scipy/scipy_doctest#tailoring-your-doctesting-experience) section.
-
-3. **Run Doctests**
-
-Doctesting is configured to execute on SciPy using the `dev.py` module.
-
-To run all doctests, use the following command:
-```bash
-python dev.py smoke-docs
+dt_config = DTConfig()
 ```
 
-To run doctests on specific SciPy modules, e.g: `cluster`, use the following command:
+or, if using pytest,
 
-```bash
-python dev.py smoke-docs -s cluster
+```python
+from scipy_doctest.conftest import dt_config   # a DTConfig instance with default settings
 ```
 
-### Running Doctests on Other Packages/Projects
+and then
 
-If you want to run doctests on packages or projects other than SciPy, follow these steps:
-
-1. **Install the plugin**
-
-```bash
-pip install scipy-doctest
 ```
+dt_config.rndm_markers = {'# unintialized'}
 
-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:
+dt_config.stopwords = {'plt.', 'plt.hist', 'plt.show'}
 
-```python
-# In your conftest.py file or test 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']
+}
 
-pytest_plugins = "scipy_doctest"
+dt_config.skiplist = {
+    'scipy.special.sinc',
+    'scipy.misc.who',
+    'scipy.optimize.show_options'
+}
 ```
 
-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.
+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.
 
-3. **Configure your doctesting experience**
 
-An in-depth explanation is given in the [tailoring your doctesting experience](https://github.com/scipy/scipy_doctest#tailoring-your-doctesting-experience) section.
+#### Alternative Checkers
 
-4. **Run doctests** 
+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,
 
-Once the plugin is registered, you can run your doctests by executing the following command:
 
-```bash
-$ python -m pytest --doctest-modules
 ```
-or
-```bash
-$ pytest --pyargs <your-package> --doctest-modules
+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
 ```
 
-By default, all doctests are collected. To only collect public objects, `strategy="api"`,
-use the command flag
+and
 
-```bash
-$ pytest --pyargs <your-package> --doctest-modules --doctest-collect=api
+```
+dt_config = DTConfig()
+dt_config.CheckerKlass = VanillaOutputChecker
 ```
 
-### Tailoring Your Doctesting Experience
+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.
 
-[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.
-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`.
+### NumPy and SciPy wrappers
 
-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/scipy/scipy_doctest/blob/58ff06a837b7bff1dbac6560013fc6fd07952ae2/scipy_doctest/plugin.py#L39).
 
-**Example:**
+NumPy wraps `scipy-doctest` with the `spin` command
 
-```python
-dt_config = DTConfig()
-dt_config.stopwords = {'plt.', '.hist', '.show'}
-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']
-}
-dt_config.skiplist = {
-    'scipy.special.sinc',
-    'scipy.misc.who',
-    'scipy.optimize.show_options'
-}
+```
+$ spin check-docs
 ```
 
-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.
+SciPy wraps `scipy-doctest` with custom `dev.py` commands:
+
+```
+$ python dev.py smoke-docs    # check docstrings
+$ python dev.py smoke-tutorials   # ReST user guide tutorials
+```
 
-By following these steps, you will be able to effectively use the SciPy Doctest pytest plugin for doctests in your Python projects.
 
-Happy testing!
 
 ## Rough edges and sharp bits
 
@@ -307,7 +322,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 ...
@@ -342,6 +357,19 @@ leads to
 - `scipy.linalg.det`, collected from `scipy/linalg/__init__.py`, is public.
 
 
+- *`pytest`'s assertion rewriting*
+
+In some rare cases you may need to either explicitly register the `scipy_doctest`
+package with the `pytest` assertion rewriting machinery, or ask it to avoid rewriting
+completely, via `pytest --assert=plain`.
+See [the `pytest documentation`](https://docs.pytest.org/en/7.1.x/how-to/assert.html)
+for more details.
+
+In general, rewriting assertions is not very useful for doctests, as the
+output on error is fixed by the doctest machinery anyway. Therefore, we believe
+adding `--assert=plain` is reasonable.
+
+
 ## Prior art and related work
 
 - `pytest` provides some limited floating-point aware `NumericLiteralChecker`.
@@ -351,20 +379,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.2.0 → scipy_doctest-1.4}/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.4/scipy_doctest/__init__.py

@@ -0,0 +1,22 @@
+"""
+Configurable, whitespace-insensitive, floating-point-aware doctest helpers.
+"""
+
+
+__version__ = "1.4"
+
+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.2.0 → scipy_doctest-1.4}/scipy_doctest/impl.py

@@ -40,6 +40,11 @@ class DTConfig:
     rtol : float
         Absolute and relative tolerances to check doctest examples with.
         Specifically, the check is ``np.allclose(want, got, atol=atol, rtol=rtol)``
+    strict_check : bool
+       Whether to check that dtypes match or rely on the lax definition of
+       equality of numpy objects. For instance, `3 == np.float64(3)`, but
+       dtypes do not match.
+       Default is False.
     optionflags : int
         doctest optionflags
         Default is ``NORMALIZE_WHITESPACE | ELLIPSIS | IGNORE_EXCEPTION_DETAIL``
@@ -91,6 +96,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,
@@ -99,6 +112,7 @@ class DTConfig:
                           rndm_markers=None,
                           atol=1e-8,
                           rtol=1e-2,
+                          strict_check=False,
                           # DTRunner configuration
                           optionflags=None,
                           # DTFinder/DTParser configuration
@@ -153,8 +167,8 @@ class DTConfig:
                             '#random', '#Random',
                             "# may vary"}
         self.rndm_markers = rndm_markers
-
         self.atol, self.rtol = atol, rtol
+        self.strict_check = strict_check
 
         ### DTRunner configuration ###
 
@@ -355,23 +369,35 @@ class DTChecker(doctest.OutputChecker):
             return False
 
         # ... and defer to numpy
+        strict = self.config.strict_check
         try:
-            return self._do_check(a_want, a_got)
+            return self._do_check(a_want, a_got, strict)
         except Exception:
             # heterog tuple, eg (1, np.array([1., 2.]))
             try:
-                return all(self._do_check(w, g) for w, g in zip_longest(a_want, a_got))
+                return all(
+                    self._do_check(w, g, strict) for w, g in zip_longest(a_want, a_got)
+                )
             except (TypeError, ValueError):
                 return False
 
-    def _do_check(self, want, got):
+    def _do_check(self, want, got, strict_check):
         # This should be done exactly as written to correctly handle all of
         # numpy-comparable objects, strings, and heterogeneous tuples
+
+        # NB: 3 == np.float64(3.0) but dtypes differ
+        if strict_check:
+            want_dtype = np.asarray(want).dtype
+            got_dtype = np.asarray(got).dtype
+            if want_dtype != got_dtype:
+                return False
+
         try:
             if want == got:
                 return True
         except Exception:
             pass
+
         with warnings.catch_warnings():
             # NumPy's ragged array deprecation of np.array([1, (2, 3)])
             warnings.simplefilter('ignore', VisibleDeprecationWarning)
@@ -506,6 +532,7 @@ class DTParser(doctest.DocTestParser):
         """
         stopwords = self.config.stopwords
         pseudocode = self.config.pseudocode
+        rndm_markers = self.config.rndm_markers
 
         SKIP = doctest.OPTIONFLAGS_BY_NAME['SKIP']
         keep_skipping_this_block = False
@@ -529,6 +556,11 @@ class DTParser(doctest.DocTestParser):
                 # NB: Could have just skipped it via `continue`.
                 example.options[SKIP] = True
 
+            if any(word in example.source for word in rndm_markers):
+                # Found a `# may vary`. Do not check the output (but do check
+                # that the source is valid python).
+                example.want += "  # _ignore\n"
+
             if any(word in example.source for word in stopwords):
                 # Found a stopword. Do not check the output (but do check
                 # that the source is valid python).

{scipy_doctest-1.2.0 → scipy_doctest-1.4}/scipy_doctest/tests/failure_cases.py

@@ -45,3 +45,11 @@ def tuple_and_list_2():
     >>> (0, 1, 2)
     [0, 1, 2]
     """
+
+
+def dtype_mismatch():
+    """
+    >>> import numpy as np
+    >>> 3.0
+    3
+    """

{scipy_doctest-1.2.0 → scipy_doctest-1.4}/scipy_doctest/tests/local_file_cases.py

@@ -3,7 +3,7 @@ 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']
+    'scipy_doctest.tests.local_file_cases.sio': ['octave_a.mat']
 }
 
 

{scipy_doctest-1.2.0 → scipy_doctest-1.4}/scipy_doctest/tests/test_pytest_configuration.py

@@ -49,11 +49,9 @@ def test_stopword_cases(pytester):
     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.
-    """
+    """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")

{scipy_doctest-1.2.0 → scipy_doctest-1.4}/scipy_doctest/tests/test_skipmarkers.py

@@ -161,8 +161,25 @@ class TestMayVary:
                                   filename='none', lineno=0)
 
         runner = DebugDTRunner()
-        with pytest.raises(doctest.DocTestFailure):
+        runner.run(test)
+
+        # one example tried, of which zero failed
+        assert runner.get_history() == {'may_vary_source': (0, 1)}
+
+    def test_may_vary_syntax_error(self):
+        # `# may vary` markers do not mask syntax errors, unlike `# doctest: +SKIP`
+        string = ">>> 1 += 2    # may vary\n"
+        string += "42\n"
+
+        parser = DTParser()
+        test = parser.get_doctest(string, globs={},
+                                  name='may_vary_err',
+                                  filename='none', lineno=0)
+
+        runner = DebugDTRunner()
+        with pytest.raises(Exception) as exc_info:
             runner.run(test)
+        assert exc_info.type == doctest.UnexpectedException
 
 
 string='''\

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

@@ -117,6 +117,16 @@ def test_tuple_and_list():
     assert res.failed == 2
 
 
+@pytest.mark.parametrize('strict, num_fails', [(True, 1), (False, 0)])
+class TestStrictDType:
+    def test_np_fix(self, strict, num_fails):
+        config = DTConfig(strict_check=strict)
+        res, _ = _testmod(failure_cases,
+                          strategy=[failure_cases.dtype_mismatch],
+                          config=config)
+        assert res.failed == num_fails
+
+
 class TestLocalFiles:
     def test_local_files(self):
         # A doctest tries to open a local file. Test that it works

scipy_doctest-1.2.0/scipy_doctest/__init__.py

@@ -1,12 +0,0 @@
-"""
-Doctests on steroids.
-
-Whitespace-insensitive, numpy-aware, floating-point-aware doctest helpers.
-"""
-
-
-__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
-