Merge pull request #4616 from Zac-HD/claude/add-min-leaves-parameter-01XYPfenzf6xuY64W4tMDpAT

Add `min_leaves` parameter to `st.recursive()`

Author: Zac-HD

hypothesis-python/RELEASE.rst

@@ -0,0 +1,5 @@
+RELEASE_TYPE: minor
+
+This release adds a ``min_leaves`` argument to :func:`~hypothesis.strategies.recursive`,
+which ensures that generated recursive structures have at least the specified number
+of leaf nodes (:issue:`4205`).

hypothesis-python/src/hypothesis/strategies/_internal/core.py

@@ -1857,12 +1857,16 @@ def recursive(
     base: SearchStrategy[Ex],
     extend: Callable[[SearchStrategy[Any]], SearchStrategy[T]],
     *,
+    min_leaves: int = 1,
     max_leaves: int = 100,
 ) -> SearchStrategy[T | Ex]:
     """base: A strategy to start from.
 
     extend: A function which takes a strategy and returns a new strategy.
 
+    min_leaves: The minimum number of elements to be drawn from base on a given
+    run.
+
     max_leaves: The maximum number of elements to be drawn from base on a given
     run.
 
@@ -1881,7 +1885,7 @@ def recursive(
 
     """
 
-    return RecursiveStrategy(base, extend, max_leaves)
+    return RecursiveStrategy(base, extend, min_leaves, max_leaves)
 
 
 class PermutationStrategy(SearchStrategy):

hypothesis-python/src/hypothesis/strategies/_internal/recursive.py

@@ -9,10 +9,14 @@
 # obtain one at https://mozilla.org/MPL/2.0/.
 
 import threading
+import warnings
 from contextlib import contextmanager
 
