Skip to content

Improve @example docs #4418

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
May 30, 2025
Merged

Improve @example docs #4418

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
db1e2fd
clean up docs
tybug May 29, 2025
3f3953e
move currently_in_test_context
tybug May 29, 2025
5f1e9d1
move @example docs to source code
tybug May 29, 2025
edec80b
add release notes
tybug May 29, 2025
d436cd2
rewrite @given arguments docs
tybug May 29, 2025
df1130b
drop .via prefix docs
tybug May 29, 2025
facb0de
update infer docs
tybug May 29, 2025
78aa433
address review
tybug May 29, 2025
5ea4b68
move "reproducing inputs"
tybug May 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions hypothesis-python/RELEASE.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
RELEASE_TYPE: patch

Improve documentation of |@example|.
5 changes: 2 additions & 3 deletions hypothesis-python/docs/changelog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6925,8 +6925,7 @@ This release consists of some internal refactoring to the shrinker in preparatio
5.18.0 - 2020-06-22
-------------------

This release teaches Hypothesis to :ref:`shorten tracebacks <v3.79.2>` for
:ref:`explicit examples <providing-explicit-examples>`, as we already do
This release teaches Hypothesis to :ref:`shorten tracebacks <v3.79.2>` for |@example|, as we already do
for generated examples, so that you can focus on your code rather than ours.

If you have multiple failing explicit examples, they will now all be reported.
Expand Down Expand Up @@ -10874,7 +10873,7 @@ and adds a CI check so we don't add new ones.
This patch fixes two bugs (:issue:`944` and :issue:`1521`), where messages
about :func:`@seed <hypothesis.seed>` did not check the current verbosity
setting, and the wrong settings were active while executing
:ref:`explicit examples <providing-explicit-examples>`.
explicit examples from |@example|.

.. _v3.71.5:

Expand Down
165 changes: 2 additions & 163 deletions hypothesis-python/docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ def setup(app):


language = "en"
exclude_patterns = ["_build"]
exclude_patterns = ["_build", "prolog.rst"]
pygments_style = "sphinx"
todo_include_todos = False

Expand Down Expand Up @@ -166,168 +166,7 @@ def setup(app):

autodoc_mock_imports = ["numpy", "pandas", "redis", "django", "pytz"]

