Skip to content

Commit 918b125

Browse files
claudeZac-HD
andcommitted
Support .filter(...) and .map(...) on stateful Bundles
Bundle now intercepts .filter and .map, storing the transformations and applying them within a single draw: a throwaway SampledFromStrategy subclass samples (position, reference) pairs from the bundle's current contents, resolves values lazily, and retries rejected elements without redrawing the whole step. consumes() preserves transformations, so consumes(b).filter(fn) and consumes(b.filter(fn)) are both supported and only ever remove the value which was actually drawn. Previously, filtering a consuming bundle also popped every rejected value, and consumes(b.filter(fn)) was a type error. Design notes: - The old BundleReferenceStrategy is inlined into Bundle, which draws VarReferences for direct rule arguments so printed reproductions use variable names; with a map transformation the passed value is not the stored one, so the transformed value is drawn and printed directly. - The per-draw sampler is what keeps bundle draws thread-safe: Bundle and its Rule-created copies are shared by every instance (and thread) of a machine class, so per-draw state never lives on them. - Since Bundle is not a SampledFromStrategy, construction-time optimizations like the unique-lists fast path and text() alphabet inspection never see a bundle; lists(bundle, unique=True) keeps using the generic unique-list strategy. Informed by Reagan Lee's earlier implementation in upstream PR 4084 and Liam's review comments there. Co-Authored-By: Zac Hatfield-Dodds <[email protected]> Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Fm2EfTyhtGU8GsiUBUN9df
1 parent d851bb3 commit 918b125

5 files changed

Lines changed: 430 additions & 41 deletions

File tree

‎hypothesis/RELEASE.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
RELEASE_TYPE: minor
2+
3+
:class:`~hypothesis.stateful.Bundle` now supports efficient |.filter|
4+
and |.map| methods, which compose with
5+
:func:`~hypothesis.stateful.consumes` in either order (:issue:`3944`).
6+
Previously, ``consumes(bundle).filter(fn)`` could remove rejected values from
7+
the bundle while retrying, and ``consumes(bundle.filter(fn))`` was a type
8+
error; filtered draws now select among currently-matching values and consume
9+
only the value which was actually drawn.
10+
11+
Thanks to Reagan Lee for the initial implementation of this feature in
12+
:pull:`4084`!

