polars-runtime-compat 1.34.0b2__cp39-abi3-win_arm64.whl

polars/testing/asserts/series.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import contextlib
+from typing import Any
+
+from polars._utils.deprecation import deprecate_renamed_parameter
+from polars.series import Series
+from polars.testing.asserts.utils import raise_assertion_error
+
+with contextlib.suppress(ImportError):  # Module not available when building docs
+    from polars._plr import assert_series_equal_py
+
+
+def _assert_correct_input_type(left: Any, right: Any) -> bool:
+    __tracebackhide__ = True
+
+    if not (isinstance(left, Series) and isinstance(right, Series)):
+        raise_assertion_error(
+            "inputs",
+            "unexpected input types",
+            type(left).__name__,
+            type(right).__name__,
+        )
+    return True
+
+
+@deprecate_renamed_parameter("check_dtype", "check_dtypes", version="0.20.31")
+@deprecate_renamed_parameter("rtol", "rel_tol", version="1.32.3")
+@deprecate_renamed_parameter("atol", "abs_tol", version="1.32.3")
+def assert_series_equal(
+    left: Series,
+    right: Series,
+    *,
+    check_dtypes: bool = True,
+    check_names: bool = True,
+    check_order: bool = True,
+    check_exact: bool = False,
+    rel_tol: float = 1e-5,
+    abs_tol: float = 1e-8,
+    categorical_as_str: bool = False,
+) -> None:
+    """
+    Assert that the left and right Series are equal.
+
+    Raises a detailed `AssertionError` if the Series differ.
+    This function is intended for use in unit tests.
+
+    .. versionchanged:: 0.20.31
+        The `check_dtype` parameter was renamed `check_dtypes`.
+
+    .. versionchanged:: 1.32.3
+        The `rtol` and `atol` parameters were renamed to `rel_tol` and `abs_tol`,
+        respectively.
+
+    Parameters
+    ----------
+    left
+        The first Series to compare.
+    right
+        The second Series to compare.
+    check_dtypes
+        Requires data types to match.
+    check_names
+        Requires names to match.
+    check_order
+        Requires elements to appear in the same order.
+    check_exact
+        Requires float values to match exactly. If set to `False`, values are considered
+        equal when within tolerance of each other (see `rel_tol` and `abs_tol`).
+        Only affects columns with a Float data type.
+    rel_tol
+        Relative tolerance for inexact checking, given as a fraction of the values in
+        `right`.
+    abs_tol
+        Absolute tolerance for inexact checking.
+    categorical_as_str
+        Cast categorical columns to string before comparing. Enabling this helps
+        compare columns that do not share the same string cache.
+
+    See Also
+    --------
+    assert_frame_equal
+    assert_series_not_equal
+
+    Notes
+    -----
+    When using pytest, it may be worthwhile to shorten Python traceback printing
+    by passing `--tb=short`. The default mode tends to be unhelpfully verbose.
+    More information in the
+    `pytest docs <https://docs.pytest.org/en/latest/how-to/output.html#modifying-python-traceback-printing>`_.
+
+    Examples
+    --------
+    >>> from polars.testing import assert_series_equal
+    >>> s1 = pl.Series([1, 2, 3])
+    >>> s2 = pl.Series([1, 5, 3])
+    >>> assert_series_equal(s1, s2)
+    Traceback (most recent call last):
+    ...
+    AssertionError: Series are different (exact value mismatch)
+    [left]: shape: (3,)
+    Series: '' [i64]
+    [
+        1
+        2
+        3
+    ]
+    [right]: shape: (3,)
+    Series: '' [i64]
+    [
+        1
+        5
+        3
+    ]
+    """
+    __tracebackhide__ = True
+
+    _assert_correct_input_type(left, right)
+
+    assert_series_equal_py(
+        left._s,
+        right._s,
+        check_dtypes=check_dtypes,
+        check_names=check_names,
+        check_order=check_order,
+        check_exact=check_exact,
+        rel_tol=rel_tol,
+        abs_tol=abs_tol,
+        categorical_as_str=categorical_as_str,
+    )
+
+
+@deprecate_renamed_parameter("check_dtype", "check_dtypes", version="0.20.31")
+@deprecate_renamed_parameter("rtol", "rel_tol", version="1.32.3")
+@deprecate_renamed_parameter("atol", "abs_tol", version="1.32.3")
+def assert_series_not_equal(
+    left: Series,
+    right: Series,
+    *,
+    check_dtypes: bool = True,
+    check_names: bool = True,
+    check_order: bool = True,
+    check_exact: bool = False,
+    rel_tol: float = 1e-5,
+    abs_tol: float = 1e-8,
+    categorical_as_str: bool = False,
+) -> None:
+    """
+    Assert that the left and right Series are **not** equal.
+
+    This function is intended for use in unit tests.
+
+    .. versionchanged:: 0.20.31
+        The `check_dtype` parameter was renamed `check_dtypes`.
+
+    .. versionchanged:: 1.32.3
+        The `rtol` and `atol` parameters were renamed to `rel_tol` and `abs_tol`,
+        respectively.
+
+    Parameters
+    ----------
+    left
+        The first Series to compare.
+    right
+        The second Series to compare.
+    check_dtypes
+        Requires data types to match.
+    check_names
+        Requires names to match.
+    check_order
+        Requires elements to appear in the same order.
+    check_exact
+        Requires float values to match exactly. If set to `False`, values are considered
+        equal when within tolerance of each other (see `rel_tol` and `abs_tol`).
+        Only affects columns with a Float data type.
+    rel_tol
+        Relative tolerance for inexact checking, given as a fraction of the values in
+        `right`.
+    abs_tol
+        Absolute tolerance for inexact checking.
+    categorical_as_str
+        Cast categorical columns to string before comparing. Enabling this helps
+        compare columns that do not share the same string cache.
+
+    See Also
+    --------
+    assert_series_equal
+    assert_frame_not_equal
+
+    Examples
+    --------
+    >>> from polars.testing import assert_series_not_equal
+    >>> s1 = pl.Series([1, 2, 3])
+    >>> s2 = pl.Series([1, 2, 3])
+    >>> assert_series_not_equal(s1, s2)
+    Traceback (most recent call last):
+    ...
+    AssertionError: Series are equal (but are expected not to be)
+    """
+    __tracebackhide__ = True
+
+    _assert_correct_input_type(left, right)
+    try:
+        assert_series_equal(
+            left=left,
+            right=right,
+            check_dtypes=check_dtypes,
+            check_names=check_names,
+            check_order=check_order,
+            check_exact=check_exact,
+            rel_tol=rel_tol,
+            abs_tol=abs_tol,
+            categorical_as_str=categorical_as_str,
+        )
+    except AssertionError:
+        return
+    else:
+        msg = "Series are equal (but are expected not to be)"
+        raise AssertionError(msg)

