API: add testing functions to public API ?

[jorisvandenbossche]

A lot of other projects that use pandas will (like to) use pandas testing functionality like assert_frame_equal in their test suite. Although the pandas testing functions are available in the namespace (#6188), they are not really 'officially' labeled as public API that other projects can use (and rely upon).
Numpy has a similar submodule numpy.testing (http://docs.scipy.org/doc/numpy/reference/routines.testing.html)

Some things we could do:

• make a selection of the functions in util.testing that we want to label as public
• add this list somewhere to the docs
• write docstrings for these public ones (the other could use that as well of course ..)
• add some tests for the public API
• I would also import them into a pandas.testing module, so it is this one we can publicly advertise (and users are less tempted to use other non-public functions in the pandas.util.testing namespace)

[jreback]

the 'official' way really to compare is actually .equals(...) or com.array_equivalent (which the testing functions use). So maybe make these more obvious as these are already API.

[rockg]

xref #9457 that discusses some improvements that can be made to these functions.

[jorisvandenbossche]

OK, but .equals() is a first class citizen method, and not designed for using in a test suite. Other people have still to write there own assert_ functions that use those (the assert_frame_equal has lots of other options like non-precise, checking index names, etc).
And com.array_equivalent is something we could put in a pandas.testing module to make it public.

[jreback]

ok, so the proposition is to make a public testing module that is the API for pandas testing functions, ok, onboard with that.

[jorisvandenbossche]

Yes indeed.
In the reasoning of "we define/provide a DataFrame object used by a lot of other projects, so we should also provide easy usable assert_ testing functionality for this object"

[jreback]

ok, so the proposal is to leave pandas.utils.testing and simply create a pandas.testing namespace that basically imports some of these names, ok, onboard with that. (and add to API docs / maybe actual docs)

[jorisvandenbossche]

That last one of pandas.testing is only a proposal of me, and certainly debatable. But I think this gives the advantage of a well defined/delineated testing module (I don't think we want to have everyting in util.testing as public?)
And that we can progressively make functions from pandas.util.testing public in pandas.testing as it seems appropriate.

It would also enable to clean up some of the functions (in argument names, defaults, ..) if this would be needed / deemed desired.

[shoyer]

pandas.testing seems like a good idea to me, too.

[bashtage]

This is a good idea - I use assert_(series,frame)_equal in both statsmodels and my own code.

[jorisvandenbossche]

@sinhrks as you are doing quite some work on the testing functions lately, you are maybe also interested in this one? (any way, I would like to do this for 0.17.0)