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.

Commencez par examiner le comportement proposé dans pydoc_end_demo.py et la manière dont les points d’entrée pydoc et doctest traitent actuellement les docstrings. Déterminez l’interaction prévue entre le marqueur proposé et les cas doctest, puis ajoutez une couverture montrant que la documentation concise reste visible tandis que les exemples suivants restent testables.