Added doctests (#207)

* Fix `pycodestyle` and `pydocstyle` compliance

* Docstring fixes

* Fixed an incorrect exception in `_Settings.__missing__`
* Fixed a number of incorrect Sphinx domains
* Clarified a few docstrings

* Enabled doctest

* Removed a redundant assignment

conftest.py

@@ -0,0 +1,5 @@
+"""A pytest ``conftest.py`` file."""
+
+import os
+
+collect_ignore = [os.path.join('src', 'qmflows', 'settings.py')]

docs/conf.py

@@ -40,6 +40,7 @@
     'sphinx.ext.githubpages',
     'sphinx.ext.autosummary',
     'sphinx.ext.napoleon',
+    'sphinx.ext.doctest',
     'nbsphinx',
     # Workaround for this issue: https://github.com/spatialaudio/nbsphinx/issues/24
     'IPython.sphinxext.ipython_console_highlighting'

setup.cfg

@@ -16,7 +16,7 @@ max-line-length = 100
 
 [tool:pytest]
 testpaths = src test
-addopts = --pycodestyle --pydocstyle --tb=short --cov --cov-report xml --cov-report term --cov-report html
+addopts = --pycodestyle --pydocstyle --tb=short --cov --doctest-modules --cov-report xml --cov-report term --cov-report html
 markers = slow: A marker for slow tests requiring external quantum-chemical packages.
 
 # Define `python setup.py build_sphinx`

src/qmflows/backports.py

@@ -30,11 +30,16 @@ class _NullContextBackup(AbstractContextManager):
     Used as a stand-in for a normal context manager, when a particular
     block of code is only sometimes used with a normal context manager:
 
+    .. testsetup:: python
+
+        >>> condition = False
+
     .. code:: python
 
-        >>> cm = optional_cm if condition else nullcontext()
-        >>> with cm:
-        ...     ...  # Perform operation, using optional_cm if condition is True
+        >>> cm = optional_cm if condition else nullcontext(1)
+        >>> with cm as f:
+        ...     print(f)
+        1
 
     """
 

src/qmflows/cp2k_utils.py

@@ -522,10 +522,10 @@ def prm_to_df(settings: MutableMapping) -> None:
         >>> print(type(s.lennard_jones))
         <class 'pandas.core.frame.DataFrame'>
 
-        >>> print(s)
-        lennard_jones:             param      unit   Cs   Cd    O    H
-                        epsilon  epsilon   kcalmol  1.0  2.0  3.0  4.0
-                        sigma      sigma  angstrom  1.0  2.0  3.0  4.0
+        >>> print(s)  # doctest: +NORMALIZE_WHITESPACE
+        lennard_jones:                param      unit   Cs   Cd    O    H
+                           epsilon  epsilon   kcalmol  1.0  2.0  3.0  4.0
+                           sigma      sigma  angstrom  1.0  2.0  3.0  4.0
 
 
     Parameters

src/qmflows/packages/package_wrapper.py

@@ -27,23 +27,30 @@
 
 For example:
 
+.. testsetup:: python
+
+    >>> from scm.plams import from_smiles
+
+    >>> mol = from_smiles('C')
+    >>> settings = Settings()
+
 .. code:: python
 
     >>> from scm.plams import AMSJob, Molecule, Settings
 
     >>> from qmflows import run, PackageWrapper
     >>> from qmflows.packages.package_wrapper import ResultWrapper
 
-    >>> mol = Molecule(...)
-    >>> settings = Settings(...)
+    >>> mol = Molecule(...)  # doctest: +SKIP
+    >>> settings = Settings(...)  # doctest: +SKIP
 
     >>> pkg = PackageWrapper(AMSJob)
     >>> job = pkg(settings, mol, name='amsjob')
-    >>> result: ResultWrapper = run(job, ...)
+    >>> result: ResultWrapper = run(job)
 
-    >>> energy = result.get_energy()  # Alias for AMSResults.get_energy()
-    >>> mol = result.get_molecule()  # Alias for AMSResults.get_molecule()
-    >>> freq = result.get_frequencies()  # Alias for AMSResults.get_frequencies()
+    >>> energy = result.get_energy()  # doctest: +SKIP
+    >>> mol = result.get_molecule()  # doctest: +SKIP
+    >>> freq = result.get_frequencies()  # doctest: +SKIP
 
 
 Index
@@ -144,7 +151,7 @@ class PackageWrapper(Package):
 
         >>> from scm.plams import ADFJob, AMSJob
 
-        >>> from qmflows PackageWrapper, run
+        >>> from qmflows import PackageWrapper, run
         >>> from qmflows.packages.package_wrapper import ResultWrapper
         >>> from qmflows.packages.SCM import ADF_Result
 
@@ -153,8 +160,8 @@ class PackageWrapper(Package):
         >>> pkg_ams = PackageWrapper(AMSJob)
 
         # End up with two different Result instances
-        >>> result_adf: ADF_Result = run(pkg_adf(...), ...)
-        >>> result_ams: ResultWrapper = run(pkg_ams(...), ...)
+        >>> result_adf: ADF_Result = run(pkg_adf(...), ...)  # doctest: +SKIP
+        >>> result_ams: ResultWrapper = run(pkg_ams(...), ...)  # doctest: +SKIP
 
     Attributes
     ----------

src/qmflows/packages/packages.py

@@ -108,10 +108,10 @@ def __getattr__(self, prop: str) -> Any:
 
         ..code:: python
 
-            >>> from qmflows.packages.packages import Results
+            >>> from qmflows.packages.packages import Result
 
-            >>> result = Result(...)
-            >>> dipole = result.dipole
+            >>> result = Result(...)  # doctest: +SKIP
+            >>> dipole = result.dipole  # doctest: +SKIP
 
         """
         is_private = prop.startswith('__') and prop.endswith('__')

src/qmflows/settings.py

@@ -12,9 +12,9 @@ class Settings(plams.core.settings.Settings, ):
     """A subclass of :class:`plams.Settings<scm.plams.core.settings.Settings>`.
 
     The difference with respect to plams' Settings are:
-    
+
     - :code:`settings['a.b']` is equivalent to :code:`settings['a']['b'] = settings.a.b`
-    - in :meth:`Settings.update`: :code:`settings.__block_replace = True` results in removal 
+    - in :meth:`Settings.update`: :code:`settings.__block_replace = True` results in removal
       of all existing key value pairs.
       ``__block_replace`` can be either in the updated settings or in the updating settings object.
     """
@@ -40,7 +40,7 @@ def __delitem__(self, name):
 
     def copy(self):
         """Create a deep(-ish) copy of this instance.
-        
+
         All nested settings instances embedded within *self* are copied recursively;
         all other objects set without copying.
         """

src/qmflows/test_utils.py

@@ -95,11 +95,11 @@ def delete_output(delete_db: Union[Callable, bool] = True,
         >>> from qmflows.test_utils import delete_output
 
         >>> @delete_output
-        >>> def test1(...):
+        ... def test1(*args, **kwargs):
         ...     ...
 
         >>> @delete_output(delete_db=True, delete_workdir=False)
-        >>> def test2(...):
+        ... def test2(*args, **kwargs):
         ...     ...
 
     Parameters

src/qmflows/utils.py

@@ -38,14 +38,18 @@ def to_runtime_error(func: Callable) -> Callable:
         ...     raise Exception('error')
 
         >>> @to_runtime_error
-        >>> def func2(settings, key, value, mol):
+        ... def func2(settings, key, value, mol):
         ...     raise Exception('error')
 
         >>> func1(None, 'func1', None, None)
-        Exception('error')
+        Traceback (most recent call last):
+          ...
+        Exception: error
 
-        >>> func1(None, 'func2', None, None)
-        Exception('"func2" section: error')
+        >>> func2(None, 'func2', None, None)
+        Traceback (most recent call last):
+          ...
+        RuntimeError: 'func2' section: error
 
     """
     @wraps(func)
@@ -71,18 +75,24 @@ def file_to_context(file: Union[int, PathLike, IO],
 
     Examples
     --------
+    .. testsetup:: python
+
+        >>> from pathlib import Path
+
+        >>> path_like = Path('test') / 'test_files' / 'mypy.ini'
+
     .. code:: python
 
         >>> from io import StringIO
 
-        >>> path_like = 'file_name.txt'
+        >>> path_like = 'file_name.txt'  # doctest: +SKIP
         >>> file_like = StringIO('this is a file-like object')
 
         >>> context1 = file_to_context(path_like)
         >>> context2 = file_to_context(file_like)
 
-        >>> with context1 as f1, with context2 as f2:
-        ...     ... # insert operations here
+        >>> with context1 as f1, context2 as f2:
+        ...     pass # insert operations here
 
 
     Parameters
@@ -174,7 +184,7 @@ class InitRestart(AbstractContextManager):
     .. code:: python
 
         >>> path = "path/to/my/workdir"
-        >>> with InitRestart(path):
+        >>> with InitRestart(path):  # doctest: +SKIP
         ...     ...  # Run any PLAMS Jobs here