gh-107862: Add stateful, timezones and ip_addresses to the Hypothesis stubs

The stubs in test.support._hypothesis_stubs only cover the strategies
and decorators the existing property tests happen to use, so a test
that wants hypothesis.stateful, or the timezones() and ip_addresses()
strategies, fails to import when Hypothesis is not installed.

This adds those names. The stateful API has no equivalent of @example,
so there is nothing for the stub to replay: a state machine's TestCase
is skipped and run_state_machine_as_test raises SkipTest. The
decorators are accepted so that state machine classes can be defined
at import time.

Real Hypothesis only exposes hypothesis.stateful once the submodule has
been imported, so hypothesis_helper now imports it, making the
attribute available in both modes.

The stubs had no tests of their own, so this also adds
test_hypothesis_stubs, which checks the replay and skip behavior
directly and runs the API-shape checks against the real package when
it is importable.

Author: pganssle

Lib/test/support/_hypothesis_stubs/__init__.py

@@ -8,13 +8,14 @@
     "assume",
     "reject",
     "register_random",
+    "stateful",
     "strategies",
     "HealthCheck",
     "settings",
     "Verbosity",
 ]
 
-from . import strategies
+from . import stateful, strategies
 
 
 def given(*_args, **_kwargs):

Lib/test/support/_hypothesis_stubs/stateful.py

@@ -0,0 +1,96 @@
+"""Stubs for the subset of ``hypothesis.stateful`` used by the test suite.
+
+The stateful API has no equivalent of ``@example``, so without Hypothesis
+there is nothing to replay: the ``TestCase`` generated for a state machine
+is skipped, and ``run_state_machine_as_test`` raises ``unittest.SkipTest``.
+The decorators and helpers are accepted so that state machine classes can
+be defined at import time.
+"""
+import unittest
+
+from ._helpers import stub_factory
+from .strategies import StubStrategy
+
+__all__ = [
+    "Bundle",
+    "MultipleResults",
+    "RuleBasedStateMachine",
+    "consumes",
+    "initialize",
+    "invariant",
+    "multiple",
+    "precondition",
+    "rule",
+    "run_state_machine_as_test",
+]
+
+_SKIP_REASON = "Hypothesis required for stateful test"
+
+Bundle = stub_factory(StubStrategy, "hypothesis.stateful.Bundle")
+
+
+def consumes(bundle):
+    return bundle
+
+
+class MultipleResults:
+    def __init__(self, *values):
+        self.values = values
+
+
+def multiple(*args):
+    return MultipleResults(*args)
+
+
+def _identity_decorator(*_args, **_kwargs):
+    return lambda f: f
+
+
+rule = _identity_decorator
+initialize = _identity_decorator
+invariant = _identity_decorator
+
+
+def precondition(precond):
+    return lambda f: f
+
+
+class _TestCaseProperty:
+    """Build (and cache) a skipped ``unittest.TestCase`` per state machine."""
+
+    def __init__(self):
+        self._cases = {}
+
+    def __get__(self, obj, owner):
+        if owner not in self._cases:
+
+            class StateMachineTestCase(unittest.TestCase):
+                settings = None
+
+                def runTest(self):
+                    raise unittest.SkipTest(_SKIP_REASON)
+
+            StateMachineTestCase.__name__ = f"{owner.__name__}.TestCase"
+            StateMachineTestCase.__qualname__ = f"{owner.__qualname__}.TestCase"
+            self._cases[owner] = StateMachineTestCase
+        return self._cases[owner]
+
+
+class RuleBasedStateMachine:
+    TestCase = _TestCaseProperty()
+
+    def bundle(self, name):
+        return Bundle(name)
+
+    def check_invariants(self, settings, output, runtimes):
+        pass
+
+    def setup_state(self):
+        pass
+
+    def teardown(self):
+        pass
+
+
+def run_state_machine_as_test(state_machine_factory, *, settings=None):
+    raise unittest.SkipTest(_SKIP_REASON)

Lib/test/support/_hypothesis_stubs/strategies.py

@@ -44,6 +44,7 @@ def __or__(self, other):
     "frozensets",
     "functions",
     "integers",
+    "ip_addresses",
     "iterables",
     "just",
     "lists",
@@ -62,6 +63,8 @@ def __or__(self, other):
     "slices",
     "timedeltas",
     "times",
+    "timezone_keys",
+    "timezones",
     "text",
     "tuples",
     "uuids",

Lib/test/support/hypothesis_helper.py

@@ -2,6 +2,9 @@
 
 try:
     import hypothesis
+    # Real Hypothesis does not import this submodule on its own; do it here
+    # so that ``hypothesis.stateful`` is available in both modes.
+    import hypothesis.stateful
 except ImportError:
     from . import _hypothesis_stubs as hypothesis
 else:

Lib/test/test_hypothesis_stubs.py

