From d73b49d75dc29838701980835af7977c9f2a7215 Mon Sep 17 00:00:00 2001 From: vin01 Date: Thu, 26 Jan 2023 22:45:59 +0100 Subject: [PATCH] Clarify docs for `match` regarding escaping Add example using `re.escape` to escape arbitrary literal strings which might contain regular expression characters like ( or . --- doc/en/how-to/capture-warnings.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/en/how-to/capture-warnings.rst b/doc/en/how-to/capture-warnings.rst index 91565002c..2e71247a2 100644 --- a/doc/en/how-to/capture-warnings.rst +++ b/doc/en/how-to/capture-warnings.rst @@ -270,7 +270,11 @@ which works in a similar manner to :ref:`raises ` (except that warnings.warn("my warning", UserWarning) The test will fail if the warning in question is not raised. Use the keyword -argument ``match`` to assert that the warning matches a text or regex:: +argument ``match`` to assert that the warning matches a text or regex. +To match a literal string that may contain regular expression metacharacters like ``(`` or ``.``, the pattern can +first be escaped with ``re.escape``. + +Some examples: >>> with warns(UserWarning, match='must be 0 or None'): ... warnings.warn("value must be 0 or None", UserWarning) @@ -284,6 +288,9 @@ argument ``match`` to assert that the warning matches a text or regex:: ... Failed: DID NOT WARN. No warnings of type ...UserWarning... were emitted... + >>> with warns(UserWarning, match=re.escape('issue with foo() func')): + ... warnings.warn("issue with foo() func") + You can also call :func:`pytest.warns` on a function or code string: .. code-block:: python