[IPython-user] doctests

Fernando Perez fperez.net at gmail.com
Wed Jan 3 12:29:27 CST 2007

On 1/2/07, belinda thom <bthom at cs.hmc.edu> wrote:
> Hello,
> I was hoping I might be able to run doctest scripts from w/in
> ipython, but it appears to not be possible.
> In particular, I get the following kinds of errors w/in ipython
> (which don't show up when using python):
> Trying:
>      t.name()
> Expecting:
>      'Tic-Tac-Toe 3-by-3 wins comprised of 3 contiguous pieces'
> Out[63]: 'Tic-Tac-Toe 3-by-3 wins comprised of 3 contiguous pieces'
> It seems the main problem is the "Out[63]:" header. Is there a way to
> strip these off these output prompts just for the period that such
> tests are running?
> I've tried this using both the magic run and calling directly from
> the cmd line (e.g. importing and then calling the "do_test" function
> in a __name__ == __main__ block; both yield the same behavior.
> Any insight you might have appreciated (or if you've got a better
> general purpose way to test .txt files, I'm all ears).

There are a couple of solutions:

1. You can use ipython's irunner to execute a simple .py file and
produce doctest-valid output.  I use this a lot in other projects, and
I've recently checked this support into ipython's dev branch:


These 3 template files are used for setting up testing for any new
module in a project, so that normal unittests, in-docstring doctests
and doctests contained in a .txt file are all gathered as a single
comprehensive test suite.  The driver script hasn't been checked in
yet, but I can mail you a copy if you need it before we're done with
this (I have one from another project).

2. You can have a profile for ipython which modifies its prompts so
they are more doctest-compatible.  I personally have a profile (I call
it doctest) which uses this:

# include base config and only add some extras
include ipythonrc

# Configure prompts and exceptions so we can copy/paste into docstrings and
# have the result be a valid doctest with minimal tweaking.
prompt_in1 '\n\#>\n>>> '
prompt_in2 '... '
prompt_out ''

pprint 0

separate_in 0

xmode plain


This profile makes it easy to copy/paste small chunks from an ipython
session into docstrings, but still lets me know where in the number
sequence I am (I use numbered prompts a lot for recalling previous
results).   I only need to delete the number lines after pasting,
which is OK for small things.

3. It is possible to modify the Python doctest module so that it
recognizes ipython's prompts correctly, and so that one could use
normal ipython sessions in a docstring.  This is unfortunately not a
completely trivial exercise, but a good chunk of it is already done in
my private branch.  I hope to finish this soon and commit it, so that
it becomes possible to just paste any old ipython input into a
dosctring as a doctest.

I hope this helps,


More information about the IPython-user mailing list