This issue is to add to the doctest module an easy way to obtain the number of doctest examples in a unittest.TestSuite instance returned by a call to the doctest.DocFileSuite() function.

The unittest.TestSuite class currently exposes a countTestCases() method that gives the number of TestCase instances inside a test suite.

However, this method isn't useful for determining how many doctest examples that the TestSuite instance returned by a call to DocFileSuite() contains, nor in particular whether the instance contains any actual tests.  Calling countTestCases() on the return value returns the number of files that were parsed and not the number of doctest examples.

In fact, getting the number of doctest examples contained in such a TestSuite is surprisingly obscure and seems to rely on implementation details and accessing private attributes.  Here is one way to do it (annotated with comments):

    paths = ['Doc/howto/ipaddress.rst', 'Doc/howto/unicode.rst']

    # The return value of DocFileSuite is a unittest.TestCase instance, and
    # each item in the return value is a doctest.DocFileCase instance (which
    # in turn is also a doctest.DocTestCase and unittest.TestCase instance).
    suite = doctest.DocFileSuite(*paths, module_relative=False)

    total = 0
    for case in suite:
        doc_test = case._dt_test  # a doctest.DocTest instance.
        total += len(doc_test.examples)

    print("total test cases:  %s" % suite.countTestCases())
    print("total examples:   %s" % total)

Ideally, you would just be able to do something like this instead:

    suite.countExamples()

Exposing a method like that would probably involve converting DocFileSuite from a simple function that returns a unittest.TestSuite into a class that subclasses unittest.TestSuite (so that the function becomes a constructor).