‎hypothesis/docs/stateful.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ A rule can, in place of a normal strategy, take a :class:`~hypothesis.stateful.B
2525

2626
Specifically, a rule that specifies ``target=a_bundle`` will cause its return value to be added to that bundle. A rule that specifies ``an_argument=a_bundle`` as a strategy will draw a value from that bundle. A rule can also specify that an argument chooses a value from a bundle and removes that value by using :func:`~hypothesis.stateful.consumes` as in ``an_argument=consumes(a_bundle)``.
2727

28+
Bundles can be filtered and mapped like any other strategy, and this composes with :func:`~hypothesis.stateful.consumes` in either order: ``consumes(a_bundle.filter(fn))`` and ``consumes(a_bundle).filter(fn)`` both draw a currently-matching value and remove only that value from the bundle.
29+
2830
.. note::
2931
There is some overlap between what you can do with Bundles and what you can do with instance variables. Both represent state that rules can manipulate. If you do not need to draw values that depend on the machine's state, you can simply use instance variables. If you do need to draw values that depend on the machine's state, Bundles provide a fairly straightforward way to do this. If you need rules that draw values that depend on the machine's state in some more complicated way, you will have to abandon bundles. You can use :func:`~hypothesis.strategies.runner` and |.flatmap| to access the instance from a rule: the strategy ``runner().flatmap(lambda self: sampled_from(self.a_list))`` will draw from the instance variable ``a_list``. If you need something more complicated still, you can use |st.data| to draw data from the instance (or anywhere else) based on logic in the rule.
3032

‎hypothesis/src/hypothesis/stateful.py‎

Lines changed: 108 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
from functools import lru_cache
2525
from io import StringIO
2626
from time import perf_counter
27-
from typing import Any, ClassVar, TypeVar, overload
27+
from typing import Any, ClassVar, Literal, TypeVar, overload
2828
from unittest import TestCase
2929

3030
from hypothesis import strategies as st
@@ -54,8 +54,10 @@
5454
from hypothesis.strategies._internal.strategies import (
5555
Ex,
5656
OneOfStrategy,
57+
SampledFromStrategy,
5758
SearchStrategy,
5859
check_strategy,
60+
filter_not_satisfied,
5961
)
6062
from hypothesis.utils.deprecation import note_deprecation
6163
from hypothesis.vendor.pretty import RepresentationPrinter
@@ -525,10 +527,22 @@ class Rule:
525527
def __post_init__(self):
526528
bundles = []
527529
for k, v in sorted(self.arguments.items()):
528-
assert not isinstance(v, BundleReferenceStrategy)
529530
if isinstance(v, Bundle):
530531
bundles.append(v)
531-
v = BundleReferenceStrategy(v.name, consume=v.consume)
532+
# We use a VarReference so that the printed reproduction refers to
533+
# values by their variable names, except when a map transform is
534+
# involved, in which case the value passed to the rule is not the one
535+
# stored on the machine and we want to draw the transformed value
536+
# directly instead of a reference.
537+
draw_references = all(
538+
name == "filter" for name, _ in v._transformations
539+
)
540+
v = Bundle(
541+
v.name,
542+
consume=v.consume,
543+
draw_references=draw_references,
544+
transformations=v._transformations,
545+
)
532546
self.arguments_strategies[k] = v
533547
self.bundles = tuple(bundles)
534548

@@ -562,25 +576,34 @@ def __hash__(self):
562576
self_strategy = st.runner()
563577

564578

565-
class BundleReferenceStrategy(SearchStrategy):
566-
def __init__(self, name: str, *, consume: bool = False):
567-
super().__init__()
568-
self.name = name
569-
self.consume = consume
579+
class _BundleSampler(SampledFromStrategy):
580+
"""A single draw from the current contents of a Bundle.
570581
571-
def do_draw(self, data):
572-
machine = data.draw(self_strategy)
573-
bundle = machine.bundle(self.name)
574-
if not bundle:
575-
data.mark_invalid(f"Cannot draw from empty bundle {self.name!r}")
576-
# Shrink towards the right rather than the left. This makes it easier
577-
# to delete data generated earlier, as when the error is towards the
578-
# end there can be a lot of hard to remove padding.
579-
position = data.draw_integer(0, len(bundle) - 1, shrink_towards=len(bundle))
580-
if self.consume:
581-
return bundle.pop(position) # pragma: no cover # coverage is flaky here
582-
else:
583-
return bundle[position]
582+
A Bundle's elements are only known at draw time, so Bundle.do_draw
583+
constructs a throwaway instance of this strategy for each draw, passing
584+
(position, reference) pairs as the elements.
585+
586+
The throwaway instance is also what makes bundle draws thread-safe:
587+
Bundle and its Rule-created copies are shared by every instance of the
588+
machine class, so per-draw state must live here and never on them.
589+
"""
590+
591+
def __init__(self, machine, elements, *, force_repr, transformations):
592+
super().__init__(
593+
elements, force_repr=force_repr, transformations=transformations
594+
)
595+
self.machine = machine
596+
597+
def _transform(self, element):
598+
# Filter and map transformations apply to the value, which we look up
599+
# lazily so that untested elements cost nothing; the position and
600+
# reference ride along so that Bundle.do_draw can consume the chosen
601+
# element and refer to it by name.
602+
position, reference = element
603+
result = super()._transform(self.machine.names_to_values[reference.name])
604+
if result is filter_not_satisfied:
605+
return filter_not_satisfied
606+
return (position, reference, result)
584607

585608

586609
class Bundle(SearchStrategy[Ex]):
@@ -603,29 +626,81 @@ class MyStateMachine(RuleBasedStateMachine):
603626
604627
If the ``consume`` argument is set to True, then all values that are
605628
drawn from this bundle will be consumed (as above) when requested.
629+
630+
Bundles may be used with |.filter| and |.map| like any other
631+
strategy, and this composes with :func:`~hypothesis.stateful.consumes` in
632+
either order - e.g. ``consumes(b.filter(fn))`` and ``consumes(b).filter(fn)``
633+
are equivalent, and only ever consume the value which was actually drawn.
606634
"""
607635

608636
def __init__(
609-
self, name: str, *, consume: bool = False, draw_references: bool = True
637+
self,
638+
name: str,
639+
*,
640+
consume: bool = False,
641+
draw_references: bool = False,
642+
transformations: tuple[
643+
tuple[Literal["filter", "map"], Callable[[Ex], Any]], ...
644+
] = (),
610645
) -> None:
611646
super().__init__()
612647
self.name = name
613-
self.__reference_strategy = BundleReferenceStrategy(name, consume=consume)
648+
self.consume = consume
614649
self.draw_references = draw_references
615-
616-
@property
617-
def consume(self) -> bool:
618-
return self.__reference_strategy.consume
650+
self._transformations = transformations
619651

620652
def do_draw(self, data):
621653
machine = data.draw(self_strategy)
622-
reference = data.draw(self.__reference_strategy)
623-
return machine.names_to_values[reference.name]
654+
bundle = machine.bundle(self.name)
655+
if not bundle:
656+
data.mark_invalid(f"Cannot draw from empty bundle {self.name!r}")
657+
# Shrink towards the right rather than the left. This makes it easier
658+
# to delete data generated earlier, as when the error is towards the
659+
# end there can be a lot of hard to remove padding. do_filtered_draw
660+
# shrinks the index towards zero, so we list the elements newest-first.
661+
sampler = _BundleSampler(
662+
machine,
663+
list(enumerate(bundle))[::-1],
664+
force_repr=self._base_repr(),
665+
transformations=self._transformations,
666+
)
667+
result = sampler.do_filtered_draw(data)
668+
if result is filter_not_satisfied:
669+
data.mark_invalid(f"Aborted test because unable to satisfy {self!r}")
670+
position, reference, value = result
671+
if self.consume:
672+
bundle.pop(position) # pragma: no cover # coverage is flaky here
673+
return reference if self.draw_references else value
674+
675+
# We intercept .filter and .map, rather than relying on the generic
676+
# FilteredStrategy and MappedStrategy wrappers, so that transformations
677+
# apply within a single draw: the generic wrappers instead retry the whole
678+
# draw when a filter fails, consuming rejected values from consuming
679+
# bundles, and are opaque to the reference-drawing logic in Rule.
680+
def __with_transform(self, name, f):
681+
return Bundle(
682+
self.name,
683+
consume=self.consume,
684+
draw_references=self.draw_references,
685+
transformations=(*self._transformations, (name, f)),
686+
)
687+
688+
def map(self, pack):
689+
return self.__with_transform("map", pack)
690+
691+
def filter(self, condition):
692+
return self.__with_transform("filter", condition)
693+
694+
def _base_repr(self):
695+
consume = ", consume=True" if self.consume else ""
696+
return f"Bundle(name={self.name!r}{consume})"
624697

625698
def __repr__(self):
626-
if self.consume is False:
627-
return f"Bundle(name={self.name!r})"
628-
return f"Bundle(name={self.name!r}, consume={self.consume!r})"
699+
transforms = "".join(
700+
f".{name}({get_pretty_function_description(f)})"
701+
for name, f in self._transformations
702+
)
703+
return self._base_repr() + transforms
629704

630705
def calc_is_empty(self, recur):
631706
# We assume that a bundle will grow over time
@@ -638,13 +713,6 @@ def is_currently_empty(self, data):
638713
machine = data.draw(self_strategy)
639714
return not bool(machine.bundle(self.name))
640715

641-
def flatmap(self, expand):
642-
if self.draw_references:
643-
return Bundle(
644-
self.name, consume=self.consume, draw_references=False
645-
).flatmap(expand)
646-
return super().flatmap(expand)
647-
648716
def __hash__(self):
649717
# Making this hashable means we hit the fast path of "everything is
650718
# hashable" in st.sampled_from label calculation when sampling which rule
@@ -669,7 +737,7 @@ def consumes(bundle: Bundle[Ex]) -> SearchStrategy[Ex]:
669737
"""
670738
if not isinstance(bundle, Bundle):
671739
raise TypeError("Argument to be consumed must be a bundle.")
672-
return Bundle(bundle.name, consume=True)
740+
return Bundle(bundle.name, consume=True, transformations=bundle._transformations)
673741

674742

675743
@dataclass(slots=True, frozen=True)

0 commit comments

Comments
 (0)