-from hypothesis.errors import InvalidArgument
-from hypothesis.internal.reflection import get_pretty_function_description
+from hypothesis.errors import HypothesisWarning, InvalidArgument
+from hypothesis.internal.reflection import (
+    get_pretty_function_description,
+    is_identity_function,
+)
 from hypothesis.internal.validation import check_type
 from hypothesis.strategies._internal.strategies import (
     OneOfStrategy,
@@ -72,24 +76,36 @@ def capped(self, max_templates):
 
 
 class RecursiveStrategy(SearchStrategy):
-    def __init__(self, base, extend, max_leaves):
+    def __init__(self, base, extend, min_leaves, max_leaves):
         super().__init__()
+        self.min_leaves = min_leaves
         self.max_leaves = max_leaves
         self.base = base
         self.limited_base = LimitedStrategy(base)
         self.extend = extend
 
+        if is_identity_function(extend):
+            warnings.warn(
+                "extend=lambda x: x is a no-op; you probably want to use a "
+                "different extend function, or just use the base strategy directly.",
+                HypothesisWarning,
+                stacklevel=5,
+            )
+
         strategies = [self.limited_base, self.extend(self.limited_base)]
         while 2 ** (len(strategies) - 1) <= max_leaves:
             strategies.append(extend(OneOfStrategy(tuple(strategies))))
+        # If min_leaves > 1, we can never draw from base directly
+        if min_leaves > 1:
+            strategies = strategies[1:]
         self.strategy = OneOfStrategy(strategies)
 
     def __repr__(self) -> str:
         if not hasattr(self, "_cached_repr"):
-            self._cached_repr = "recursive(%r, %s, max_leaves=%d)" % (
-                self.base,
-                get_pretty_function_description(self.extend),
-                self.max_leaves,
+            self._cached_repr = (
+                f"recursive({self.base!r}, "
+                f"{get_pretty_function_description(self.extend)}, "
+                f"min_leaves={self.min_leaves}, max_leaves={self.max_leaves})"
             )
         return self._cached_repr
 
@@ -99,20 +115,41 @@ def do_validate(self) -> None:
         check_strategy(extended, f"extend({self.limited_base!r})")
         self.limited_base.validate()
         extended.validate()
+        check_type(int, self.min_leaves, "min_leaves")
         check_type(int, self.max_leaves, "max_leaves")
+        if self.min_leaves <= 0:
+            raise InvalidArgument(
+                f"min_leaves={self.min_leaves!r} must be greater than zero"
+            )
         if self.max_leaves <= 0:
             raise InvalidArgument(
                 f"max_leaves={self.max_leaves!r} must be greater than zero"
             )
+        if self.min_leaves > self.max_leaves:
+            raise InvalidArgument(
+                f"min_leaves={self.min_leaves!r} must be less than or equal to "
+                f"max_leaves={self.max_leaves!r}"
+            )
 
     def do_draw(self, data):
-        count = 0
+        min_leaves_retries = 0
         while True:
             try:
                 with self.limited_base.capped(self.max_leaves):
-                    return data.draw(self.strategy)
+                    result = data.draw(self.strategy)
+                    leaves_drawn = self.max_leaves - self.limited_base.marker
+                    if leaves_drawn < self.min_leaves:
+                        data.events[
+                            f"Draw for {self!r} had fewer than "
+                            f"min_leaves={self.min_leaves} and had to be retried"
+                        ] = ""
+                        min_leaves_retries += 1
+                        if min_leaves_retries < 5:
+                            continue
+                        data.mark_invalid(f"min_leaves={self.min_leaves} unsatisfied")
+                    return result
             except LimitReached:
-                if count == 0:
-                    msg = f"Draw for {self!r} exceeded max_leaves and had to be retried"
-                    data.events[msg] = ""
-                count += 1
+                data.events[
+                    f"Draw for {self!r} exceeded "
+                    f"max_leaves={self.max_leaves} and had to be retried"
+                ] = ""

hypothesis-python/tests/cover/test_recursive.py

@@ -10,10 +10,15 @@
 
 import pytest
 
-from hypothesis import given, strategies as st
-from hypothesis.errors import InvalidArgument
-
-from tests.common.debug import check_can_generate_examples, find_any, minimal
+from hypothesis import given, note, settings, strategies as st
+from hypothesis.errors import HypothesisWarning, InvalidArgument
+
+from tests.common.debug import (
+    assert_all_examples,
+    check_can_generate_examples,
+    find_any,
+    minimal,
+)
 
 
 @given(st.recursive(st.booleans(), st.lists, max_leaves=10))
@@ -83,8 +88,44 @@ def test_issue_1502_regression(s):
         st.recursive(st.none(), st.lists, max_leaves=-1),
         st.recursive(st.none(), st.lists, max_leaves=0),
         st.recursive(st.none(), st.lists, max_leaves=1.0),
+        st.recursive(st.none(), st.lists, min_leaves=-1),
+        st.recursive(st.none(), st.lists, min_leaves=0),
+        st.recursive(st.none(), st.lists, min_leaves=1.0),
+        st.recursive(st.none(), st.lists, min_leaves=10, max_leaves=5),
     ],
 )
 def test_invalid_args(s):
     with pytest.raises(InvalidArgument):
         check_can_generate_examples(s)
+
+
+def _count_leaves(tree):
+    if isinstance(tree, tuple):
+        return sum(_count_leaves(child) for child in tree)
+    return 1
+
+
+@given(st.data())
+@settings(max_examples=5, suppress_health_check=["filter_too_much"])
+def test_respects_min_leaves(data):
+    min_leaves = data.draw(st.integers(1, 20))
+    max_leaves = data.draw(st.integers(min_leaves, 40))
+    note(f"{min_leaves=}")
+    note(f"{max_leaves=}")
+    s = st.recursive(
+        st.none(),
+        lambda x: st.tuples(x, x),
+        min_leaves=min_leaves,
+        max_leaves=max_leaves,
+    )
+    assert_all_examples(s, lambda tree: min_leaves <= _count_leaves(tree) <= max_leaves)
+
+
+@given(st.recursive(st.none(), lambda x: st.tuples(x, x), min_leaves=5, max_leaves=5))
+def test_can_set_exact_leaf_count(tree):
+    assert _count_leaves(tree) == 5
+
+
+def test_identity_extend_warns():
+    with pytest.warns(HypothesisWarning, match="extend=lambda x: x is a no-op"):
+        st.recursive(st.none(), lambda x: x)