polars/testing/asserts/utils.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import Any, NoReturn
+
+
+def raise_assertion_error(
+    objects: str, detail: str, left: Any, right: Any, *, cause: Exception | None = None
+) -> NoReturn:
+    """Raise a detailed assertion error."""
+    __tracebackhide__ = True
+    msg = f"{objects} are different ({detail})\n[left]:  {left}\n[right]: {right}"
+    raise AssertionError(msg) from cause

polars/testing/parametric/__init__.py

@@ -0,0 +1,33 @@
+from polars._dependencies import _HYPOTHESIS_AVAILABLE
+
+if not _HYPOTHESIS_AVAILABLE:
+    msg = (
+        "polars.testing.parametric requires the 'hypothesis' module\n"
+        "Please install it using the command: pip install hypothesis"
+    )
+    raise ModuleNotFoundError(msg)
+
+from polars.testing.parametric.profiles import load_profile, set_profile
+from polars.testing.parametric.strategies import (
+    column,
+    columns,
+    create_list_strategy,
+    dataframes,
+    dtypes,
+    lists,
+    series,
+)
+
+__all__ = [
+    # strategies
+    "dataframes",
+    "series",
+    "column",
+    "columns",
+    "dtypes",
+    "lists",
+    "create_list_strategy",
+    # profiles
+    "load_profile",
+    "set_profile",
+]