rst_prolog = """
.. |given| replace:: :func:`~hypothesis.given`
.. |@given| replace:: :func:`@given <hypothesis.given>`
.. |@example| replace:: :func:`@example <hypothesis.example>`
.. |@example.xfail| replace:: :func:`@example(...).xfail() <hypothesis.example.xfail>`
.. |@settings| replace:: :func:`@settings <hypothesis.settings>`
.. |settings| replace:: :func:`settings <hypothesis.settings>`
.. |@composite| replace:: :func:`@composite <hypothesis.strategies.composite>`
.. |assume| replace:: :func:`~hypothesis.assume`
.. |target| replace:: :func:`~hypothesis.target`
.. |event| replace:: :func:`~hypothesis.event`
.. |note| replace:: :func:`~hypothesis.note`

.. |max_examples| replace:: :obj:`~hypothesis.settings.max_examples`
.. |settings.max_examples| replace:: :obj:`settings.max_examples <hypothesis.settings.max_examples>`
.. |settings.database| replace:: :obj:`settings.database <hypothesis.settings.database>`
.. |settings.deadline| replace:: :obj:`settings.deadline <hypothesis.settings.deadline>`
.. |settings.derandomize| replace:: :obj:`settings.derandomize <hypothesis.settings.derandomize>`
.. |settings.phases| replace:: :obj:`settings.phases <hypothesis.settings.phases>`
.. |settings.print_blob| replace:: :obj:`settings.print_blob <hypothesis.settings.print_blob>`
.. |settings.report_multiple_bugs| replace:: :obj:`settings.report_multiple_bugs <hypothesis.settings.report_multiple_bugs>`
.. |settings.verbosity| replace:: :obj:`settings.verbosity <hypothesis.settings.verbosity>`
.. |settings.suppress_health_check| replace:: \
:obj:`settings.suppress_health_check <hypothesis.settings.suppress_health_check>`
.. |settings.stateful_step_count| replace:: :obj:`settings.stateful_step_count <hypothesis.settings.stateful_step_count>`
.. |settings.backend| replace:: :obj:`settings.backend <hypothesis.settings.backend>`

.. |~settings.max_examples| replace:: :obj:`~hypothesis.settings.max_examples`
.. |~settings.database| replace:: :obj:`~hypothesis.settings.database`
.. |~settings.deadline| replace:: :obj:`~hypothesis.settings.deadline`
.. |~settings.derandomize| replace:: :obj:`~hypothesis.settings.derandomize`
.. |~settings.phases| replace:: :obj:`~hypothesis.settings.phases`
.. |~settings.print_blob| replace:: :obj:`~hypothesis.settings.print_blob`
.. |~settings.report_multiple_bugs| replace:: :obj:`~hypothesis.settings.report_multiple_bugs`
.. |~settings.verbosity| replace:: :obj:`~hypothesis.settings.verbosity`
.. |~settings.suppress_health_check| replace:: :obj:`~hypothesis.settings.suppress_health_check`
.. |~settings.stateful_step_count| replace:: :obj:`~hypothesis.settings.stateful_step_count`
.. |~settings.backend| replace:: :obj:`~hypothesis.settings.backend`

.. |HealthCheck.data_too_large| replace:: :obj:`HealthCheck.data_too_large <hypothesis.HealthCheck.data_too_large>`
.. |HealthCheck.filter_too_much| replace:: :obj:`HealthCheck.filter_too_much <hypothesis.HealthCheck.filter_too_much>`
.. |HealthCheck.too_slow| replace:: :obj:`HealthCheck.too_slow <hypothesis.HealthCheck.too_slow>`
.. |HealthCheck.function_scoped_fixture| replace:: \
:obj:`HealthCheck.function_scoped_fixture <hypothesis.HealthCheck.function_scoped_fixture>`
.. |HealthCheck.differing_executors| replace:: \
:obj:`HealthCheck.differing_executors <hypothesis.HealthCheck.differing_executors>`
.. |HealthCheck| replace:: :obj:`~hypothesis.HealthCheck`

.. |Phase| replace:: :obj:`Phase <hypothesis.Phase>`
.. |Phase.explicit| replace:: :obj:`Phase.explicit <hypothesis.Phase.explicit>`
.. |Phase.reuse| replace:: :obj:`Phase.reuse <hypothesis.Phase.reuse>`
.. |Phase.generate| replace:: :obj:`Phase.generate <hypothesis.Phase.generate>`
.. |Phase.target| replace:: :obj:`Phase.target <hypothesis.Phase.target>`
.. |Phase.shrink| replace:: :obj:`Phase.shrink <hypothesis.Phase.shrink>`
.. |Phase.explain| replace:: :obj:`Phase.explain <hypothesis.Phase.explain>`

.. |Verbosity| replace:: :obj:`~hypothesis.Verbosity`
.. |Verbosity.verbose| replace:: :obj:`Verbosity.verbose <hypothesis.Verbosity.verbose>`
.. |Verbosity.debug| replace:: :obj:`Verbosity.debug <hypothesis.Verbosity.debug>`
.. |Verbosity.normal| replace:: :obj:`Verbosity.normal <hypothesis.Verbosity.normal>`
.. |Verbosity.quiet| replace:: :obj:`Verbosity.quiet <hypothesis.Verbosity.quiet>`

.. |InvalidArgument| replace:: :obj:`InvalidArgument <hypothesis.errors.InvalidArgument>`
.. |DidNotReproduce| replace:: :obj:`DidNotReproduce <hypothesis.errors.DidNotReproduce>`

.. |st.lists| replace:: :func:`~hypothesis.strategies.lists`
.. |st.integers| replace:: :func:`~hypothesis.strategies.integers`
.. |st.floats| replace:: :func:`~hypothesis.strategies.floats`
.. |st.booleans| replace:: :func:`~hypothesis.strategies.booleans`
.. |st.none| replace:: :func:`~hypothesis.strategies.none`
.. |st.composite| replace:: :func:`@composite <hypothesis.strategies.composite>`
.. |st.data| replace:: :func:`~hypothesis.strategies.data`
.. |st.one_of| replace:: :func:`~hypothesis.strategies.one_of`
.. |st.text| replace:: :func:`~hypothesis.strategies.text`
.. |st.characters| replace:: :func:`~hypothesis.strategies.characters`
.. |st.tuples| replace:: :func:`~hypothesis.strategies.tuples`
.. |st.sets| replace:: :func:`~hypothesis.strategies.sets`
.. |st.dictionaries| replace:: :func:`~hypothesis.strategies.dictionaries`
.. |st.fixed_dictionaries| replace:: :func:`~hypothesis.strategies.fixed_dictionaries`
.. |st.datetimes| replace:: :func:`~hypothesis.strategies.datetimes`
.. |st.builds| replace:: :func:`~hypothesis.strategies.builds`
.. |st.recursive| replace:: :func:`~hypothesis.strategies.recursive`
.. |st.deferred| replace:: :func:`~hypothesis.strategies.deferred`
.. |st.from_type| replace:: :func:`~hypothesis.strategies.from_type`
.. |st.sampled_from| replace:: :func:`~hypothesis.strategies.sampled_from`
.. |st.uuids| replace:: :func:`~hypothesis.strategies.uuids`
.. |st.ip_addresses| replace:: :func:`~hypothesis.strategies.ip_addresses`
.. |st.register_type_strategy| replace:: :func:`~hypothesis.strategies.register_type_strategy`
.. |st.just| replace:: :func:`~hypothesis.strategies.just`
.. |st.domains| replace:: :func:`~hypothesis.provisional.domains`
.. |st.urls| replace:: :func:`~hypothesis.provisional.urls`

.. |django.from_form| replace:: :func:`~hypothesis.extra.django.from_form`
.. |django.from_model| replace:: :func:`~hypothesis.extra.django.from_model`
.. |django.from_field| replace:: :func:`~hypothesis.extra.django.from_field`

.. |settings.register_profile| replace:: :func:`~hypothesis.settings.register_profile`
.. |settings.get_profile| replace:: :func:`~hypothesis.settings.get_profile`
.. |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>`
.. |.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>`
.. |.example()| replace:: :func:`.example() <hypothesis.strategies.SearchStrategy.example>`

.. |PrimitiveProvider| replace:: :class:`~hypothesis.internal.conjecture.providers.PrimitiveProvider`
.. |PrimitiveProvider.realize| replace:: :func:`~hypothesis.internal.conjecture.providers.PrimitiveProvider.realize`
.. |PrimitiveProvider.draw_integer| replace:: \
:func:`~hypothesis.internal.conjecture.providers.PrimitiveProvider.draw_integer`
.. |PrimitiveProvider.draw_boolean| replace:: \
:func:`~hypothesis.internal.conjecture.providers.PrimitiveProvider.draw_boolean`
.. |PrimitiveProvider.draw_float| replace:: :func:`~hypothesis.internal.conjecture.providers.PrimitiveProvider.draw_float`
.. |PrimitiveProvider.draw_string| replace:: :func:`~hypothesis.internal.conjecture.providers.PrimitiveProvider.draw_string`
.. |PrimitiveProvider.draw_bytes| replace:: :func:`~hypothesis.internal.conjecture.providers.PrimitiveProvider.draw_bytes`

.. |AVAILABLE_PROVIDERS| replace:: :data:`~hypothesis.internal.conjecture.providers.AVAILABLE_PROVIDERS`
.. |TESTCASE_CALLBACKS| replace:: :data:`~hypothesis.internal.observability.TESTCASE_CALLBACKS`
.. |BUFFER_SIZE| replace:: :data:`~hypothesis.internal.conjecture.engine.BUFFER_SIZE`
.. |MAX_SHRINKS| replace:: :data:`~hypothesis.internal.conjecture.engine.MAX_SHRINKS`
.. |MAX_SHRINKING_SECONDS| replace:: :data:`~hypothesis.internal.conjecture.engine.MAX_SHRINKING_SECONDS`
.. |BackendCannotProceed| replace:: :exc:`~hypothesis.errors.BackendCannotProceed`

.. |@rule| replace:: :func:`@rule <hypothesis.stateful.rule>`
.. |RuleBasedStateMachine| replace:: :class:`~hypothesis.stateful.RuleBasedStateMachine`

.. |@reproduce_failure| replace:: :func:`@reproduce_failure <hypothesis.reproduce_failure>`
.. |@seed| replace:: :func:`@seed <hypothesis.seed>`

.. |ExampleDatabase| replace:: :class:`~hypothesis.database.ExampleDatabase`
.. |ExampleDatabase.save| replace:: :func:`~hypothesis.database.ExampleDatabase.save`
.. |ExampleDatabase.delete| replace:: :func:`~hypothesis.database.ExampleDatabase.delete`
.. |ExampleDatabase.fetch| replace:: :func:`~hypothesis.database.ExampleDatabase.fetch`
.. |ExampleDatabase.move| replace:: :func:`~hypothesis.database.ExampleDatabase.move`
.. |ExampleDatabase.add_listener| replace:: :func:`~hypothesis.database.ExampleDatabase.add_listener`
.. |ExampleDatabase.remove_listener| replace:: :func:`~hypothesis.database.ExampleDatabase.remove_listener`
.. |ExampleDatabase.clear_listeners| replace:: :func:`~hypothesis.database.ExampleDatabase.clear_listeners`
.. |ExampleDatabase._start_listening| replace:: :func:`~hypothesis.database.ExampleDatabase._start_listening`
.. |ExampleDatabase._stop_listening| replace:: :func:`~hypothesis.database.ExampleDatabase._stop_listening`
.. |ExampleDatabase._broadcast_change| replace:: :func:`~hypothesis.database.ExampleDatabase._broadcast_change`

.. |DirectoryBasedExampleDatabase| replace:: :class:`~hypothesis.database.DirectoryBasedExampleDatabase`
.. |InMemoryExampleDatabase| replace:: :class:`~hypothesis.database.InMemoryExampleDatabase`
.. |ReadOnlyDatabase| replace:: :class:`~hypothesis.database.ReadOnlyDatabase`
.. |MultiplexedDatabase| replace:: :class:`~hypothesis.database.MultiplexedDatabase`
.. |GitHubArtifactDatabase| replace:: :class:`~hypothesis.database.GitHubArtifactDatabase`
.. |BackgroundWriteDatabase| replace:: :class:`~hypothesis.database.BackgroundWriteDatabase`
.. |RedisExampleDatabase| replace:: :class:`~hypothesis.extra.redis.RedisExampleDatabase`

.. |is_hypothesis_test| replace:: :func:`~hypothesis.is_hypothesis_test`

.. |str| replace:: :obj:`python:str`
.. |int| replace:: :obj:`python:int`
.. |bool| replace:: :obj:`python:bool`
.. |bytes| replace:: :obj:`python:bytes`
.. |float| replace:: :obj:`python:float`
.. |assert| replace:: :keyword:`python:assert`
.. |dataclasses| replace:: :mod:`python:dataclasses`
"""
rst_prolog = (Path(__file__).parent / "prolog.rst").read_text()

