From bb834e2b0608a51298414f6f6ebc389f87f79700 Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Wed, 9 Oct 2024 16:33:08 +0200 Subject: [PATCH 1/3] Docs: improve/cleanup reference from/to recwarn --- doc/en/builtin.rst | 3 +-- doc/en/how-to/capture-warnings.rst | 17 ++++++++--------- doc/en/reference/reference.rst | 3 ++- src/_pytest/recwarn.py | 3 +-- 4 files changed, 12 insertions(+), 14 deletions(-) diff --git a/doc/en/builtin.rst b/doc/en/builtin.rst index 9b406a6a512..822ee48b3fb 100644 --- a/doc/en/builtin.rst +++ b/doc/en/builtin.rst @@ -234,8 +234,7 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a recwarn -- .../_pytest/recwarn.py:35 Return a :class:`WarningsRecorder` instance that records all warnings emitted by test functions. - See https://docs.pytest.org/en/latest/how-to/capture-warnings.html for information - on warning categories. + See :ref:`warnings` for information on warning categories. tmp_path_factory [session scope] -- .../_pytest/tmpdir.py:242 Return a :class:`pytest.TempPathFactory` instance for the test session. diff --git a/doc/en/how-to/capture-warnings.rst b/doc/en/how-to/capture-warnings.rst index afabad5da14..0827c9a7fa9 100644 --- a/doc/en/how-to/capture-warnings.rst +++ b/doc/en/how-to/capture-warnings.rst @@ -195,7 +195,7 @@ user code and third-party libraries, as recommended by :pep:`565`. This helps users keep their code modern and avoid breakages when deprecated warnings are effectively removed. However, in the specific case where users capture any type of warnings in their test, either with -:func:`pytest.warns`, :func:`pytest.deprecated_call` or using the :ref:`recwarn ` fixture, +:func:`pytest.warns`, :func:`pytest.deprecated_call` or using the :func:`recwarn <_pytest.recwarn.recwarn>` fixture, no warning will be displayed at all. Sometimes it is useful to hide some specific deprecation warnings that happen in code that you have no control over @@ -332,10 +332,10 @@ additional information: assert record[0].message.args[0] == "another warning" Alternatively, you can examine raised warnings in detail using the -:ref:`recwarn ` fixture (see below). +:func:`recwarn <_pytest.recwarn.recwarn>` fixture (see :ref:`below `). -The :ref:`recwarn ` fixture automatically ensures to reset the warnings +The :func:`recwarn <_pytest.recwarn.recwarn>` fixture automatically ensures to reset the warnings filter at the end of the test, so no global state is leaked. .. _`recording warnings`: @@ -345,8 +345,8 @@ filter at the end of the test, so no global state is leaked. Recording warnings ------------------ -You can record raised warnings either using :func:`pytest.warns` or with -the ``recwarn`` fixture. +You can record raised warnings either using the :func:`pytest.warns` context manager or with +the :func:`recwarn <_pytest.recwarn.recwarn>` fixture. To record with :func:`pytest.warns` without asserting anything about the warnings, pass no arguments as the expected warning type and it will default to a generic Warning: @@ -361,7 +361,7 @@ pass no arguments as the expected warning type and it will default to a generic assert str(record[0].message) == "user" assert str(record[1].message) == "runtime" -The ``recwarn`` fixture will record warnings for the whole function: +The :func:`recwarn <_pytest.recwarn.recwarn>` fixture will record warnings for the whole function: .. code-block:: python @@ -377,12 +377,11 @@ The ``recwarn`` fixture will record warnings for the whole function: assert w.filename assert w.lineno -Both ``recwarn`` and :func:`pytest.warns` return the same interface for recorded -warnings: a WarningsRecorder instance. To view the recorded warnings, you can +Both the :func:`recwarn <_pytest.recwarn.recwarn>` fixture and the :func:`pytest.warns` context manager return the same interface for recorded +warnings: a :class:`~_pytest.recwarn.WarningsRecorder` instance. To view the recorded warnings, you can iterate over this instance, call ``len`` on it to get the number of recorded warnings, or index into it to get a particular recorded warning. -Full API: :class:`~_pytest.recwarn.WarningsRecorder`. .. _`warns use cases`: diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index baf781d4356..b6ec5c65e1e 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -529,13 +529,14 @@ record_testsuite_property recwarn ~~~~~~~ -**Tutorial**: :ref:`assertwarnings` +**Tutorial**: :ref:`recwarn` .. autofunction:: _pytest.recwarn.recwarn() :no-auto-options: .. autoclass:: pytest.WarningsRecorder() :members: + :special-members: __getitem__, __iter__, __len__ .. fixture:: request diff --git a/src/_pytest/recwarn.py b/src/_pytest/recwarn.py index 85d8de84abb..0dc002edd94 100644 --- a/src/_pytest/recwarn.py +++ b/src/_pytest/recwarn.py @@ -35,8 +35,7 @@ def recwarn() -> Generator[WarningsRecorder]: """Return a :class:`WarningsRecorder` instance that records all warnings emitted by test functions. - See https://docs.pytest.org/en/latest/how-to/capture-warnings.html for information - on warning categories. + See :ref:`warnings` for information on warning categories. """ wrec = WarningsRecorder(_ispytest=True) with wrec: From 0c39cf1ecf6c0292f7061222b1ac26a41d27bf93 Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Wed, 9 Oct 2024 22:32:26 +0200 Subject: [PATCH 2/3] PR #12866 add changelog item --- changelog/12866.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog/12866.doc.rst diff --git a/changelog/12866.doc.rst b/changelog/12866.doc.rst new file mode 100644 index 00000000000..10af4baf462 --- /dev/null +++ b/changelog/12866.doc.rst @@ -0,0 +1 @@ +Improved cross-references concerning the :func:`recwarn <_pytest.recwarn.recwarn>` fixture. From 7cc8094f5f230a6c5dd896e7e5031b5d3514c9f6 Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Thu, 10 Oct 2024 09:12:57 +0200 Subject: [PATCH 3/3] Update to use "fixture" rst/sphinx role Co-authored-by: Bruno Oliveira --- changelog/12866.doc.rst | 2 +- doc/en/how-to/capture-warnings.rst | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/changelog/12866.doc.rst b/changelog/12866.doc.rst index 10af4baf462..865b2bbc600 100644 --- a/changelog/12866.doc.rst +++ b/changelog/12866.doc.rst @@ -1 +1 @@ -Improved cross-references concerning the :func:`recwarn <_pytest.recwarn.recwarn>` fixture. +Improved cross-references concerning the :fixture:`recwarn` fixture. diff --git a/doc/en/how-to/capture-warnings.rst b/doc/en/how-to/capture-warnings.rst index 0827c9a7fa9..44ed87508a3 100644 --- a/doc/en/how-to/capture-warnings.rst +++ b/doc/en/how-to/capture-warnings.rst @@ -195,7 +195,7 @@ user code and third-party libraries, as recommended by :pep:`565`. This helps users keep their code modern and avoid breakages when deprecated warnings are effectively removed. However, in the specific case where users capture any type of warnings in their test, either with -:func:`pytest.warns`, :func:`pytest.deprecated_call` or using the :func:`recwarn <_pytest.recwarn.recwarn>` fixture, +:func:`pytest.warns`, :func:`pytest.deprecated_call` or using the :fixture:`recwarn` fixture, no warning will be displayed at all. Sometimes it is useful to hide some specific deprecation warnings that happen in code that you have no control over @@ -332,10 +332,10 @@ additional information: assert record[0].message.args[0] == "another warning" Alternatively, you can examine raised warnings in detail using the -:func:`recwarn <_pytest.recwarn.recwarn>` fixture (see :ref:`below `). +:fixture:`recwarn` fixture (see :ref:`below `). -The :func:`recwarn <_pytest.recwarn.recwarn>` fixture automatically ensures to reset the warnings +The :fixture:`recwarn` fixture automatically ensures to reset the warnings filter at the end of the test, so no global state is leaked. .. _`recording warnings`: @@ -346,7 +346,7 @@ Recording warnings ------------------ You can record raised warnings either using the :func:`pytest.warns` context manager or with -the :func:`recwarn <_pytest.recwarn.recwarn>` fixture. +the :fixture:`recwarn` fixture. To record with :func:`pytest.warns` without asserting anything about the warnings, pass no arguments as the expected warning type and it will default to a generic Warning: @@ -361,7 +361,7 @@ pass no arguments as the expected warning type and it will default to a generic assert str(record[0].message) == "user" assert str(record[1].message) == "runtime" -The :func:`recwarn <_pytest.recwarn.recwarn>` fixture will record warnings for the whole function: +The :fixture:`recwarn` fixture will record warnings for the whole function: .. code-block:: python @@ -377,7 +377,7 @@ The :func:`recwarn <_pytest.recwarn.recwarn>` fixture will record warnings for t assert w.filename assert w.lineno -Both the :func:`recwarn <_pytest.recwarn.recwarn>` fixture and the :func:`pytest.warns` context manager return the same interface for recorded +Both the :fixture:`recwarn` fixture and the :func:`pytest.warns` context manager return the same interface for recorded warnings: a :class:`~_pytest.recwarn.WarningsRecorder` instance. To view the recorded warnings, you can iterate over this instance, call ``len`` on it to get the number of recorded warnings, or index into it to get a particular recorded warning.