hypothesis: add docs and overloads.

Author: pradeep90

CHANGELOG.md

@@ -27,6 +27,7 @@ See [0Ver](https://0ver.org/).
 ### Features
 
 - Make `hypothesis` plugin test laws from user-defined interfaces too
+- Make `hypothesis` plugin accept user-defined strategies
 
 ### Bugfixes
 

docs/pages/contrib/hypothesis_plugins.rst

@@ -140,6 +140,27 @@ like ``Future``, ``ReaderFutureResult``, etc
 that have complex ``__init__`` signatures.
 And we don't want to mess with them.
 
+You can also register a custom strategy to be used when running your
+container's laws:
+
+.. code:: python
+
+
+  from hypothesis import strategies as st
+
+  check_all_laws(Number, container_strategy=st.builds(Number, st.integers()))
+
+The ``container_strategy`` will be used only when running the tests generated
+by the ``check_all_laws`` call above. It will have no effect on any other
+property tests that involve ``Number``. You cannot use this argument together
+with ``use_init``.
+
+Warning::
+  Avoid directly registering your container's strategy with ``hypothesis``
+  using ``st.register_type_strategy``. Because of the way we emulate
+  higher-kinded types, ``hypothesis`` may mistakenly use the strategy
+  for other incompatible containers and cause spurious test failures.
+
 Warning::
   Checking laws is not compatible with ``pytest-xdist``,
   because we use a lot of global mutable state there.

returns/contrib/hypothesis/laws.py

@@ -1,7 +1,7 @@
 import inspect
 from collections.abc import Callable, Iterator, Mapping
 from contextlib import ExitStack, contextmanager
-from typing import Any, NamedTuple, TypeGuard, TypeVar, final
+from typing import Any, NamedTuple, TypeGuard, TypeVar, final, overload
 
 import pytest
 from hypothesis import given
@@ -28,6 +28,24 @@ class Settings(NamedTuple):
     container_strategy: StrategyFactory | None
 
 
+@overload
+def check_all_laws(
+    container_type: type[Lawful[Example_co]],
+    *,
+    settings_kwargs: dict[str, Any] | None = None,
+    container_strategy: StrategyFactory[Example_co] | None = None,
+) -> None: ...
+
+
+@overload
+def check_all_laws(
+    container_type: type[Lawful[Example_co]],
+    *,
+    settings_kwargs: dict[str, Any] | None = None,
+    use_init: bool = False,
+) -> None: ...
+
+
 def check_all_laws(
     container_type: type[Lawful[Example_co]],
     *,