codeautolink_autodoc_inject = False
codeautolink_global_preface = """
Expand Down
19 changes: 8 additions & 11 deletions hypothesis-python/docs/extensions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,10 +126,7 @@ standard library. Strategies for other things are also welcome; anything with
external dependencies just goes in ``hypothesis.extra``.

Tools such as assertion helpers may also need to check whether the current
test is using Hypothesis:

.. autofunction:: hypothesis.currently_in_test_context

test is using Hypothesis. For that, see |currently_in_test_context|.

.. _entry-points:

Expand All @@ -139,9 +136,9 @@ Hypothesis integration via entry points

If you would like to ship Hypothesis strategies for a custom type - either as
part of the upstream library, or as a third-party extension, there's a catch:
:func:`~hypothesis.strategies.from_type` only works after the corresponding
call to :func:`~hypothesis.strategies.register_type_strategy`, and you'll have
the same problem with :func:`~hypothesis.register_random`. This means that
|st.from_type| only works after the corresponding
call to |st.register_type_strategy|, and you'll have
the same problem with |register_random|. This means that
either

- you have to try importing Hypothesis to register the strategy when *your*
Expand Down Expand Up @@ -251,9 +248,9 @@ Hypothesis includes the following backends:
hypothesis
The default backend.
hypothesis-urandom
The same as the default backend, but uses ``/dev/urandom`` to back the randomness
behind its PRNG. The only reason to use this backend over the default is if you are also
using `Antithesis <https://antithesis.com/>`_, in which case this enables Antithesis
The same as the default backend, but uses ``/dev/urandom`` as its source of randomness,
instead of the standard PRNG in |random.Random|. The only reason to use this backend over the default ``backend="hypothesis"`` is if you are also
using `Antithesis <https://antithesis.com/>`_, in which case this allows Antithesis
mutation of ``/dev/urandom`` to control the values generated by Hypothesis.

``/dev/urandom`` is not available on Windows, so we emit a warning and fall back to the
Expand All @@ -264,7 +261,7 @@ crosshair

Requires ``pip install hypothesis[crosshair]``.

You can change the backend for a test with the ``backend`` setting. For instance, after
You can change the backend for a test with the |settings.backend| setting. For instance, after
``pip install hypothesis[crosshair]``, you can use :pypi:`crosshair <crosshair-tool>` to
generate examples with SMT via the :pypi:`hypothesis-crosshair` backend:

Expand Down
4 changes: 2 additions & 2 deletions hypothesis-python/docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ Hypothesis is the property-based testing library for Python. With Hypothesis, yo

You should start with the :doc:`tutorial <tutorial/index>`, or the more condensed :doc:`quickstart <quickstart>`.

.. rst-class:: clearfix row
.. rst-class:: row

.. rst-class:: column column2 top-left

Expand Down Expand Up @@ -90,7 +90,7 @@ Commentary oriented towards deepening your understanding of Hypothesis.

Technical API reference.

.. rst-class:: clearfix row
.. rst-class:: row

.. toctree::
:maxdepth: 1
Expand Down
Loading