DEPR: deprecate pandas.tests

doc/source/whatsnew/v1.5.0.rst

@@ -771,6 +771,7 @@ Other Deprecations
 - Clarified warning from :func:`to_datetime` when delimited dates can't be parsed in accordance to specified ``dayfirst`` argument (:issue:`46210`)
 - Deprecated :class:`Series` and :class:`Resampler` reducers (e.g. ``min``, ``max``, ``sum``, ``mean``) raising a ``NotImplementedError`` when the dtype is non-numric and ``numeric_only=True`` is provided; this will raise a ``TypeError`` in a future version (:issue:`47500`)
 - Deprecated :meth:`Series.rank` returning an empty result when the dtype is non-numeric and ``numeric_only=True`` is provided; this will raise a ``TypeError`` in a future version (:issue:`47500`)
+- Deprecated the module ``pandas.tests``. It will be private in the future and renamed to to ``pandas._tests`` (:issue:`46651`)
 
 .. ---------------------------------------------------------------------------
 .. _whatsnew_150.performance:

pandas/tests/__init__.py

@@ -0,0 +1,7 @@
+from warnings import warn
+
+warn(
+    "pandas.tests is considered to be private and will be renamed "
+    "to pandas._tests in the future.",
+    DeprecationWarning,
+)

pandas/tests/test_common.py

@@ -1,6 +1,8 @@
 import collections
 from functools import partial
 import string
+import subprocess
+import sys
 
 import numpy as np
 import pytest
@@ -229,3 +231,16 @@ def test_temp_setattr(with_exception):
                 raise ValueError("Inside exception raised")
         raise ValueError("Outside exception raised")
     assert ser.name == "first"
+
+
+def test_private_tests():
+    # GH 47738
+    output = subprocess.check_output(
+        [sys.executable, "-W", "default", "-c", '"from pandas import tests"'],
+        stderr=subprocess.STDOUT,
+    )
+    msg = (
+        "DeprecationWarning: pandas.tests is considered to be private and "
+        "will be renamed to pandas._tests in the future."
+    )
+    assert msg in output.decode()

pandas/util/_tester.py

@@ -5,6 +5,7 @@
 
 import os
 import sys
+import warnings
 
 from pandas.compat._optional import import_optional_dependency
 
@@ -22,6 +23,11 @@ def test(extra_args: list[str] | None = None):
     extra_args : list[str], default None
         Extra marks to run the tests.
     """
+    # prevent pytest from containing the pandas/tests deprecation
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", category=DeprecationWarning)
+        from pandas import tests
+
     pytest = import_optional_dependency("pytest")
     import_optional_dependency("hypothesis")
     cmd = ["--skip-slow", "--skip-network", "--skip-db"]