@@ -0,0 +1,163 @@
+"""Tests for the Hypothesis stubs used when Hypothesis is not installed.
+
+The stubs are tested directly, so these tests run regardless of whether
+Hypothesis is available.  The API-shape tests also run against the real
+package when it is importable, to catch the stubs drifting from it.
+"""
+import unittest
+
+from test.support import _hypothesis_stubs as stubs
+from test.support import hypothesis_helper
+
+try:
+    import hypothesis
+    import hypothesis.stateful
+except ImportError:
+    hypothesis = None
+
+
+def _run(case_class):
+    """Run every test in ``case_class`` and return the ``TestResult``."""
+    result = unittest.TestResult()
+    unittest.defaultTestLoader.loadTestsFromTestCase(case_class).run(result)
+    return result
+
+
+class APIShapeMixin:
+    """Checks that hold for both the stubs and the real package."""
+
+    module = None
+
+    def test_new_strategies_exist(self):
+        st = self.module.strategies
+        for name in ("ip_addresses", "timezone_keys", "timezones"):
+            with self.subTest(name=name):
+                self.assertTrue(callable(getattr(st, name)))
+                self.assertIn(name, dir(st))
+
+    def test_stateful_names_exist(self):
+        stateful = self.module.stateful
+        for name in (
+            "Bundle",
+            "RuleBasedStateMachine",
+            "consumes",
+            "initialize",
+            "invariant",
+            "multiple",
+            "precondition",
+            "rule",
+            "run_state_machine_as_test",
+        ):
+            with self.subTest(name=name):
+                self.assertTrue(hasattr(stateful, name))
+
+    def test_state_machine_definition(self):
+        stateful = self.module.stateful
+        st = self.module.strategies
+
+        class Machine(stateful.RuleBasedStateMachine):
+            values = stateful.Bundle("values")
+
+            @stateful.initialize(target=values)
+            def start(self):
+                return stateful.multiple(1, 2)
+
+            @stateful.rule(target=values, x=st.integers())
+            def add(self, x):
+                return x
+
+            @stateful.precondition(lambda self: True)
+            @stateful.rule(x=stateful.consumes(values))
+            def remove(self, x):
+                pass
+
+            @stateful.invariant()
+            def check(self):
+                pass
+
+        self.assertTrue(issubclass(Machine.TestCase, unittest.TestCase))
+        self.assertIs(Machine.TestCase, Machine.TestCase)
+        self.assertTrue(hasattr(Machine.TestCase, "runTest"))
+        self.assertEqual(stateful.multiple(1, 2).values, (1, 2))
+
+
+class StubAPIShapeTests(APIShapeMixin, unittest.TestCase):
+    module = stubs
+
+
+@unittest.skipIf(hypothesis is None, "requires Hypothesis")
+class RealAPIShapeTests(APIShapeMixin, unittest.TestCase):
+    module = hypothesis
+
+
+class HelperTests(unittest.TestCase):
+    def test_helper_exposes_stateful(self):
+        # Real Hypothesis only has this attribute once the submodule has
+        # been imported, so the helper must do that in both modes.
+        self.assertTrue(hasattr(hypothesis_helper.hypothesis, "stateful"))
+        self.assertTrue(hasattr(hypothesis_helper.hypothesis, "strategies"))
+
+
+class StubBehaviorTests(unittest.TestCase):
+    def test_given_replays_examples(self):
+        seen = []
+
+        class Case(unittest.TestCase):
+            @stubs.example(x=1)
+            @stubs.example(x=2)
+            @stubs.given(x=stubs.strategies.integers())
+            def test_prop(self, x):
+                seen.append(x)
+
+        result = _run(Case)
+        self.assertEqual(result.testsRun, 1)
+        self.assertEqual(result.failures, [])
+        self.assertEqual(result.errors, [])
+        self.assertEqual(sorted(seen), [1, 2])
+
+    def test_given_without_examples_skips(self):
+        class Case(unittest.TestCase):
+            @stubs.given(x=stubs.strategies.integers())
+            def test_prop(self, x):
+                self.fail("should not run")
+
+        result = _run(Case)
+        self.assertEqual(result.testsRun, 1)
+        self.assertEqual(len(result.skipped), 1)
+
+    def test_strategy_repr_names_the_strategy(self):
+        self.assertEqual(
+            repr(stubs.strategies.timezones()),
+            "hypothesis.strategies.timezones()",
+        )
+        self.assertEqual(
+            repr(stubs.strategies.ip_addresses(v=4).map(str)),
+            "hypothesis.strategies.ip_addresses().map(str)",
+        )
+
+    def test_unknown_strategy_raises(self):
+        with self.assertRaises(AttributeError):
+            stubs.strategies.no_such_strategy
+
+    def test_state_machine_test_case_is_skipped(self):
+        class Machine(stubs.stateful.RuleBasedStateMachine):
+            @stubs.stateful.rule()
+            def step(self):
+                raise AssertionError("rules must not run without Hypothesis")
+
+        result = _run(Machine.TestCase)
+        self.assertEqual(result.testsRun, 1)
+        self.assertEqual(len(result.skipped), 1)
+        self.assertEqual(result.failures, [])
+        self.assertEqual(result.errors, [])
+
+    def test_run_state_machine_as_test_skips(self):
+        class Machine(stubs.stateful.RuleBasedStateMachine):
+            pass
+
+        with self.assertRaises(unittest.SkipTest):
+            stubs.stateful.run_state_machine_as_test(Machine)
+
+
+if __name__ == "__main__":
+    unittest.main()

Misc/NEWS.d/next/Tests/2026-10-19-17-05-00.gh-issue-107862.qH3sTa.rst

@@ -0,0 +1,3 @@
+Add ``hypothesis.stateful`` and the ``timezones()`` and ``ip_addresses()``
+strategies to the Hypothesis stubs used when Hypothesis is not installed, and
+add tests for the stubs.