Consider adding `doctest.skip_if` decorator

Feature or enhancement

Right now there's no way to skip the whole test / class doctest. You can only skip individual statements with # doctest: +SKIP

This causes problems in several use-cases:

• You have a doctest that should be skipped based on the platform
• We have doctests that should be skipped based on a resource availability
• Libraries might want to skip some doctests based on the Python version / any other lib version

Right now we have this hack:

https://github.com/python/cpython/blob/2e9be80c99f635c2f7761e8356b0260922d6e7a6/Lib/test/test_doctest/test_doctest.py#L727-L730

https://github.com/python/cpython/blob/2e9be80c99f635c2f7761e8356b0260922d6e7a6/Lib/test/test_doctest/test_doctest.py#L1999-L2003

https://github.com/python/cpython/blob/2e9be80c99f635c2f7761e8356b0260922d6e7a6/Lib/test/test_doctest/test_doctest.py#L2938-L2943

However, this is just test functions. For library functions it would be much harder to do.
You have to jiggle __doc__ attribute around.

Since https://github.com/python/cpython/pull/117297 we now have correct skipped count for doctest + unittest integration.

So, I propose adding this decorator to doctest.py

def skip_if(condition):
    def decorator(func):
        if condition and HAVE_DOCSTRINGS:
            func.__doc__ = ">>> pass  # doctest: +SKIP"
        return func
    return decorator

It will allow us skipping some tests conditionally with the proper reported results.

Refs https://github.com/python/cpython/pull/116758
CC @serhiy-storchaka and @furkanonder

Linked PRs

• gh-122935