[Biopython-dev] Deprecating Bio.ParserSupport, Bio.Blast.NCBIStandalone

[Michiel de Hoon]

Hi Peter,

As we misunderstood each other, let me try once to make the case for putting test files in Bio/*. If I fail to convince you, let's either go back to the situation before Bio._utils, or remove the "if __name__ == '__main__':" stuff altogether.

First of all, if we use "if __name__ == '__main__':" to run the docstring tests, then those tests should pass if a user executes the script. Otherwise, we have installed some code that makes no sense outside of the distribution. This is also a problem with the os.path.isfile("Fasta/sweetpea.nu"), "Run from Tests/ folder"
solution, as after installation there is no Tests/ folder any more.

Suppose we make a subdirectory Examples in each module that uses docstring tests which need some data files, and put the data files in the Examples subdirectory. The docstring tests are supposed to be simple (full testing is done by the unittests), so the example data files can be tiny.

The docstring tests can then use
>>> record = SeqIO.read(open("Examples/sweetpea.nu"),"fasta")
which is simple enough.
The unit tests can switch to the appropriate directory when running the docstring tests.
A user, finding the example in the docstring tests, can try out the example directly, since the data file is provided together with the relevant module.
And since the data file is in the subdirectory Examples/, there is still some separation between the code and the data.

Best,
-Michiel.

--- On Fri, 2/1/13, Peter Cock <p.j.a.cock at googlemail.com> wrote:

> From: Peter Cock <p.j.a.cock at googlemail.com>
> Subject: Re: [Biopython-dev] Deprecating Bio.ParserSupport, Bio.Blast.NCBIStandalone
> To: "Michiel de Hoon" <mjldehoon at yahoo.com>
> Cc: "Wibowo Arindrarto" <w.arindrarto at gmail.com>, "BioPython-Dev Mailing List" <biopython-dev at biopython.org>
> Date: Friday, February 1, 2013, 7:14 AM
> >Wibowo Arindrarto <w.arindrarto at gmail.com>
> wrote:
> >> Just to be clear, we are:
> >>
> >> * changing all module's doctest file path to use
> relative
> >> paths (with
> >> respect to the module's location),
> >> * replacing the run_doctest() import with a simpler
> doctest
> >> import and
> >> `doctest.testmod()` in each module having this
> doctest
> >> * resorting to setUp and tearDown in the
> DocTestSuite in
> >> `run_tests.py` so that each module / submodule can
> find
> >> their test
> >> files
> >> * and refactoring all string functions in
> Bio._utils to
> >> Bio.Phylo and
> >> Bio.SearchIO, so that we can remove Bio._utils,
> >>
> >> right?
> >>
> >> I'd be happy to give this a shot if everyone feels
> the same
> >> :).
> >>
> 
> On Fri, Feb 1, 2013 at 11:23 AM, Michiel de Hoon <mjldehoon at yahoo.com>
> wrote:
> > Hi Bow,
> >
> > Yes, that is correct.
> > Responding to Peter's email: Peter, do you agree with
> this approach?
> >
> > Best,
> > -Michiel.
> 
> No. I think we have misunderstood each other on the doctest
> discussion :(
> 
> If we keep the test files under Tests/ (and I think that is
> best)
> then for example look at this doctest in Bio/SeqRecord.py
> 
>         >>> from Bio import
> SeqIO
>         >>> record =
> SeqIO.read(open("Fasta/sweetpea.nu"),"fasta")
>         >>> len(record)
>         309
> 
> That is currently written to assume it is run from the
> Tests/
> folder. If we write this assuming is it in the Bio/ folder
> where
> the Python file SeqRecord.py lives, it becomes:
> 
>         >>> from Bio import
> SeqIO
>         >>> record =
> SeqIO.read(open("../Tests/Fasta/sweetpea.nu"),"fasta")
>         >>> len(record)
>         309
> 
> I think a beginner would find that more confusing. It is
> also longer
> and we already have trouble with some lines exceeding 80
> chars.
> 
> Ideally there would be a nice way for doctests to specify
> the folder,
> and then we could use a simple filename like "sweetpea.nu"
> with
> no directories at all. But I don't think that is possible
> without us
> making the testing infrastructure even more complicated.
> 
> --
> 
> If we want to get rid of Bio._utils.run_doctest() (and the
> whole of
> the file Bio/_utils.py) then I would prefer reverting to the
> old situation
> prior to adding the Bio._utils.run_doctest() helper
> function.
> 
> If the repetitive code snippets to run the doctests of a
> module are a
> problem it can be shortened to something less flexible, for
> example
> in Bio/SeqRecord.py could use something very short like
> this:
> 
> if __name__ == "__main__":
>     assert os.path.isfile("Fasta/sweetpea.nu"),
> "Run from Tests/ folder"
>     import doctest
>     doctest.testmod(verbose=2)
> 
> Or, as I suggested before, we can remove these development
> convenience hooks completely?
> 
> --
> 
> On the subject of the string functions in Bio/_utils.py, I
> have no
> objection to moving them back under Bio.SearchIO and/or
> Bio.Phylo - which has advantages in terms of modularity (a
> good thing for preventing accidental side effects).
> 
> Regards,
> 
> Peter
>