Repository: pandas-dev/pandas

Issue:
API: add testing functions to public API ?
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)



Discussion:
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.

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

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.

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

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"

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)

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.

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

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

@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)


Resolving patch:
diff --git a/pandas/__init__.py b/pandas/__init__.py
--- a/pandas/__init__.py
+++ b/pandas/__init__.py
@@ -64,6 +64,7 @@
 from pandas.util.print_versions import show_versions
 from pandas.io.api import *
 from pandas.util._tester import test
+import pandas.testing
 
 # extension module deprecations
 from pandas.util.depr_module import _DeprecatedModule


Test patch:
diff --git a/pandas/testing.py b/pandas/testing.py
new file mode 100644
--- /dev/null
+++ b/pandas/testing.py
@@ -0,0 +1,8 @@
+# flake8: noqa
+
+"""
+Public testing utility functions.
+"""
+
+from pandas.util.testing import (
+    assert_frame_equal, assert_series_equal, assert_index_equal)
diff --git a/pandas/tests/api/test_api.py b/pandas/tests/api/test_api.py
--- a/pandas/tests/api/test_api.py
+++ b/pandas/tests/api/test_api.py
@@ -32,7 +32,7 @@ class TestPDApi(Base, tm.TestCase):
     # top-level sub-packages
     lib = ['api', 'compat', 'core',
            'indexes', 'errors', 'pandas',
-           'plotting', 'test', 'tools', 'tseries',
+           'plotting', 'test', 'testing', 'tools', 'tseries',
            'util', 'options', 'io']
 
     # these are already deprecated; awaiting removal
@@ -128,6 +128,17 @@ def test_api(self):
         self.check(api, self.allowed)
 
 
+class TestTesting(Base):
+
+    funcs = ['assert_frame_equal', 'assert_series_equal',
+             'assert_index_equal']
+
+    def test_testing(self):
+
+        from pandas import testing
+        self.check(testing, self.funcs)
+
+
 class TestDatetoolsDeprecation(tm.TestCase):
 
     def test_deprecation_access_func(self):
diff --git a/pandas/util/testing.py b/pandas/util/testing.py
--- a/pandas/util/testing.py
+++ b/pandas/util/testing.py
@@ -861,7 +861,7 @@ def assert_index_equal(left, right, exact='equiv', check_names=True,
     right : Index
     exact : bool / string {'equiv'}, default False
         Whether to check the Index class, dtype and inferred_type
-        are identical. If 'equiv', then RangeIndex can be substitued for
+        are identical. If 'equiv', then RangeIndex can be substituted for
         Int64Index as well
     check_names : bool, default True
         Whether to check the names attribute.