pytest-regtest 2.2.0a2__py2.py3-none-any.whl → 2.3.0__py2.py3-none-any.whl

pytest_regtest/register_third_party_handlers.py

@@ -1,20 +1,4 @@
-try:
-    import numpy as np  # noqa: F401
-
-    HAS_NUMPY = True
-except ImportError:
-    HAS_NUMPY = False
-
-try:
-    import pandas as pd  # noqa: F401
-
-    HAS_PANDAS = True
-except ImportError:
-    HAS_PANDAS = False
-
-
-if HAS_PANDAS and HAS_NUMPY:
-
+def register_pandas_handler():
     def is_dataframe(obj):
         try:
             import pandas as pd
@@ -24,12 +8,12 @@ if HAS_PANDAS and HAS_NUMPY:
             return False
 
     from .pandas_handler import DataFrameHandler
-    from .snapshot_handler import snapshot_handlers
+    from .snapshot_handler import SnapshotHandlerRegistry
 
-    snapshot_handlers.append((is_dataframe, DataFrameHandler))
+    SnapshotHandlerRegistry.add_handler(is_dataframe, DataFrameHandler)
 
-if HAS_NUMPY:
 
+def register_numpy_handler():
     def is_numpy(obj):
         try:
             import numpy as np
@@ -39,6 +23,21 @@ if HAS_NUMPY:
             return False
 
     from .numpy_handler import NumpyHandler
-    from .snapshot_handler import snapshot_handlers
+    from .snapshot_handler import SnapshotHandlerRegistry
+
+    SnapshotHandlerRegistry.add_handler(is_numpy, NumpyHandler)
+
+
+def register_polars_handler():
+    def is_polars(obj):
+        try:
+            import polars as pl
+
+            return isinstance(obj, pl.DataFrame)
+        except ImportError:
+            return False
+
+    from .polars_handler import PolarsHandler
+    from .snapshot_handler import SnapshotHandlerRegistry
 
-    snapshot_handlers.append((is_numpy, NumpyHandler))
+    SnapshotHandlerRegistry.add_handler(is_polars, PolarsHandler)

pytest_regtest/snapshot_handler.py

@@ -1,42 +1,154 @@
 import abc
 import difflib
-import io
 import os
 import pickle
+import pprint
 from collections.abc import Callable
-from pprint import pprint
-from typing import Any, Type, Union
+from typing import Any, Union
 
 import pytest
 
 
 class BaseSnapshotHandler(abc.ABC):
+    """
+    Abstract base class to implement snapshot handlers.
+    """
+
+    @abc.abstractmethod
     def __init__(
-        self,
         handler_options: dict[str, Any],
-        pytest_config: Type[pytest.Config],
+        pytest_config: type[pytest.Config],
         tw: int,
-    ) -> None: ...
+    ) -> None:
+        """
+        This method is called within `snapshot.check` to configure the handler.
+
+        Parameters:
+                handler_options: Keyword arguments from `shapshot.check` call
+                pytest_config: `pytest` config object.
+                tw: Terminal width.
+        """
 
     @abc.abstractmethod
-    def save(self, folder: Union[str, os.PathLike], obj: Any) -> None: ...
+    def save(self, folder: Union[str, os.PathLike], obj: Any) -> None:
+        """
+        This method is called when a snapshot is reset, and a subclass must store the
+        given object in the given folder. How this folder is managed internally is
+        entirely up to the snapshot handler. It can be a single file, or a complex
+        structure of multiple files and sub-folders.
+
+
+        Parameters:
+                folder: Path to the folder. The folder exists already when this
+                        method is called.
+                obj: The object from the `snapshot.check` call.
+        """
 
     @abc.abstractmethod
-    def load(self, folder: Union[str, os.PathLike]) -> Any: ...
+    def load(self, folder: Union[str, os.PathLike]) -> Any:
+        """
+        This method loads an existing snapshot from the given folder and must
+        be consistent with the `save` method.
+
+        Parameters:
+                folder: Path to the folder. The folder exists already when this
+                        method is called.
+
+        Returns:
+               The loaded object.
+        """
 
     @abc.abstractmethod
-    def show(self, obj: Any) -> list[str]: ...
+    def show(self, obj: Any) -> list[str]:
+        """
+        This method returns a line wise textual representation of the given object.
+
+        Parameters:
+                obj: The object the snapshot handler is managing.
+
+        Returns:
+                List of strings.
+        """
 
     @abc.abstractmethod
