scikit-base 0.3.0__py3-none-any.whl

skbase/testing/utils/__init__.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+"""Utilities for the test framework."""
+from typing import List
+
+__all__: List[str] = []

skbase/testing/utils/_conditional_fixtures.py

@@ -0,0 +1,202 @@
+# -*- coding: utf-8 -*-
+"""Testing utility for easy generation of conditional fixtures in pytest_generate_tests.
+
+Exports create_conditional_fixtures_and_names utility
+"""
+from copy import deepcopy
+from typing import Callable, Dict, List
+
+from skbase._exceptions import FixtureGenerationError
+from skbase.utils._nested_iter import _remove_single
+from skbase.validate._types import _check_list_of_str
+
+__author__: List[str] = ["fkiraly"]
+__all__: List[str] = ["create_conditional_fixtures_and_names"]
+
+
+def create_conditional_fixtures_and_names(
+    test_name: str,
+    fixture_vars: List[str],
+    generator_dict: Dict[str, Callable],
+    fixture_sequence: List[str] = None,
+    raise_exceptions: bool = False,
+    deepcopy_fixtures: bool = False,
+):
+    """Create conditional fixtures for pytest_generate_tests.
+
+    Creates arguments for pytest.fixture.parameterize,
+        using conditional fixture generation functions in generator_dict.
+
+    Example: we want to loop over two fixture variables, "number" and "multiples"
+        "number" are integers from 1 to 10,
+        "multiples" are multiples of "number" up to "number"-squared
+        we then write a generator_dict with two entries
+        generator_dict["number"] is a function (test_name, **kwargs) -> list
+            that returns [1, 2, ..., 10]
+        generator_dict["multiples"] is a function (test_name, number, **kwargs) -> list
+            that returns [number, 2* number, ..., number*number]
+
+    This function automatically creates the inputs for pytest.mark.parameterize
+        fixture_param_str = "number,multiples"
+        fixture_prod = [(1, 1), (2, 2), (2, 4), (3, 3), (3, 6), ...]
+        fixture_names = ["1-1", "2-2", "2-4", "3-3", "3-6", ...]
+
+    Parameters
+    ----------
+    test_name : str, name of the test, from pytest_generate_tests
+    fixture_vars : list of str
+        fixture variable names used in parameterization of tests
+    generator_dict : dict of generator functions
+        keys are possible str in fixture_vars, expected signature is
+            (test_name: str, **kwargs) -> fixtures: Listof[object], or
+                (returning only fixtures)
+            (test_name: str, **kwargs) -> fixtures, fixture_names: Listof[object]
+                (returning fixture names as well as fixtures)
+        generator_dict[my_variable] can take arguments with names
+            in fixture_sequence to the left of my_variable
+            it should return a list of fixtures for my_variable
+            under the assumption that arguments have given values
+    fixture_sequence : list of str, optional, default = None
+        used in prioritizing conditional generators, sequentially (see above)
+    raise_exceptions : bool, optional, default = False
+        whether fixture generation errors or other Exceptions are raised
+        if False, exceptions are returned instead of fixtures
+    deepcopy_fixtures : bool. optional, default = False
+        whether returned fixture list in fixture_prod are deecopy-independent
+        if False, identical list/tuple elements will be identical by reference
+        if True, identical elements will be identical by value but no by reference
+        "elements" refer to fixture[i] as described below, in fixture_prod
+
+    Returns
+    -------
+    fixture_param_str : str, string to use in pytest.fixture.parameterize
+        this is strings in "fixture_vars" concatenated, separated by ","
+    fixture_prod : list of tuples, fixtures to use in pytest.fixture.parameterize
+        fixture tuples, generated according to the following conditional rule:
+            let fixture_vars = [fixture_var1, fixture_var2, ..., fixture_varN]
+            all fixtures are obtained as following:
+                for i in 1 to N
+                    pick fixture[i] any element of generator_dict[fixture_vari](
+                        test_name,
+                        fixture_var1 = fixture[1], ...,
+                        fixture_var(i-1) = fixture[i-1],
+                    )
+            return (fixture[1], fixture[2], ..., fixture[N])
+        if deepcopy_fixtures = False, identical fixture[i] are identical by reference
+        if deepcopy_fixtures = True, identical fixture[i] are not identical references
+    fixture_names : list of str, fixture ids to use in pytest.fixture.parameterize
+        fixture names, generated according to the following conditional rule:
+            let fixture_vars = [fixture_var1, fixture_var2, ..., fixture_varN]
+            all fixtures names are obtained as following:
+                for i in 1 to N
+                    pick fixture_str_pt[i] any element of generator_dict[fixture_vari](
+                        test_name,
+                        fixture_var1 = fixture[1], ...,
+                        fixture_var(i-1) = fixture[i-1],
+                    ), second return is exists; otherwise str(first return)
+            return "fixture_str_pt[1]-fixture_str_pt[2]-...-fixture_str_pt[N]"
+        fixture names correspond to fixtures with the same indices at picks (from lists)
+    """
+    fixture_vars = _check_list_of_str(fixture_vars, name="fixture_vars")
+    fixture_vars = [var for var in fixture_vars if var in generator_dict.keys()]
+
+    # order fixture_vars according to fixture_sequence if provided
+    if fixture_sequence is not None:
+        fixture_sequence = _check_list_of_str(fixture_sequence, name="fixture_sequence")
+        ordered_fixture_vars = []
+        for fixture_var_name in fixture_sequence:
+            if fixture_var_name in fixture_vars:
+                ordered_fixture_vars += [fixture_var_name]
+        fixture_vars = ordered_fixture_vars
+
+    def get_fixtures(fixture_var, **kwargs):
+        """Call fixture generator from generator_dict, return fixture list.
+
+        Light wrapper around calls to generator_dict[key] functions that generate
+            conditional fixtures. get_fixtures adds default string names to the return
+            if generator_dict[key] does not return them.
+
+        Parameters
+        ----------
+        fixture_var : str, name of fixture variable
+        kwargs : key-value pairs, keys = names of previous fixture variables
+        test_name : str, from local scope
+            name of test for which fixtures are generated
+
+        Returns
+        -------
+        fixture_prod : list of objects or one-element list with FixtureGenerationError
+            fixtures for fixture_var for test_name, conditional on fixtures in kwargs
+            if call to generator_dict[fixture_var] fails, returns list with error
+        fixture_names : list of string, same length as fixture_prod
+            i-th element is a string name for i-th element of fixture_prod
+            if 2nd arg is returned by generator_dict, then 1:1 copy of that argument
+            if no 2nd arg is returned by generator_dict, then str(fixture_prod[i])
+            if fixture_prod is list with error, then string is Error:fixture_var
+        """
+        try:
+            res = generator_dict[fixture_var](test_name, **kwargs)
+            if isinstance(res, tuple) and len(res) == 2:
+                fixture_prod = res[0]
+                fixture_names = res[1]
+            else:
+                fixture_prod = res
+                fixture_names = [str(x) for x in res]
+        except Exception as err:
+            error = FixtureGenerationError(fixture_name=fixture_var, err=err)
+            if raise_exceptions:
+                raise error
+            fixture_prod = [error]
+            fixture_names = [f"Error:{fixture_var}"]
+
+        return fixture_prod, fixture_names
+
+    fixture_prod = [()]
+    fixture_names = [""]
+
+    # we loop over fixture_vars, incrementally going through conditionals
+    for i, fixture_var in enumerate(fixture_vars):
+        old_fixture_vars = fixture_vars[0:i]
+
+        # then take successive left products
+        new_fixture_prod = []
+        new_fixture_names = []
+
+        for j, fixture in enumerate(fixture_prod):
+            # retrieve kwargs corresponding to old fixture values
+            fixture_name = fixture_names[j]
+            if i == 0:
+                kwargs = {}
+            else:
+                kwargs = dict(zip(old_fixture_vars, fixture))
+            # retrieve conditional fixtures, conditional on fixture values in kwargs
+            new_fixtures, new_fixture_names_r = get_fixtures(fixture_var, **kwargs)
+            # new fixture values are concatenation/product of old values plus new
+            new_fixture_prod += [
+                fixture + (new_fixture,) for new_fixture in new_fixtures
+            ]
+            # new fixture name is concatenation of name so far and "dash-new name"
+            #   if the new name is empty string, don't add a dash
+            if len(new_fixture_names_r) > 0 and new_fixture_names_r[0] != "":
+                new_fixture_names_r = [f"-{x}" for x in new_fixture_names_r]
+            new_fixture_names += [f"{fixture_name}{x}" for x in new_fixture_names_r]
+
+        fixture_prod = new_fixture_prod
+        fixture_names = new_fixture_names
+
+    # due to the concatenation, fixture names all start leading "-" which is removed
+    fixture_names = [x[1:] for x in fixture_names]
+
+    # in pytest convention, variable strings are separated by comma
+    fixture_param_str = ",".join(fixture_vars)
+
+    # we need to remove the tuple bracket from singleton
+    #   in pytest convention, only multiple variables (2 or more) are tuples
+    fixture_prod = [_remove_single(x) for x in fixture_prod]
+
+    # if deepcopy_fixtures = True:
+    # we run deepcopy on every element of fixture_prod to make them independent
+    if deepcopy_fixtures:
+        fixture_prod = [deepcopy(x) for x in fixture_prod]
+
+    return fixture_param_str, fixture_prod, fixture_names

