TST: add details to the public modules test about how to check public-ness

1 files changed, 15 insertions, 0 deletions

diff --git a/numpy/tests/test_public_api.py b/numpy/tests/test_public_api.py
index 32e9f42d5..4d9066fc9 100644
--- a/numpy/tests/test_public_api.py
+++ b/numpy/tests/test_public_api.py
@@ -373,6 +373,21 @@ def test_all_modules_are_expected_2():
 
         import .lib.scimath as emath
 
+    To check if something in a module is (effectively) public, one can check if
+    there's anything in that namespace that's a public function/object but is
+    not exposed in a higher-level namespace.  For example for a `numpy.lib`
+    submodule::
+
+        mod = np.lib.mixins
+        for obj in mod.__all__:
+            if obj in np.__all__:
+                continue
+            elif obj in np.lib.__all__:
+                continue
+
+            else:
+                print(obj)
+
     """
     modnames = []