DOC: Ignore certain doctest warnings (#47083)

Author: rhshadrach

pandas/conftest.py

@@ -105,6 +105,24 @@ def pytest_addoption(parser):
     )
 
 
+def ignore_doctest_warning(item: pytest.Item, path: str, message: str) -> None:
+    """Ignore doctest warning.
+
+    Parameters
+    ----------
+    item : pytest.Item
+        pytest test item.
+    path : str
+        Module path to Python object, e.g. "pandas.core.frame.DataFrame.append". A
+        warning will be filtered when item.name ends with in given path. So it is
+        sufficient to specify e.g. "DataFrame.append".
+    message : str
+        Message to be filtered.
+    """
+    if item.name.endswith(path):
+        item.add_marker(pytest.mark.filterwarnings(f"ignore:{message}"))
+
+
 def pytest_collection_modifyitems(items, config):
     skip_slow = config.getoption("--skip-slow")
     only_slow = config.getoption("--only-slow")
@@ -117,13 +135,34 @@ def pytest_collection_modifyitems(items, config):
         (pytest.mark.db, "db", skip_db, "--skip-db"),
     ]
 
+    # Warnings from doctests that can be ignored; place reason in comment above.
+    # Each entry specifies (path, message) - see the ignore_doctest_warning function
+    ignored_doctest_warnings = [
+        # Deprecations where the docstring will emit a warning
+        ("DataFrame.append", "The frame.append method is deprecated"),
+        ("Series.append", "The series.append method is deprecated"),
+        ("dtypes.common.is_categorical", "is_categorical is deprecated"),
+        ("Categorical.replace", "Categorical.replace is deprecated"),
+        ("dtypes.common.is_extension_type", "'is_extension_type' is deprecated"),
+        ("Index.is_mixed", "Index.is_mixed is deprecated"),
+        ("MultiIndex._is_lexsorted", "MultiIndex.is_lexsorted is deprecated"),
+        # Docstring divides by zero to show behavior difference
+        ("missing.mask_zero_div_zero", "divide by zero encountered"),
+        # Docstring demonstrates the call raises a warning
+        ("_validators.validate_axis_style_args", "Use named arguments"),
+    ]
+
     for item in items:
         if config.getoption("--doctest-modules") or config.getoption(
             "--doctest-cython", default=False
         ):
             # autouse=True for the add_doctest_imports can lead to expensive teardowns
             # since doctest_namespace is a session fixture
             item.add_marker(pytest.mark.usefixtures("add_doctest_imports"))
+
+            for path, message in ignored_doctest_warnings:
+                ignore_doctest_warning(item, path, message)
+
         # mark all tests in the pandas/tests/frame directory with "arraymanager"
         if "/frame/" in item.nodeid:
             item.add_marker(pytest.mark.arraymanager)

pyproject.toml

@@ -45,6 +45,12 @@ doctest_optionflags = [
 filterwarnings = [
   "error:Sparse:FutureWarning",
   "error:The SparseArray:FutureWarning",
+  # Deprecation gives warning on import during pytest collection
+  "ignore:pandas.core.index is deprecated:FutureWarning:importlib",
+  "ignore:pandas.util.testing is deprecated:FutureWarning:importlib",
+  # Will be fixed in numba 0.56: https://github.com/numba/numba/issues/7758
+  "ignore:`np.MachAr` is deprecated:DeprecationWarning:numba",
+
 ]
 junit_family = "xunit2"
 markers = [