Merge branch 'master' into 314

Author: Liam-DeVoe

.github/workflows/main.yml

@@ -103,6 +103,7 @@ jobs:
           - check-crosshair-custom-nocover/test_[j-r]*
           - check-crosshair-custom-nocover/test_[s-z]*
           # - check-crosshair-niche
+          - check-threading
           - check-py39-oldestnumpy
           - check-numpy-nightly
       fail-fast: false
@@ -203,7 +204,8 @@ jobs:
         pip install -r requirements/crosshair.txt
         pip install hypothesis-python/
     - name: Run tests
-      run: python -m pytest --numprocesses auto ${{ matrix.whichtests == 'nocover' && 'hypothesis-python/tests/nocover' || 'hypothesis-python/tests/ --ignore=hypothesis-python/tests/nocover/ --ignore=hypothesis-python/tests/quality/ --ignore=hypothesis-python/tests/ghostwriter/ --ignore=hypothesis-python/tests/patching/' }}
+      # remove this ignore when https://github.com/pschanely/hypothesis-crosshair/issues/40 is fixed
+      run: python -m pytest -W "ignore:hypothesis.internal.observability.TESTCASE_CALLBACKS is deprecated" --numprocesses auto ${{ matrix.whichtests == 'nocover' && 'hypothesis-python/tests/nocover' || 'hypothesis-python/tests/ --ignore=hypothesis-python/tests/nocover/ --ignore=hypothesis-python/tests/quality/ --ignore=hypothesis-python/tests/ghostwriter/ --ignore=hypothesis-python/tests/patching/' }}
 
   test-osx:
     runs-on: macos-latest

.github/workflows/website.yml