polars/testing/parametric/profiles.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import os
+import re
+
+from hypothesis import settings
+
+from polars._typing import ParametricProfileNames
+
+
+def load_profile(
+    profile: ParametricProfileNames | int = "fast", *, set_environment: bool = False
+) -> None:
+    """
+    Load a named (or custom) hypothesis profile for use with the parametric tests.
+
+    .. warning::
+        This functionality is currently considered **unstable**. It may be
+        changed at any point without it being considered a breaking change.
+
+    Parameters
+    ----------
+    profile : {str, int}, optional
+        Name of the profile to load; one of "fast", "balanced", "expensive", or
+        the integer number of iterations to run (which will create and register
+        a custom profile with that value).
+
+    set_environment : bool, default False
+        If True, also set the environment variable `POLARS_HYPOTHESIS_PROFILE`
+        to the given profile name/value.
+
+    Examples
+    --------
+    >>> # load a custom profile that will run with 1500 iterations
+    >>> from polars.testing.parametric import load_profile
+    >>> load_profile(1500)
+    """
+    common_settings = {"print_blob": True, "deadline": None}
+    profile_name = str(profile)
+
+    # Register standard/named profiles
+    # --------------------------------
+    for name, iterations in (
+        ("fast", 100),
+        ("balanced", 1_000),
+        ("expensive", 10_000),
+    ):
+        settings.register_profile(
+            name=f"polars.{name}",
+            max_examples=iterations,
+            **common_settings,  # type: ignore[arg-type]
+        )
+
+    # Register a custom profile with 'n' iterations.
+    # ----------------------------------------------
+    # (Set the ideal number to balance time-vs-coverage for your machine).
+    if profile_name.isdigit() or re.match(r"polars\.custom\.[\d_]+$", profile_name):
+        n_iterations = int(profile_name.replace("polars.custom.", ""))
+        profile_name = f"polars.custom.{profile_name}"
+        settings.register_profile(
+            name=profile_name,
+            max_examples=n_iterations,
+            **common_settings,  # type: ignore[arg-type]
+        )
+
+    # Load the chosen profile
+    profile_name = f"polars.{profile_name.replace('polars.', '')}"
+    settings.load_profile(profile_name)
+
+    if set_environment:
+        set_profile(profile_name)  # type: ignore[arg-type]
+
+
+def set_profile(profile: ParametricProfileNames | int) -> None:
+    """
+    Set the env var `POLARS_HYPOTHESIS_PROFILE` to the given profile name/value.
+
+    .. warning::
+        This functionality is currently considered **unstable**. It may be
+        changed at any point without it being considered a breaking change.
+
+    Parameters
+    ----------
+    profile : {str, int}, optional
+        Name of the profile to load; one of "fast", "balanced", "expensive", or
+        the integer number of iterations to run (which will create and register
+        a custom profile with that value).
+
+    Examples
+    --------
+    >>> # prefer the 'balanced' profile for running parametric tests
+    >>> from polars.testing.parametric import set_profile
+    >>> set_profile("balanced")
+    """
+    profile_name = str(profile).split(".")[-1]
+    if profile_name.replace("_", "").isdigit():
+        profile_name = str(int(profile_name))
+
+    else:
+        from typing import get_args
+
+        valid_profile_names = get_args(ParametricProfileNames)
+        if profile_name not in valid_profile_names:
+            msg = f"invalid profile name {profile_name!r}; expected one of {valid_profile_names!r}"
+            raise ValueError(msg)
+
+    os.environ["POLARS_HYPOTHESIS_PROFILE"] = profile_name

polars/testing/parametric/strategies/__init__.py

@@ -0,0 +1,22 @@
+from polars.testing.parametric.strategies.core import (
+    column,
+    dataframes,
+    series,
+)
+from polars.testing.parametric.strategies.data import lists
+from polars.testing.parametric.strategies.dtype import dtypes
+from polars.testing.parametric.strategies.legacy import columns, create_list_strategy
+
+__all__ = [
+    # core
+    "dataframes",
+    "series",
+    "column",
+    # dtype
+    "dtypes",
+    # data
+    "lists",
+    # legacy
+    "columns",
+    "create_list_strategy",
+]

polars/testing/parametric/strategies/_utils.py

@@ -0,0 +1,14 @@
+from typing import Any
+
+
+def flexhash(elem: Any) -> int:
+    """
+    Hashing function that also handles lists and dictionaries.
+
+    Used for `unique` check in nested strategies.
+    """
+    if isinstance(elem, list):
+        return hash(tuple(flexhash(e) for e in elem))
+    elif isinstance(elem, dict):
+        return hash(tuple((k, flexhash(v)) for k, v in elem.items()))
+    return hash(elem)