skbase/testing/utils/_dependencies.py

@@ -0,0 +1,254 @@
+# -*- coding: utf-8 -*-
+"""Utility to check soft dependency imports, and raise warnings or errors."""
+import io
+import sys
+import warnings
+from importlib import import_module
+from inspect import isclass
+from typing import List
+
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+
+__author__: List[str] = ["fkiraly", "mloning"]
+
+
+def _check_soft_dependencies(
+    *packages,
+    package_import_alias=None,
+    severity="error",
+    obj=None,
+    suppress_import_stdout=False,
+):
+    """Check if required soft dependencies are installed and raise error or warning.
+
+    Parameters
+    ----------
+    packages : str or list/tuple of str, or length-1-tuple containing list/tuple of str
+        str should be package names and/or package version specifications to check.
+        Each str must be a PEP 440 compatibe specifier string, for a single package.
+        For instance, the PEP 440 compatible package name such as "pandas";
+        or a package requirement specifier string such as "pandas>1.2.3".
+        arg can be str, kwargs tuple, or tuple/list of str, following calls are valid:
+        `_check_soft_dependencies("package1")`
+        `_check_soft_dependencies("package1", "package2")`
+        `_check_soft_dependencies(("package1", "package2"))`
+        `_check_soft_dependencies(["package1", "package2"])`
+    package_import_alias : dict with str keys and values, optional, default=empty
+        key-value pairs are package name, import name
+        import name is str used in python import, i.e., from import_name import ...
+        should be provided if import name differs from package name
+    severity : str, "error" (default), "warning", "none"
+        behaviour for raising errors or warnings
+        "error" - raises a `ModuleNotFoundException` if one of packages is not installed
+        "warning" - raises a warning if one of packages is not installed
+            function returns False if one of packages is not installed, otherwise True
+        "none" - does not raise exception or warning
+            function returns False if one of packages is not installed, otherwise True
+    obj : python class, object, str, or None, default=None
+        if self is passed here when _check_soft_dependencies is called within __init__,
+        or a class is passed when it is called at the start of a single-class module,
+        the error message is more informative and will refer to the class/object;
+        if str is passed, will be used as name of the class/object or module
+    suppress_import_stdout : bool, optional. Default=False
+        whether to suppress stdout printout upon import.
+
+    Raises
+    ------
+    ModuleNotFoundError
+        error with informative message, asking to install required soft dependencies
+
+    Returns
+    -------
+    boolean - whether all packages are installed, only if no exception is raised
+    """
+    if len(packages) == 1 and isinstance(packages[0], (tuple, list)):
+        packages = packages[0]
+    if not all(isinstance(x, str) for x in packages):
+        raise TypeError("packages must be str or tuple of str")
+
+    if package_import_alias is None:
+        package_import_alias = {}
+    msg = "package_import_alias must be a dict with str keys and values"
+    if not isinstance(package_import_alias, dict):
+        raise TypeError(msg)
+    if not all(isinstance(x, str) for x in package_import_alias.keys()):
+        raise TypeError(msg)
+    if not all(isinstance(x, str) for x in package_import_alias.values()):
+        raise TypeError(msg)
+
+    if obj is None:
+        class_name = "This functionality"
+    elif not isclass(obj):
+        class_name = type(obj).__name__
+    elif isclass(obj):
+        class_name = obj.__name__
+    elif isinstance(obj, str):
+        class_name = obj
+    else:
+        raise TypeError("obj must be a class, an object, a str, or None")
+
+    for package in packages:
+
+        try:
+            req = Requirement(package)
+        except InvalidRequirement:
+            msg_version = (
+                f"wrong format for package requirement string, "
+                f'must be PEP 440 compatible requirement string, e.g., "pandas"'
+                f' or "pandas>1.1", but found "{package}"'
+            )
+            raise InvalidRequirement(msg_version)
+
+        package_name = req.name
+        package_version_req = req.specifier
+
+        # determine the package import
+        if package_name in package_import_alias.keys():
+            package_import_name = package_import_alias[package_name]
+        else:
+            package_import_name = package_name
+        # attempt import - if not possible, we know we need to raise warning/exception
+        try:
+            if suppress_import_stdout:
+                # setup text trap, import, then restore
+                sys.stdout = io.StringIO()
+                pkg_ref = import_module(package_import_name)
+                sys.stdout = sys.__stdout__
+            else:
+                pkg_ref = import_module(package_import_name)
+        # if package cannot be imported, make the user aware of installation requirement
+        except ModuleNotFoundError as e:
+            msg = (
+                f"{e}. "
+                f"{class_name} requires package '{package}' to be present "
+                f"in the python environment, but '{package}' was not found. "
+            )
+            if obj is not None:
+                msg = msg + (
+                    f"'{package}' is a dependency of {class_name} and required "
+                    f"to construct it. "
+                )
+            msg = msg + (
+                f"Please run: `pip install {package}` to "
+                f"install the {package} package. "
+            )
+
+            if severity == "error":
+                raise ModuleNotFoundError(msg) from e
+            elif severity == "warning":
+                warnings.warn(msg)
+                return False
+            elif severity == "none":
+                return False
+            else:
+                raise RuntimeError(
+                    "Error in calling _check_soft_dependencies, severity "
+                    'argument must be "error", "warning", or "none",'
+                    f'found "{severity}".'
+                )
+
+        # now we check compatibility with the version specifier if non-empty
+        if package_version_req != SpecifierSet(""):
+            pkg_env_version = pkg_ref.__version__
+
+            msg = (
+                f"{class_name} requires package '{package}' to be present "
+                f"in the python environment, with version {package_version_req}, "
+                f"but incompatible version {pkg_env_version} was found. "
+            )
+            if obj is not None:
+                msg = msg + (
+                    f"'{package}', with version {package_version_req},"
+                    f"is a dependency of {class_name} and required to construct it. "
+                )
+
+            # raise error/warning or return False if version is incompatible
+            if pkg_env_version not in package_version_req:
+                if severity == "error":
+                    raise ModuleNotFoundError(msg)
+                elif severity == "warning":
+                    warnings.warn(msg)
+                elif severity == "none":
+                    return False
+                else:
+                    raise RuntimeError(
+                        "Error in calling _check_soft_dependencies, severity argument"
+                        f' must be "error", "warning", or "none", found "{severity}".'
+                    )
+
+    # if package can be imported and no version issue was caught for any string,
+    # then obj is compatible with the requirements and we should return True
+    return True
+
+
+def _check_python_version(obj, package=None, msg=None, severity="error"):
+    """Check if system python version is compatible with requirements of obj.
+
+    Parameters
+    ----------
+    obj : BaseObject descendant
+        used to check python version
+    package : str, default = None
+        if given, will be used in error message as package name
+    msg : str, optional, default = default message (msg below)
+        error message to be returned in the `ModuleNotFoundError`, overrides default
+    severity : str, "error" (default), "warning", or "none"
+        whether the check should raise an error, a warning, or nothing
+
+    Returns
+    -------
+    compatible : bool, whether obj is compatible with system python version
+        check is using the python_version tag of obj
+
+    Raises
+    ------
+    ModuleNotFoundError
+        User friendly error if obj has python_version tag that is
+        incompatible with the system python version. If package is given,
+        error message gives package as the reason for incompatibility.
+    """
+    est_specifier_tag = obj.get_class_tag("python_version", tag_value_default="None")
+    if est_specifier_tag in ["None", None]:
+        return True
+
+    try:
+        est_specifier = SpecifierSet(est_specifier_tag)
+    except InvalidSpecifier:
+        msg_version = (
+            f"wrong format for python_version tag, "
+            f'must be PEP 440 compatible specifier string, e.g., "<3.9, >= 3.6.3",'
+            f' but found "{est_specifier_tag}"'
+        )
+        raise InvalidSpecifier(msg_version)
+
+    # python sys version, e.g., "3.8.12"
+    sys_version = sys.version.split(" ")[0]
+
+    if sys_version in est_specifier:
+        return True
+    # now we know that est_version is not compatible with sys_version
+
+    if not isinstance(msg, str):
+        msg = (
+            f"{type(obj).__name__} requires python version to be {est_specifier},"
+            f" but system python version is {sys.version}."
+        )
+
+        if package is not None:
+            msg += (
+                f" This is due to python version requirements of the {package} package."
+            )
+
+    if severity == "error":
+        raise ModuleNotFoundError(msg)
+    elif severity == "warning":
+        warnings.warn(msg)
+    elif severity == "none":
+        return False
+    else:
+        raise RuntimeError(
+            "Error in calling _check_python_version, severity "
+            f'argument must be "error", "warning", or "none", found "{severity}".'
+        )
+    return True