pydoc output control for doctest cases

Feature or enhancement

#File: pydoc_end_demo.py
"""
I very much appreciate both the doctest and the pydoc features of python for small developement
tasks with minimum overhead.

A slight enhancement to pydoc as proposed in this example would further increase the usefulness.
"""

def rotated( sequence, distance=1 ):  # example to demonstrate the <pydoc-end> proposal
    """ Returns sequence rotated by distance number of elements.

    Examples:  # small number of test cases (to be included in the pydoc output) show the use of the function
        >>> rotated( ( "one", "two", "three", "four" ) )
        ('four', 'one', 'two', 'three')
        >>> rotated( [ 2, 3, 5, 7, 11, 13 ], 2 )
        [11, 13, 2, 3, 5, 7]
        >>> rotated( "abcdefgh", -3 )
        'defghabc'

    <pydoc-end>  # the proposed indicator string instructs pydoc to stop ouput here ((for this docstring))
    
    Doctests:    # exhaustive number of further test cases - not relevant for the api user
                 # but needed for test quality - without the proposal the test cases clutter the pydoc output
        >>> rotated( "abcde", 0 )
        'abcde'
        >>> rotated( "abcde", 5 )  # abs(distance) == len(sequence)
        'abcde'
        >>> rotated( "abcde", -5 )
        'abcde'
        
        >>> rotated( "abcde", 6 )  # abs(distance) > len(sequence)
        'eabcd'
        >>> rotated( "abcde", -6 )
        'bcdea'
        
        >>> rotated( "", 5 )  # empty sequence
        ''
        >>> rotated( [], -3 )
        []
    """
    length = len(sequence)
    if length == 0: return sequence
    dist = distance % length
    return sequence[-dist:] + sequence[:-dist]


if __name__ == "__main__":

   # run the doctest cases:
   print( ">>> doctest >>>" )
   import doctest
   doctest.testmod()
   print( "<<< doctest <<<" )

Pitch

extensive doctest cases will no more clutter pydoc output: A single source file is sufficient for concise user docu as well as for comprehensive doctest cases.

Comece examinando o comportamento proposto em pydoc_end_demo.py e como os pontos de entrada de pydoc e doctest tratam atualmente as docstrings. Determine a interação pretendida entre o marcador proposto e os casos de doctest e, em seguida, adicione cobertura mostrando que a documentação concisa continua visível enquanto os exemplos posteriores continuam testáveis.