python comment in docstring

Question

I found this one out because some of the homework questions I met were tested by docstrings, and it gives me failures.

For example:

def foo(x):
    """
    >>> foo(5)
    25
    >>> foo(6)
    36  # Are you sure?
    """
    return x**2

if __name__ == '__main__':
    import doctest
    doctest.testmod(verbose=True)

The example above fails with:

Expected:
    36  # are you sure?
Got:
    36

I wonder if we are not supposed to add comment in docstring? Or there is a way to make python to ignore the comment in docstring?

sorry I added wrong comments, I will try and get back to you. — Viswanath Polaki, Nov 02 '18 at 05:51
@MadPhysicist Both answers are technically the same principle, but he responded earlier. — jxie0755, Nov 02 '18 at 19:07
@Code_Control_jxie0755. I agree. I just wanted to get the question off the unanswered queue. — Mad Physicist, Nov 02 '18 at 19:08
Usually it is better to use the docstring primarily for its original purpose and put the explanation of the doctest right before the doctest. It is shown right in the first example in the documentation: https://docs.python.org/3/library/doctest.html — pabouk - Ukraine stay strong, Nov 08 '21 at 09:16

score 5 · Accepted Answer · answered Nov 02 '18 at 06:09

You can just add your comments like below

>>> # comments are ignored

Reference https://docs.python.org/3/library/doctest.html

Note: This must not be a part of output so if you want to add comment then you can use a new line to write your comment. So in your case "36" line must not contain any other string other than output.

score 5 · Answer 2 · answered Nov 02 '18 at 06:29

Doctest works by capturing stdout from your command line. The text supplied in the test string must match your output exactly. Doctest has no way of knowing what type of data you are outputting: it can only compare text outputs. In your case it is an integer followed by a comment, but what if you did the following instead:

>>> print('36   # are you sure?')

Any comments you want to have must be in the executable lines:

>>> foo(6)  # are you sure?
36

This is not as visually appealing, perhaps, but serves nearly the same purpose and actually works. When a line with a comment is passed to the interpreter, the comment is handled correctly.

python comment in docstring

2 Answers2