dycw-utilities 0.129.10__py3-none-any.whl → 0.175.17__py3-none-any.whl

utilities/pytest.py

@@ -1,68 +1,82 @@
 from __future__ import annotations
 
+from collections.abc import Callable
 from dataclasses import dataclass
 from functools import partial, wraps
 from inspect import iscoroutinefunction
 from os import environ
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, ParamSpec, assert_never, cast, override
+from re import sub
+from types import FunctionType
+from typing import TYPE_CHECKING, Any, assert_never, cast, override
 
-from pytest import fixture
+from whenever import ZonedDateTime
 
-from utilities.datetime import datetime_duration_to_float, get_now
+from utilities.atomicwrites import writer
 from utilities.functools import cache
 from utilities.hashlib import md5_hash
-from utilities.pathlib import ensure_suffix
-from utilities.platform import (
-    IS_LINUX,
-    IS_MAC,
-    IS_NOT_LINUX,
-    IS_NOT_MAC,
-    IS_NOT_WINDOWS,
-    IS_WINDOWS,
+from utilities.os import get_env_var
+from utilities.pathlib import (
+    _GetTailEmptyError,
+    ensure_suffix,
+    get_root,
+    get_tail,
+    module_path,
 )
-from utilities.random import get_state
+from utilities.platform import IS_LINUX, IS_MAC, IS_NOT_LINUX, IS_NOT_MAC
+from utilities.random import bernoulli
+from utilities.text import to_bool
+from utilities.types import MaybeCallableBoolLike, MaybeCoro, Seed
+from utilities.whenever import SECOND, get_now_local
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable, Sequence
-    from random import Random
-
-    from utilities.types import (
-        Coroutine1,
-        Duration,
-        PathLike,
-        TCallableMaybeCoroutine1None,
-    )
+    from collections.abc import Iterable
 
-try:  # WARNING: this package cannot use unguarded `pytest` imports
     from _pytest.config import Config
     from _pytest.config.argparsing import Parser
     from _pytest.python import Function
-    from pytest import mark, skip
+
+    from utilities.types import Coro, Delta, PathLike
+
+
+IS_CI = "CI" in environ
+IS_CI_AND_NOT_LINUX = IS_CI and IS_NOT_LINUX
+
+
+try:  # WARNING: this package cannot use unguarded `pytest` imports
+    from pytest import mark
 except ModuleNotFoundError:  # pragma: no cover
-    from typing import Any as Config
-    from typing import Any as Function
-    from typing import Any as Parser
 
-    mark = skip = skipif_windows = skipif_mac = skipif_linux = skipif_not_windows = (
-        skipif_not_mac
-    ) = skipif_not_linux = None
+    def skipif_ci[F: Callable](func: F) -> F:
+        return func
+
+    def skipif_mac[F: Callable](func: F) -> F:
+        return func
+
+    def skipif_linux[F: Callable](func: F) -> F:
+        return func
+
+    def skipif_not_mac[F: Callable](func: F) -> F:
+        return func
+
+    def skipif_not_linux[F: Callable](func: F) -> F:
+        return func
+
+    def skipif_ci_and_not_linux[F: Callable](func: F) -> F:
+        return func
+
 else:
-    skipif_windows = mark.skipif(IS_WINDOWS, reason="Skipped for Windows")
+    skipif_ci = mark.skipif(IS_CI, reason="Skipped for CI")
     skipif_mac = mark.skipif(IS_MAC, reason="Skipped for Mac")
     skipif_linux = mark.skipif(IS_LINUX, reason="Skipped for Linux")
-    skipif_not_windows = mark.skipif(IS_NOT_WINDOWS, reason="Skipped for non-Windows")
     skipif_not_mac = mark.skipif(IS_NOT_MAC, reason="Skipped for non-Mac")
     skipif_not_linux = mark.skipif(IS_NOT_LINUX, reason="Skipped for non-Linux")
+    skipif_ci_and_not_linux = mark.skipif(
+        IS_CI_AND_NOT_LINUX, reason="Skipped for CI/non-Linux"
+    )
 
 
-_P = ParamSpec("_P")
-
-
-##
-
-
-def add_pytest_addoption(parser: Parser, options: Sequence[str], /) -> None:
+def add_pytest_addoption(parser: Parser, options: list[str], /) -> None:
     """Add the `--slow`, etc options to pytest.
 
     Usage:
@@ -83,7 +97,7 @@ def add_pytest_addoption(parser: Parser, options: Sequence[str], /) -> None:
 
 
 def add_pytest_collection_modifyitems(
-    config: Config, items: Iterable[Function], options: Sequence[str], /
+    config: Config, items: Iterable[Function], options: list[str], /
 ) -> None:
     """Add the @mark.skips as necessary.
 
@@ -92,6 +106,8 @@ def add_pytest_collection_modifyitems(
         def pytest_collection_modifyitems(config, items):
             add_pytest_collection_modifyitems(config, items, ["slow"])
     """
+    from pytest import mark
+
     options = list(options)
     missing = {opt for opt in options if not config.getoption(f"--{opt}")}
     for item in items:
@@ -121,26 +137,32 @@ def add_pytest_configure(config: Config, options: Iterable[tuple[str, str]], /)
 ##
 
 
-def is_pytest() -> bool:
-    """Check if `pytest` is running."""
-    return "PYTEST_VERSION" in environ
+def make_ids(obj: Any, /) -> str:
+    if isinstance(obj, FunctionType):
+        return sub(r"\s+at +0x[0-9a-fA-F]+", "", repr(obj))
+    return repr(obj)
 
 
 ##
 
 
-def node_id_to_path(
-    node_id: str, /, *, head: PathLike | None = None, suffix: str | None = None
+def node_id_path(
+    node_id: str, /, *, root: PathLike | None = None, suffix: str | None = None
 ) -> Path:
-    """Map a node ID to a path."""
+    """Get the path of a node ID."""
     path_file, *parts = node_id.split("::")
     path_file = Path(path_file)
     if path_file.suffix != ".py":
-        raise NodeIdToPathError(node_id=node_id)
+        raise _NodeIdToPathNotPythonFileError(node_id=node_id)
     path = path_file.with_suffix("")
-    if head is not None:
-        path = path.relative_to(head)
-    path = Path(".".join(path.parts), "__".join(parts))
+    if root is not None:
+        try:
+            path = get_tail(path, root)
+        except _GetTailEmptyError as error:
+            raise _NodeIdToPathNotGetTailError(
+                node_id=node_id, path=error.path, root=error.root
+            ) from None
+    path = Path(module_path(path), "__".join(parts))
     if suffix is not None:
         path = ensure_suffix(path, suffix)
     return path
@@ -150,123 +172,207 @@ def node_id_to_path(
 class NodeIdToPathError(Exception):
     node_id: str
 
+
+@dataclass(kw_only=True, slots=True)
+class _NodeIdToPathNotPythonFileError(NodeIdToPathError):
     @override
     def __str__(self) -> str:
         return f"Node ID must be a Python file; got {self.node_id!r}"
 
 
-##
-
+@dataclass(kw_only=True, slots=True)
+class _NodeIdToPathNotGetTailError(NodeIdToPathError):
+    path: PathLike
+    root: PathLike
 
-@fixture
-def random_state(*, seed: int) -> Random:
-    """Fixture for a random state."""
-    return get_state(seed=seed)
+    @override
+    def __str__(self) -> str:
+        return (
+            f"Unable to get the tail of {str(self.path)!r} with root {str(self.root)!r}"
+        )
 
 
 ##
 
 
-def throttle(
-    *, root: PathLike | None = None, duration: Duration = 1.0, on_try: bool = False
-) -> Callable[[TCallableMaybeCoroutine1None], TCallableMaybeCoroutine1None]:
-    """Throttle a test. On success by default, on try otherwise."""
-    root_use = Path(".pytest_cache", "throttle") if root is None else Path(root)
+def run_frac[F: Callable[..., MaybeCoro[None]]](
+    *,
+    predicate: MaybeCallableBoolLike | None = None,
+    frac: float = 0.5,
+    seed: Seed | None = None,
+) -> Callable[[F], F]:
+    """Run a test only a fraction of the time.."""
     return cast(
-        "Any", partial(_throttle_inner, root=root_use, duration=duration, on_try=on_try)
+        "Any", partial(_run_frac_inner, predicate=predicate, frac=frac, seed=seed)
     )
 
 
-def _throttle_inner(
-    func: TCallableMaybeCoroutine1None,
+def _run_frac_inner[F: Callable[..., MaybeCoro[None]]](
+    func: F,
     /,
     *,
-    root: Path,
-    duration: Duration = 1.0,
-    on_try: bool = False,
-) -> TCallableMaybeCoroutine1None:
-    """Throttle a test function/method."""
+    predicate: MaybeCallableBoolLike | None = None,
+    frac: float = 0.5,
+    seed: Seed | None = None,
+) -> F:
     match bool(iscoroutinefunction(func)):
         case False:
-            func_typed = cast("Callable[..., None]", func)
 
             @wraps(func)
-            def throttle_sync(*args: _P.args, **kwargs: _P.kwargs) -> None:
-                """Call the throttled sync test function/method."""
-                path, now = _throttle_path_and_now(root, duration=duration)
-                if on_try:
-                    _throttle_write(path, now)
-                    return func_typed(*args, **kwargs)
-                func_typed(*args, **kwargs)
-                _throttle_write(path, now)
-                return None
-
-            return cast("TCallableMaybeCoroutine1None", throttle_sync)
+            def run_frac_sync(*args: Any, **kwargs: Any) -> None:
+                _skipif_frac(predicate=predicate, frac=frac, seed=seed)
+                cast("Callable[..., None]", func)(*args, **kwargs)
+
+            return cast("Any", run_frac_sync)
+
         case True:
-            func_typed = cast("Callable[..., Coroutine1[None]]", func)
 
             @wraps(func)
-            async def throttle_async(*args: _P.args, **kwargs: _P.kwargs) -> None:
-                """Call the throttled async test function/method."""
-                path, now = _throttle_path_and_now(root, duration=duration)
-                if on_try:
-                    _throttle_write(path, now)
-                    return await func_typed(*args, **kwargs)
-                await func_typed(*args, **kwargs)
-                _throttle_write(path, now)
-                return None
-
-            return cast("TCallableMaybeCoroutine1None", throttle_async)
-        case _ as never:
+            async def run_frac_async(*args: Any, **kwargs: Any) -> None:
+                _skipif_frac(predicate=predicate, frac=frac, seed=seed)
+                await cast("Callable[..., Coro[None]]", func)(*args, **kwargs)
+
+            return cast("Any", run_frac_async)
+
+        case never:
             assert_never(never)
 
 
-def _throttle_path_and_now(
-    root: Path, /, *, duration: Duration = 1.0
-) -> tuple[Path, float]:
-    test = environ["PYTEST_CURRENT_TEST"]
-    path = Path(root, _throttle_md5_hash(test))
-    if path.exists():
-        with path.open(mode="r") as fh:
-            contents = fh.read()
-        prev = float(contents)
-    else:
-        prev = None
-    now = get_now().timestamp()
-    if (
-        (skip is not None)
-        and (prev is not None)
-        and ((now - prev) < datetime_duration_to_float(duration))
+def _skipif_frac(
+    *,
+    predicate: MaybeCallableBoolLike | None = None,
+    frac: float = 0.5,
+    seed: Seed | None = None,
+) -> None:
+    from pytest import skip
+
+    if ((predicate is None) or to_bool(predicate)) and bernoulli(
+        true=1 - frac, seed=seed
     ):
-        _ = skip(reason=f"{test} throttled")
-    return path, now
+        skip(reason=f"{_get_name()} skipped (run {frac:.0%})")
+
+
+##
+
+
+def throttle[F: Callable[..., MaybeCoro[None]]](
+    *, root: PathLike | None = None, delta: Delta = SECOND, on_try: bool = False
+) -> Callable[[F], F]:
+    """Throttle a test. On success by default, on try otherwise."""
+    return cast("Any", partial(_throttle_inner, root=root, delta=delta, on_try=on_try))
+
+
+def _throttle_inner[F: Callable[..., MaybeCoro[None]]](
+    func: F,
+    /,
+    *,
+    root: PathLike | None = None,
+    delta: Delta = SECOND,
+    on_try: bool = False,
+) -> F:
+    if get_env_var("THROTTLE", nullable=True) is not None:
+        return func
+    match bool(iscoroutinefunction(func)), on_try:
+        case False, False:
+
+            @wraps(func)
+            def throttle_sync_on_pass(*args: Any, **kwargs: Any) -> None:
+                _skipif_recent(root=root, delta=delta)
+                cast("Callable[..., None]", func)(*args, **kwargs)
+                _write(root)
+
+            return cast("Any", throttle_sync_on_pass)
+
+        case False, True:
+
+            @wraps(func)
+            def throttle_sync_on_try(*args: Any, **kwargs: Any) -> None:
+                _skipif_recent(root=root, delta=delta)
+                _write(root)
+                cast("Callable[..., None]", func)(*args, **kwargs)
+
+            return cast("Any", throttle_sync_on_try)
+
+        case True, False:
+
+            @wraps(func)
+            async def throttle_async_on_pass(*args: Any, **kwargs: Any) -> None:
+                _skipif_recent(root=root, delta=delta)
+                await cast("Callable[..., Coro[None]]", func)(*args, **kwargs)
+                _write(root)
+
+            return cast("Any", throttle_async_on_pass)
+
+        case True, True:
+
+            @wraps(func)
+            async def throttle_async_on_try(*args: Any, **kwargs: Any) -> None:
+                _skipif_recent(root=root, delta=delta)
+                _write(root)
+                await cast("Callable[..., Coro[None]]", func)(*args, **kwargs)
+
+            return cast("Any", throttle_async_on_try)
+
+        case never:
+            assert_never(never)
+
+
+def _skipif_recent(*, root: PathLike | None = None, delta: Delta = SECOND) -> None:
+    from pytest import skip
+
+    path = _get_path(root)
+    try:
+        contents = path.read_text()
+    except FileNotFoundError:
+        return
+    try:
+        last = ZonedDateTime.parse_iso(contents)
+    except ValueError:
+        return
+    now = get_now_local()
+    if (now - delta) < last:
+        age = now - last
+        _ = skip(reason=f"{_get_name()} throttled (age {age})")
+
+
+def _get_path(root: PathLike | None = None, /) -> Path:
+    if root is None:
+        root_use = get_root().joinpath(".pytest_cache", "throttle")  # pragma: no cover
+    else:
+        root_use = root
+    return Path(root_use, _md5_hash_cached(_get_name()))
 
 
 @cache
-def _throttle_md5_hash(text: str, /) -> str:
+def _md5_hash_cached(text: str, /) -> str:
     return md5_hash(text)
 
 
-def _throttle_write(path: Path, now: float, /) -> None:
-    from utilities.atomicwrites import writer
+def _get_name() -> str:
+    return environ["PYTEST_CURRENT_TEST"]
+
 
-    with writer(path, overwrite=True) as temp, temp.open(mode="w") as fh:
-        _ = fh.write(str(now))
+def _write(root: PathLike | None = None, /) -> None:
+    path = _get_path(root)
+    with writer(path, overwrite=True) as temp:
+        _ = temp.write_text(get_now_local().format_iso())
 
 
 __all__ = [
+    "IS_CI",
+    "IS_CI_AND_NOT_LINUX",
     "NodeIdToPathError",
     "add_pytest_addoption",
     "add_pytest_collection_modifyitems",
     "add_pytest_configure",
-    "is_pytest",
-    "node_id_to_path",
-    "random_state",
+    "make_ids",
+    "node_id_path",
+    "run_frac",
+    "skipif_ci",
+    "skipif_ci_and_not_linux",
     "skipif_linux",
     "skipif_mac",
     "skipif_not_linux",
     "skipif_not_mac",
-    "skipif_not_windows",
-    "skipif_windows",
     "throttle",
 ]

utilities/pytest_plugins/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

utilities/pytest_plugins/pytest_randomly.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from random import Random
+
+
+try:
+    from pytest import fixture
+except ModuleNotFoundError:
+    pass
+else:
+
+    @fixture
+    def random_state(*, seed: int) -> Random:
+        """Fixture for a random state."""
+        from utilities.random import get_state
+
+        return get_state(seed)
+
+
+__all__ = ["random_state"]

utilities/pytest_plugins/pytest_regressions.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+
+if TYPE_CHECKING:
+    from pytest import FixtureRequest
+
+    from utilities.pytest_regressions import (
+        OrjsonRegressionFixture,
+        PolarsRegressionFixture,
+    )
+
+
+try:
+    from pytest import fixture
+except ModuleNotFoundError:
+    pass
+else:
+
+    @fixture
+    def orjson_regression(
+        *, request: FixtureRequest, tmp_path: Path
+    ) -> OrjsonRegressionFixture:
+        """Instance of the `OrjsonRegressionFixture`."""
+        from utilities.pytest_regressions import OrjsonRegressionFixture
+
+        path = _get_path(request)
+        return OrjsonRegressionFixture(path, request, tmp_path)
+
+    @fixture
+    def polars_regression(
+        *, request: FixtureRequest, tmp_path: Path
+    ) -> PolarsRegressionFixture:
+        """Instance of the `PolarsRegressionFixture`."""
+        from utilities.pytest_regressions import PolarsRegressionFixture
+
+        path = _get_path(request)
+        return PolarsRegressionFixture(path, request, tmp_path)
+
+
+def _get_path(request: FixtureRequest, /) -> Path:
+    from utilities.pathlib import get_root
+    from utilities.pytest import _NodeIdToPathNotGetTailError, node_id_path
+
+    path = Path(cast("Any", request).fspath)
+    root = Path("src", "tests")
+    try:
+        tail = node_id_path(request.node.nodeid, root=root)
+    except _NodeIdToPathNotGetTailError:
+        root = Path("tests")
+        tail = node_id_path(request.node.nodeid, root=root)
+    return get_root(path).joinpath(root, "regressions", tail)
+
+
+__all__ = ["orjson_regression", "polars_regression"]

utilities/pytest_regressions.py

@@ -1,18 +1,17 @@
 from __future__ import annotations
 
 from contextlib import suppress
+from dataclasses import dataclass
 from json import loads
 from pathlib import Path
 from shutil import copytree
-from typing import TYPE_CHECKING, Any, assert_never
+from typing import TYPE_CHECKING, Any, assert_never, override
 
-from pytest import fixture
 from pytest_regressions.file_regression import FileRegressionFixture
 
 from utilities.functions import ensure_str
 from utilities.operator import is_equal
-from utilities.pathlib import get_root
-from utilities.pytest import node_id_to_path
+from utilities.reprlib import get_repr
 
 if TYPE_CHECKING:
     from polars import DataFrame, Series
@@ -21,9 +20,6 @@ if TYPE_CHECKING:
     from utilities.types import PathLike, StrMapping
 
 
-_PATH_TESTS = Path("src", "tests")
-
-
 ##
 
 
@@ -76,21 +72,28 @@ class OrjsonRegressionFixture:
             check_fn=self._check_fn,
         )
 
-    def _check_fn(self, path1: Path, path2: Path, /) -> None:
-        with path1.open(mode="r") as fh:
-            left = loads(fh.read())
-        with path2.open(mode="r") as fh:
-            right = loads(fh.read())
-        assert is_equal(left, right), f"{left=}, {right=}"
+    def _check_fn(self, path_obtained: Path, path_existing: Path, /) -> None:
+        obtained = loads(path_obtained.read_text())
+        existing = loads(path_existing.read_text())
+        if not is_equal(obtained, existing):
+            raise OrjsonRegressionError(
+                path_obtained=path_obtained,
+                path_existing=path_existing,
+                obtained=obtained,
+                existing=existing,
+            )
+
 
+@dataclass(kw_only=True, slots=True)
+class OrjsonRegressionError(Exception):
+    path_obtained: Path
+    path_existing: Path
+    obtained: Any
+    existing: Any
 
-@fixture
-def orjson_regression(
-    *, request: FixtureRequest, tmp_path: Path
-) -> OrjsonRegressionFixture:
-    """Instance of the `OrjsonRegressionFixture`."""
-    path = _get_path(request)
-    return OrjsonRegressionFixture(path, request, tmp_path)
+    @override
+    def __str__(self) -> str:
+        return f"Obtained object (at {str(self.path_obtained)!r}) and existing object (at {str(self.path_existing)!r}) differ; got {get_repr(self.obtained)} and {get_repr(self.existing)}"
 
 
 ##
@@ -114,7 +117,6 @@ class PolarsRegressionFixture:
             "describe": obj.describe(percentiles=[i / 10 for i in range(1, 10)]).rows(
                 named=True
             ),
-            "estimated_size": obj.estimated_size(),
             "is_empty": obj.is_empty(),
             "n_unique": obj.n_unique(),
         }
@@ -132,33 +134,11 @@ class PolarsRegressionFixture:
                             col(column).approx_n_unique()
                         ).item()
                 data["approx_n_unique"] = approx_n_unique
-                data["glimpse"] = df.glimpse(return_as_string=True)
+                data["glimpse"] = df.glimpse(return_type="string")
                 data["null_count"] = df.null_count().row(0, named=True)
-            case _ as never:
+            case never:
                 assert_never(never)
         self._fixture.check(data, suffix=suffix)
 
 
-@fixture
-def polars_regression(
-    *, request: FixtureRequest, tmp_path: Path
-) -> PolarsRegressionFixture:
-    """Instance of the `PolarsRegressionFixture`."""
-    path = _get_path(request)
-    return PolarsRegressionFixture(path, request, tmp_path)
-
-
-##
-
-
-def _get_path(request: FixtureRequest, /) -> Path:
-    tail = node_id_to_path(request.node.nodeid, head=_PATH_TESTS)
-    return get_root().joinpath(_PATH_TESTS, "regressions", tail)
-
-
-__all__ = [
-    "OrjsonRegressionFixture",
-    "PolarsRegressionFixture",
-    "orjson_regression",
-    "polars_regression",
-]
+__all__ = ["OrjsonRegressionFixture", "PolarsRegressionFixture"]