-    def compare(self, current_obj: Any, recorded_obj: Any) -> bool: ...
+    def compare(self, current_obj: Any, recorded_obj: Any) -> bool:
+        """
+        The method compares if the current object from the
+        `snapshot.check` call and the object loaded with the `load`
+        method are considered to be the same. If this returns `True`
+        the `snapshot.check` call will pass.
+
+        Parameters:
+                current_obj: The object the snapshot handler receiving from
+                            `snapshot.check`.
+                recorded_obj: The object the snapshot handler is loading with
+                        the `load` method.
+
+        Returns:
+                Boolean value which decides is the `snapshot.check` call will pass.
+        """
 
     @abc.abstractmethod
     def show_differences(
         self, current_obj: Any, recorded_obj: Any, has_markup: bool
-    ) -> list[str]: ...
-
-
-snapshot_handlers: list[tuple[Callable[[Any], bool]]] = []
+    ) -> list[str]:
+        """
+        The method shows differences between the object from the
+        `snapshot.check` call and the object loaded with the `load`
+        method.
+
+        Parameters:
+                current_obj: The object the snapshot handler receiving from
+                            `snapshot.check`.
+                recorded_obj: The object the snapshot handler is loading with
+                        the `load` method.
+                has_markup: Indicates if the tests run within a terminal and
+                        the method can use color output in case `has_markup` is
+                        `True`.
+
+        Returns:
+                List of strings to describe the differences.
+        """
+
+
+class SnapshotHandlerRegistry:
+    """
+    This class serves as a registry for the builtin snapshot handlers
+    and can be used to add more handlers for particular data types.
+    """
+
+    _snapshot_handlers: list[tuple[Callable[[Any], bool]]] = []
+
+    @classmethod
+    def add_handler(
+        clz,
+        check_function: Callable[[Any], bool],
+        handler_class: type[BaseSnapshotHandler],
+    ):
+        """Add a handler.
+
+        Parameters:
+                check_function: A function which takes an object and returns `True`
+                                if the `handler_class` argument should be
+                                used for the given object.
+        """
+
+        clz._snapshot_handlers.append((check_function, handler_class))
+
+    @classmethod
+    def get_handler(clz, obj: Any) -> BaseSnapshotHandler:
+        """Find and initialize handler for the given object.
+
+        Parameters:
+            obj: The object for which we try to find a handler.
+
+        Returns:
+            An instance of the handler or `None` if no appropriate handler was found.
+        """
+        for check_function, handler in clz._snapshot_handlers:
+            if check_function(obj):
+                return handler
+        return None
 
 
 class PythonObjectHandler(BaseSnapshotHandler):
@@ -52,9 +164,7 @@ class PythonObjectHandler(BaseSnapshotHandler):
             return pickle.load(fh)
 
     def show(self, obj):
-        stream = io.StringIO()
-        pprint(obj, stream=stream, compact=self.compact)
-        return stream.getvalue().splitlines()
+        return pprint.pformat(obj, compact=self.compact).splitlines()
 
     def compare(self, current_obj, recorded_obj):
         return recorded_obj == current_obj
@@ -71,9 +181,8 @@ class PythonObjectHandler(BaseSnapshotHandler):
         )
 
 
-snapshot_handlers.append(
-    (
+def register_python_object_handler():
+    SnapshotHandlerRegistry.add_handler(
         lambda obj: isinstance(obj, (int, float, str, list, tuple, dict, set)),
         PythonObjectHandler,
-    ),
-)
+    )

