create (and run) doctests in the docstrings

[brentp]

there are some docstrings in the code already but they arent quite in doctest format.
having them run as part of the test-suite--and the stuff in feature.py would be nice.

[daler]

working on this, but hit a roadblock with an annoying problem caused by, in __init__.py:

from bedtool import bedtool

From IPython and the test suite, this works no prob:

import pybedtools
a = pybedtools.example_bedtool('a.bed')

But from a doctest within bedtool.py, this gives a "module not callable" error:

a = pybedtools.example_bedtool('a.bed')

Seems like some sort of name clash within the doctest execution context. The only solution I could come up with is renaming bedtool.py to bedtool_base.py. Then __init__.py has this instead:

from bedtool_base import bedtool

and the docstrings work. Lame, I know, but it's all I could get to work.

[daler]

also, i decided to let the test suite do the checking of actual results. Otherwise, to get the doctests to pass, you need <BLANKLINE> and the #doctest: +NORMALIZE_WHITESPACE directive each time, which clutters the docstrings for interactive use. For example, this is a nice complete doctest, but it's uuuugly:

    Example usage::

        >>> # create new bedtool object
        >>> a = pybedtools.example_bedtool('a.bed')

        # get overlaps with "b.bed"
        >>> b_fn = pybedtools.example_bed_fn('b.bed')
        >>> overlaps = a.intersect(b_fn)
        >>> print overlaps #doctest: +NORMALIZE_WHITESPACE 
        chr1 155 200 feature2  0 +
        chr1 155 200 feature3  0 -
        chr1 900 901 feature4  0 +
        <BLANKLINE>

So it's simply replaced by

    Example usage::

        >>> # create new bedtool object
        >>> a = pybedtools.example_bedtool('a.bed')

        # get overlaps with "b.bed"
        >>> b_fn = pybedtools.example_bed_fn('b.bed')
        >>> overlaps = a.intersect(b_fn)

and the test suite does the "real" testing of expected output.

[brentp]

yeah, i think we can also send those flags to doctest.testmod()

for the first problem, did you try:

from .bedtool import bedtool

?

[daler]

I just tried the .bedtool relative import; that didn't work.

Turns out it was nosetests that was causing that import problem. Now that I'm using the standard doctest.testmod() in the bedtool.py module rather than having nose find the doctests, it works. So now I'm back to using the plain 'ol

from bedtool import bedtool

Docstring testing at the moment has to be done by running the bedtool module; hopefully sphinx's make doctest will run these eventually.

Also, sending the flags like you suggested to doctest.testmod() works like a charm.

So both problems solved!

[brentp]

when i run

nosetests --with-doctest --doctest-extension=.py .

from the base dir, i see the problem you mention above.
what do you think about renaming the class bedtool to BedTool? to avoid this?

[daler]

yeah, prob a good PEP8 move to do this. I'm working on some doctests on the bits of downtime I have today, so I'll work on changing this over in the code and in the tests.

Another issue is that I can't find a way to pass doctest optionflags to nosetests. (specifically +NORMALIZE_WHITESPACE). There's a patch floating around to provide --doctest-options, but I don't want to rely on a patched nosetests. Any ideas for this?

[brentp]

i've just converted the whole set, yeah, now only having problems with flags to nosetests

[brentp]

brentp@0de20ba

SHA: 0de20ba

[daler]

Sweet, thanks. Merged it.

[daler]

Re: optionflags . . .

The reason for wanting to pass +normalize_whitespace to nosetests is so that in the source code, all tabs in expected output can be converted to spaces. I initially wanted to do this to avoid potential ambiguous whitespace issues in the python source.

But maybe it's worth putting the tabs back in,

1. to get nosetests to run, and
2. as an additional test to make sure things really are giving output that has tabs, which is what BEDTools is expecting.

What do you think?

[brentp]

cool. (fyi, i left all the sphinx stuffs unchanged)

[brentp]

re whitespace, your call, can also use output spariingly in the doctests and just test for equality:

>>> str(bed_line) == expected
True

but yes, getting the tests to run through nose as well would be convenient.

[daler]

ok, this should work in the base dir:

nosetests --with-coverage

i removed lots of output from function and method doctests . . . this means they're not very rigorous at the moment, but i think i'd rather keep the rigorous tests in test1.py anyway. eventually i'll probably add minor equality tests like you suggest.

also, i learned about the doctest_global_setup config value for sphinx's doctest plugin, which now lets this run doctest within the docs and then compile 'em all (when run from the docs dir):

make doctest html latexpdf