bug in doctest?

[Tim Peters]

[Alexander Schmolck]
> I ran into what I believe to be a bug in doctest and cost me
> quite a bit of time.

That's why it's called "a bug" <wink>.

> Isn't doctest meant to work pretty much with unmodified
> interactive session output (where that does make sense)?

It's a good start.  I instinctively edit out the ugly bits from interactive
shell sessions, though, so probably never tried a case like yours.

> I doesn't seem to treat comments correctly:
>
>    import doctest, test
>    def aTest():
>        r""">>> # A comment
>            ... print 'This is incorrectly ignored by doctest'
>            This output here really doesn't matter either... (but SHOULD)
>            >>>
>            """
>    doctest.testmod(test)

That does suck.  OTOH, why on Earth would you put a comment all by itself on
a PS1 line?  That's an unnatural use of the interactive shell.

> Doesn't produce any error. The print line and the (wrong) output
> following it are just ignored.

In fact, the code in _extract_examples() is still looking for "a real" PS1
line, and will ignore everything until it finds another line starting with
">>>".  It eventually finds your final

    >>>

line and ignores that too (because it's blank except for the ">>>").

> Changing '...' to '>>>' after the comment solves the problem,

Yes.  So would pasting in a "typical" interactive session and adding
comments as plain text afterwards, like

    A comment, or a paragraph of comments, or a rant about
    how stupid doctest is for not liking it if this comment
    block starts with PS1 markers.
    >>> print "This is incorrectly ignored by doctest"
    No it isn't.

> but that means editing the interactive session output.

Yes.  If you can come up with a patch that fixes your example without
breaking anything else (with fair warning that it will be tricky to do so --
in particular, doctest.py itself contains a doctest that's likely to break
if you change anything in this area), I'll integrate it.  Else, if you still
care <wink>, open a bug report on SourceForge.

> Also, wouldn't it be a good idea to (at least optionally) ignore memory
> adresses in instance repr's that follow the pattern:
>
>    <foo.Bar instance at 0x80d7624>

No:  doctest promises WYSIWYG.  For doc purposes, examples with embedded
addresses suck, precisely because they're not what the doc reader is going
to see when they try the example -- and the first word in doctest is still
"doc".  If foo is a new-style class,

    >>> type(foo.Bar())
    <class 'foo.Bar'>

is a better example.  doctest is primarly intended to help make docstrings
better (examples cab help a lot, but examples that don't work exactly as
advertised are going to confuse people), and that requires real effort on
the docstring author's part.  unittest, OTOH, will let you write tests that
pass no matter how badly things get broken <wink>.