pytest_regtest-2.3.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.3
+Name: pytest-regtest
+Version: 2.3.0
+Summary: pytest plugin for snapshot regression testing
+Project-URL: Source, https://gitlab.com/uweschmitt/pytest-regtest
+Project-URL: Documentation, https://pytest-regtest.readthedocs.org
+Author-email: Uwe Schmitt <uwe.schmitt@id.ethz.ch>
+License: MIT License
+License-File: LICENSE.txt
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: pytest>7.2
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: jinja2-cli; extra == 'dev'
+Requires-Dist: mistletoe; extra == 'dev'
+Requires-Dist: mkdocs; extra == 'dev'
+Requires-Dist: mkdocs-awesome-pages-plugin; extra == 'dev'
+Requires-Dist: mkdocs-material; extra == 'dev'
+Requires-Dist: mkdocstrings[python]; extra == 'dev'
+Requires-Dist: numpy; extra == 'dev'
+Requires-Dist: numpy>=2.1.1; extra == 'dev'
+Requires-Dist: pandas; extra == 'dev'
+Requires-Dist: pandas>=2.2.3; extra == 'dev'
+Requires-Dist: polars>=1.9.0; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Requires-Dist: wheel; extra == 'dev'
+Description-Content-Type: text/markdown
+
+![](https://gitlab.com/uweschmitt/pytest-regtest/badges/main/pipeline.svg)
+![](https://gitlab.com/uweschmitt/pytest-regtest/badges/main/coverage.svg?job=coverage)
+
+
+The full documentatin for this package are available at
+https://pytest-regtest.readthedocs.org
+
+# About
+
+## Introduction
+
+`pytest-regtest` is a plugin for [pytest](https://pytest.org) to implement
+**regression testing**.
+
+Unlike [functional testing](https://en.wikipedia.org/wiki/Functional_testing),
+[regression testing](https://en.wikipedia.org/wiki/Regression_testing)
+does not test whether the software produces the correct
+results, but whether it behaves as it did before changes were introduced.
+
+More specifically, `pytest-regtest` provides **snapshot testing**, which
+implements regression testing by recording data within a test function
+and comparing this recorded output to a previously recorded reference
+output.
+
+
+## Installation
+
+To install and activate this plugin execute:
+
+    $ pip install pytest-regtest
+
+
+!!! note
+
+    `pyteset-regtest` offers some functionalities which are tailored
+     for `NumPy`, `pandas` and `polars`. These depencies are not
+     installed if you install `pytest-regtest`. In case you are using
+     e.g. `NumPy` snapshots, we assume that your productive code (the
+     code under test) uses `NumPy` and thus should be part of the setup
+     of your project.
+
+
+## Use case 1: Changing code with no or little testing setup yet
+If you're working with code that has little or no unit testing, you
+can use regression testing to ensure that your changes don't break or
+alter previous results.
+
+**Example**:
+This can be useful when working with data analysis scripts, which often
+start as one long script and then are restructured into different
+functions as they evolve.
+
+
+## Use case 2:  Testing complex data
+If a unit tests contains many `assert` statements to check a complex
+data structure you can use regression tests instead.
+
+**Example**: To test code which ingests data into a database one can
+use regression tests on textual database dumps.
+
+## Use case 3: Testing NumPy arrays or pandas data frames
+
+If your code generates numerical results, such as `NumPy` arrays,
+`pandas` or `polars` data frames, you can use `pytest-regtest` to simply record such
+results and test them later, taking into account relative and absolute
+tolerances.
+
+
+**Example**:
+A function creates a 10 x 10 matrix. Either you have to write 100
+assert statements or you use summary statistics to test your result.
+In both cases, you may get little debugging information if a test
+fails.

pytest_regtest-2.3.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pytest_regtest/__init__.py,sha256=q3wEEi3ZZXaN5CXc0jKCeupbAl73t64Fz1pFNcYYPYo,2536
+pytest_regtest/numpy_handler.py,sha256=hKrVY9dId-45rUR_83w9jbUWgUhd0ABk8uLbOhgm0IM,7173
+pytest_regtest/pandas_handler.py,sha256=7vKaHyODcKMltgn9MbbbL1FsOBQK994dEY5fVlDoQ1g,4528
+pytest_regtest/polars_handler.py,sha256=B1CFNz0L96W8ktFMAT_j13q7nJZVN8ug402ILJjuBZA,3771
+pytest_regtest/pytest_regtest.py,sha256=umtd97AIpY4FpaYJCd741mTlJbrToWkUfrkoKCvHDAE,22135
+pytest_regtest/register_third_party_handlers.py,sha256=mfmcyeMKuxFykkKLO7T1Tz5RPitn1pKLYRM7B9lA1Kg,1132
+pytest_regtest/snapshot_handler.py,sha256=5q1oMisifbQ_i8LCSPsD1OxPVEHVUIWwZeEDcZcBNDI,6036
+pytest_regtest/utils.py,sha256=2jYTlV_qL5hH6FCeg7T1HJJvKual-Kux2scJ9_aB1lY,811
+pytest_regtest-2.3.0.dist-info/METADATA,sha256=AJQuXnr5Dqc2mcGI5zdXdOoxRs227YIa7owdSFY2SQU,4097
+pytest_regtest-2.3.0.dist-info/WHEEL,sha256=fl6v0VwpzfGBVsGtkAkhILUlJxROXbA3HvRL6Fe3140,105
+pytest_regtest-2.3.0.dist-info/entry_points.txt,sha256=4VuIhXeMGhDo0ATbaUfyjND0atofmZjV_P-o6_uEk2s,36
+pytest_regtest-2.3.0.dist-info/licenses/LICENSE.txt,sha256=Tue36uAzpW79-9WAqzkwPhsDDVd1X-VWUmdZ0MfGYvk,1068
+pytest_regtest-2.3.0.dist-info/RECORD,,