gh-117364: Add doctest.SkipTest to skip all or some doctest examples

[sobolevn]

I ended up with an exception instead of a decorator. Several reasons:

1. Exception allows skipping some parts of doctest, giving more flexibility:

>>> 'is not ' + 'skipped'
'is not skipped'

>>> import doctest
>>> raise doctest.SkipTest("All examples after are skipped")

>>> 'skipped'
'not checked'

2. It will work with testsource and other text-based features. While @skip_if decorator required real objects with attributes.
3. The API change is simplier with an exception. It only adds one new object. While decorator required a lot of new parameters in existing functions.

• Issue: Consider adding doctest.skip_if decorator #117364

---

📚 Documentation preview 📚: https://cpython-previews--122935.org.readthedocs.build/

[sobolevn]

@serhiy-storchaka friendly ping :)

[serhiy-storchaka]

Thank you for the reminder @sobolevn.

I worked on better integration of doctests with unittests (#108885). In these plans every doctest example is counted as a subtest. Raising unittest.SkipTest only skips a single subtest, not all following subtests. This difference between unittest.SkipTest and doctest.SkipTest may be confusing. On other hand, raising unittest.SkipTest outside of a subTest() block skips the whole test. Since the line that raises doctest.SkipTest does not have an expected output or traceback, it may be not counted as example.

So I want to try to make more progress on that issue first. Than we will see how it works together and what API is better for skipping doctests.

[sobolevn]

Thanks for the info, would love to see better unittest + doctest intergration. Marking this as a draft for now.