@@ -0,0 +1,41 @@
+name: Build website & deploy to GitHub Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["master"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build website
+        run: ./build.sh website
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'website/output/'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

hypothesis-python/RELEASE-sample.rst

@@ -27,7 +27,7 @@ which should:
   - :class:`package.class` for link to classes (abbreviated as above).
   - :issue:`issue-number` for referencing issues.
   - Similarly, :pull:`pr-number` can be used for PRs, but it's usually
-    preferred to refer to version numbers such as :ref:`version 6.98.9 <v6.98.9>,
+    preferred to refer to version numbers with :v:`6.98.9`,
     as they are meaningful to end users.
   - :doc:`link text <chapter#anchor>` for documentation references.
   - `link text <https://hypothesis.readthedocs.io/en/latest/chapter.html#anchor>`__

hypothesis-python/docs/changelog.rst

@@ -18,6 +18,48 @@ Hypothesis 6.x
 
     .. include:: ../RELEASE.rst
 
+.. _v6.137.1:
+
+--------------------
+6.137.1 - 2025-08-05
+--------------------
+
+Fixes a bug with solver-based :ref:`alternative backends <alternative-backends>` (like `crosshair <https://github.com/pschanely/CrossHair>`_) where symbolic values passed to |event| would not be realized to concrete values at the end of the test case.
+
+.. _v6.137.0:
+
+--------------------
+6.137.0 - 2025-08-05
+--------------------
+
+Add the |add_observability_callback|, |remove_observability_callback|, |with_observability_callback|, and |observability_enabled| methods to the :ref:`observability <observability>` interface. The previous |TESTCASE_CALLBACKS| is deprecated.
+
+This release also adds better threading support to observability callbacks. An observability callback will now only be called for observations generated by the same thread.
+
+.. _v6.136.9:
+
+--------------------
+6.136.9 - 2025-08-04
+--------------------
+
+Fix a threading race condition in |st.one_of| initialization.
+
+.. _v6.136.8:
+
+--------------------
+6.136.8 - 2025-08-04
+--------------------
+
+Improve the error messages and documentation for |HealthCheck|. Among others, the messaging is now more clear that health checks are proactive warnings, not correctness errors.
+
+.. _v6.136.7:
+
+--------------------
+6.136.7 - 2025-08-01
+--------------------
+
+Improve detection of sys.monitoring to avoid errors on GraalPy.
+
 .. _v6.136.6:
 
 --------------------

hypothesis-python/docs/compatibility.rst

@@ -1,4 +1,3 @@
-=============
 Compatibility
 =============
 
@@ -7,7 +6,6 @@ possibly need it to be compatible with. Generally you should just try it and
 expect it to work. If it doesn't, you can be surprised and check this document
 for the details.
 
--------------------
 Hypothesis versions
 -------------------
 
@@ -24,7 +22,6 @@ changes in patch releases.
 
 .. _deprecation-policy:
 
-------------
 Deprecations
 ------------
 
@@ -41,7 +38,6 @@ exactly where an error came from, or turn only our warnings into errors.
 .. autoclass:: hypothesis.errors.HypothesisDeprecationWarning
 
 
----------------
 Python versions
 ---------------
 
@@ -55,7 +51,6 @@ patch release of any version of Python it supports. Earlier releases should work
 and bugs in them will get fixed if reported, but they're not tested in CI and
 no guarantees are made.
 
------------------
 Operating systems
 -----------------
 
@@ -69,7 +64,6 @@ operating system it probably won't stay fixed due to the inevitable march of tim
 
 .. _framework-compatibility:
 
-------------------
 Testing frameworks
 ------------------
 
@@ -106,7 +100,6 @@ In terms of what's actually *known* to work:
 * :pypi:`coverage` works out of the box with Hypothesis; our own test suite has
   100% branch coverage.
 
------------------
 Optional packages
 -----------------
 
@@ -117,23 +110,33 @@ all versions that are supported upstream.
 
 .. _thread-safety-policy:
 
---------------------
 Thread-Safety Policy
 --------------------
 
-As discussed in :issue:`2719`, Hypothesis is not truly thread-safe and that's unlikely to change in the future.  This policy therefore describes what you *can* expect if you use Hypothesis with multiple threads.
+As of :version:`6.136.9`, Hypothesis is thread-safe. Each of the following is fully supported, and tested regularly in CI:
 
-**Running tests in multiple processes**, e.g. with ``pytest -n auto``, is fully supported and we test this regularly in CI - thanks to process isolation, we only need to ensure that :class:`~hypothesis.database.DirectoryBasedExampleDatabase` can't tread on its own toes too badly.  If you find a bug here we will fix it ASAP.
+* Running tests in multiple processes
+* Running separate tests in multiple threads
+* Running the same test in multiple threads
 
-**Running separate tests in multiple threads** is not something we design or test for, and is not formally supported.  That said, anecdotally it does mostly work and we would like it to keep working - we accept reasonable patches and low-priority bug reports.  The main risks here are global state, shared caches, and cached strategies.
+If you find a bug here, please report it. The main risks internally are global state, shared caches, and cached strategies.
 
-**Running the same test in multiple threads**, or using multiple threads within the same test, makes it pretty easy to trigger internal errors.  We usually accept patches for such issues unless readability or single-thread performance suffer.
+Thread usage inside tests
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Hypothesis assumes that tests are single-threaded, or do a sufficiently-good job of pretending to be single-threaded.  Tests that use helper threads internally should be OK, but the user must be careful to ensure that test outcomes are still deterministic. In particular it counts as nondeterministic if helper-thread timing changes the sequence of dynamic draws using e.g. the |st.data| strategy.
+.. TODO_DOCS: link to not-yet-merged flaky failure tutorial page
 
-Interacting with any Hypothesis APIs from helper threads might do weird/bad things, so avoid that too - we rely on thread-local variables in a few places, and haven't explicitly tested/audited how they respond to cross-thread API calls.  While |st.data| and equivalents are the most obvious danger, other APIs might also be subtly affected.
+Tests that spawn threads internally are supported by Hypothesis.
+
+However, these as with any Hypothesis test, these tests must have deterministic test outcomes and data generation. For example, if timing changes in the threads change the sequence of dynamic draws from |st.composite| or |st.data|, Hypothesis may report the test as flaky. The solution here is to refactor data generation so it does not depend on test timings.
+
+Cross-thread API calls
+~~~~~~~~~~~~~~~~~~~~~~
+
+In theory, Hypothesis supports cross-thread API calls, for instance spawning a thread inside of a test and using that to draw from |st.composite| or |st.data|, or to call |event|, |target|, or |assume|.
+
+However, we have not explicitly audited this behavior, and do not regularly test it in our CI. If you find a bug here, please report it. If our investigation determines that we cannot support cross-thread calls for the feature in question, we will update this page accordingly.
 
-----------
 Type hints
 ----------
 

hypothesis-python/docs/conf.py

@@ -14,6 +14,9 @@
 import types
 from pathlib import Path
 
+from docutils import nodes
+from sphinx.util.docutils import SphinxRole
+
 root = Path(__file__).parent.parent
 sys.path.append(str(root / "src"))
 sys.path.append(str(Path(__file__).parent / "_ext"))
@@ -87,6 +90,22 @@
 release = _d["__version__"]
 
 
+# custom role for version syntaxes.
+# :v:`6.131.0`       = [v6.131.0](changelog.html#v6.13.0)
+# :version:`6.131.0` = [version 6.131.0](changelog.html#v6.13.0)
+class VersionRole(SphinxRole):
+    def __init__(self, prefix):
+        self.prefix = prefix
+
+    def run(self):
+        node = nodes.reference(
+            "",
+            f"{self.prefix}{self.text}",
+            refuri=f"changelog.html#v{self.text.replace('.', '-')}",
+        )
+        return [node], []
+
+
 def setup(app):
     if root.joinpath("RELEASE.rst").is_file():
         app.tags.add("has_release_file")
@@ -131,6 +150,8 @@ def process_signature(app, what, name, obj, options, signature, return_annotatio
         return signature, return_annotation
 
     app.connect("autodoc-process-signature", process_signature)
+    app.add_role("v", VersionRole(prefix="v"))
+    app.add_role("version", VersionRole(prefix="version "))
 
 
 language = "en"

hypothesis-python/docs/prolog.rst

@@ -104,10 +104,13 @@
 .. |settings.load_profile| replace:: :func:`~hypothesis.settings.load_profile`
 
 .. |SearchStrategy| replace:: :class:`~hypothesis.strategies.SearchStrategy`
+.. |filter| replace:: :func:`.filter() <hypothesis.strategies.SearchStrategy.filter>`
 .. |.filter| replace:: :func:`.filter() <hypothesis.strategies.SearchStrategy.filter>`
 .. |.filter()| replace:: :func:`.filter() <hypothesis.strategies.SearchStrategy.filter>`
+.. |flatmap| replace:: :func:`.flatmap() <hypothesis.strategies.SearchStrategy.flatmap>`
 .. |.flatmap| replace:: :func:`.flatmap() <hypothesis.strategies.SearchStrategy.flatmap>`
 .. |.flatmap()| replace:: :func:`.flatmap() <hypothesis.strategies.SearchStrategy.flatmap>`
+.. |map| replace:: :func:`.map() <hypothesis.strategies.SearchStrategy.map>`
 .. |.map| replace:: :func:`.map() <hypothesis.strategies.SearchStrategy.map>`
 .. |.map()| replace:: :func:`.map() <hypothesis.strategies.SearchStrategy.map>`
 .. |.example()| replace:: :func:`.example() <hypothesis.strategies.SearchStrategy.example>`
@@ -128,6 +131,11 @@
 .. |PrimitiveProvider.span_end| replace:: :func:`~hypothesis.internal.conjecture.providers.PrimitiveProvider.span_end`
 
 .. |AVAILABLE_PROVIDERS| replace:: :data:`~hypothesis.internal.conjecture.providers.AVAILABLE_PROVIDERS`
+
+.. |add_observability_callback| replace:: :data:`~hypothesis.internal.observability.add_observability_callback`
+.. |remove_observability_callback| replace:: :data:`~hypothesis.internal.observability.remove_observability_callback`
+.. |with_observability_callback| replace:: :data:`~hypothesis.internal.observability.with_observability_callback`
+.. |observability_enabled| replace:: :data:`~hypothesis.internal.observability.observability_enabled`
 .. |TESTCASE_CALLBACKS| replace:: :data:`~hypothesis.internal.observability.TESTCASE_CALLBACKS`
 .. |OBSERVABILITY_CHOICES| replace:: :data:`~hypothesis.internal.observability.OBSERVABILITY_CHOICES`
 .. |BUFFER_SIZE| replace:: :data:`~hypothesis.internal.conjecture.engine.BUFFER_SIZE`

hypothesis-python/docs/reference/api.rst

@@ -478,7 +478,7 @@ Note that the interpretation of both input and output bytestrings is specific to
 Interaction with settings
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``fuzz_one_input`` uses just enough of Hypothesis' internals to drive your test function with a fuzzer-provided bytestring, and most settings therefore have no effect in this mode.  We recommend running your tests the usual way before fuzzing to get the benefits of healthchecks, as well as afterwards to replay, shrink, deduplicate, and report whatever errors were discovered.
+``fuzz_one_input`` uses just enough of Hypothesis' internals to drive your test function with a fuzzer-provided bytestring, and most settings therefore have no effect in this mode.  We recommend running your tests the usual way before fuzzing to get the benefits of health checks, as well as afterwards to replay, shrink, deduplicate, and report whatever errors were discovered.
 
 - The :obj:`~hypothesis.settings.database` setting *is* used by fuzzing mode - adding failures to the database to be replayed when you next run your tests is our preferred reporting mechanism and response to `the 'fuzzer taming' problem <https://blog.regehr.org/archives/925>`__.
 - The :obj:`~hypothesis.settings.verbosity` and :obj:`~hypothesis.settings.stateful_step_count` settings work as usual.

hypothesis-python/docs/reference/index.rst

@@ -3,7 +3,7 @@ API Reference
 
 The technical API reference for Hypothesis is split into four pages:
 
-* :doc:`API Reference </reference/api>`. Non-strategy Hypothesis objects, classes, and functions.
+* :doc:`API Reference </reference/api>`. Non-strategy Hypothesis objects, classes, and functions. |@given| and others live here.
 * :doc:`Strategies Reference </reference/strategies>`. Hypothesis strategies, including for :doc:`extras </extras>`.
 * :doc:`Integrations Reference </reference/integrations>`. Features with a defined interface, but no code API.
 * :doc:`Hypothesis internals </reference/internals>`. Internal APIs for developers building tools, libraries, or research on top of Hypothesis.

hypothesis-python/docs/reference/internals.rst

@@ -30,6 +30,11 @@ Alternative backends
 Observability
 -------------
 
+.. autofunction:: hypothesis.internal.observability.add_observability_callback
+.. autofunction:: hypothesis.internal.observability.remove_observability_callback
+.. autofunction:: hypothesis.internal.observability.with_observability_callback
+.. autofunction:: hypothesis.internal.observability.observability_enabled
+
 .. autodata:: hypothesis.internal.observability.TESTCASE_CALLBACKS
 .. autodata:: hypothesis.internal.observability.OBSERVABILITY_COLLECT_COVERAGE
 .. autodata:: hypothesis.internal.observability.OBSERVABILITY_CHOICES