Warning assertions

Assertions that a callable does or does not emit warnings.

Expected warning mixin (a pytest.warns-style assertion).

The front verbs (warns() / does_not_warn()) only record the expected warning category; the actual invocation happens in when_called_with(), which dispatches to the private handlers below.

warns

warns(warning: type[Warning] = Warning) -> Self

Asserts that val is callable and sets the expected warning category.

Just records the expectation, but never calls val. You must chain to when_called_with() to invoke val() inside a warning-capturing context. On success, the matched warning's message becomes the new val so you can chain further assertions on it.

Subclasses of the given category match, and the category defaults to the base Warning (which matches any warning).

Parameters:

Name	Type	Description	Default
warning	type[Warning]	the expected warning category (a Warning subclass)	Warning

Examples:

Usage:

assert_that(deprecated_func).warns(DeprecationWarning).when_called_with("foo")
assert_that(deprecated_func).warns(DeprecationWarning).when_called_with("foo").matches("since 2.6")

Returns:

Name	Type	Description
AssertionBuilder	Self	returns a new instance (now with the expected warning) to chain to when_called_with()

Note

Capturing warnings mutates process-global state, so this is not thread-safe across OS threads (the same caveat as pytest.warns). It is safe within a single thread, including multiple asyncio tasks on one event loop.

Source code in assertpy2/warning.py

def warns(self, warning: type[Warning] = Warning) -> Self:
    """Asserts that val is callable and sets the expected warning category.

    Just records the expectation, but never calls val.  You must chain to
    [`when_called_with()`][assertpy2.exception.ExceptionMixin.when_called_with] to invoke ``val()`` inside a
    warning-capturing context.  On success, the matched warning's message becomes the new val so
    you can chain further assertions on it.

    Subclasses of the given category match, and the category defaults to the base `Warning`
    (which matches any warning).

    Args:
        warning: the expected warning category (a `Warning` subclass)

    Examples:
        Usage:

            assert_that(deprecated_func).warns(DeprecationWarning).when_called_with("foo")
            assert_that(deprecated_func).warns(DeprecationWarning).when_called_with("foo").matches("since 2.6")

    Returns:
        AssertionBuilder: returns a new instance (now with the expected warning) to chain to
            [`when_called_with()`][assertpy2.exception.ExceptionMixin.when_called_with]

    Note:
        Capturing warnings mutates process-global state, so this is **not** thread-safe across OS
        threads (the same caveat as ``pytest.warns``).  It is safe within a single thread,
        including multiple ``asyncio`` tasks on one event loop.
    """
    return self._warning_builder(warning)

does_not_warn

does_not_warn(warning: type[Warning] = Warning) -> Self

Asserts that val is callable and sets the not-expected warning category.

Just records the expectation, but never calls val. You must chain to when_called_with() to invoke val() and assert that no warning of the given category is emitted. The category defaults to the base Warning (which forbids any warning).

Parameters:

Name	Type	Description	Default
warning	type[Warning]	the warning category that should not be emitted (a Warning subclass)	Warning

Examples:

Usage:

assert_that(safe_func).does_not_warn(DeprecationWarning).when_called_with("foo")

Returns:

Name	Type	Description
AssertionBuilder	Self	returns a new instance to chain to when_called_with()

Source code in assertpy2/warning.py

def does_not_warn(self, warning: type[Warning] = Warning) -> Self:
    """Asserts that val is callable and sets the not-expected warning category.

    Just records the expectation, but never calls val.  You must chain to
    [`when_called_with()`][assertpy2.exception.ExceptionMixin.when_called_with] to invoke ``val()`` and assert
    that no warning of the given category is emitted.  The category defaults to the base
    `Warning` (which forbids any warning).

    Args:
        warning: the warning category that should **not** be emitted (a `Warning` subclass)

    Examples:
        Usage:

            assert_that(safe_func).does_not_warn(DeprecationWarning).when_called_with("foo")

    Returns:
        AssertionBuilder: returns a new instance to chain to
            [`when_called_with()`][assertpy2.exception.ExceptionMixin.when_called_with]
    """
    new_builder = self._warning_builder(warning)
    new_builder._not_expected = True
    return new_builder