DEPR: Deprecate DataFrame Interchange Protocol (#62920)

Author: MarcoGorelli

doc/source/whatsnew/v3.0.0.rst

@@ -739,6 +739,7 @@ Other Deprecations
 - Deprecated option "future.no_silent_downcasting", as it is no longer used. In a future version accessing this option will raise (:issue:`59502`)
 - Deprecated silent casting of non-datetime 'other' to datetime in :meth:`Series.combine_first` (:issue:`62931`)
 - Deprecated slicing on a :class:`Series` or :class:`DataFrame` with a :class:`DatetimeIndex` using a ``datetime.date`` object, explicitly cast to :class:`Timestamp` instead (:issue:`35830`)
+- Deprecated support for the Dataframe Interchange Protocol (:issue:`56732`)
 - Deprecated the 'inplace' keyword from :meth:`Resampler.interpolate`, as passing ``True`` raises ``AttributeError`` (:issue:`58690`)
 
 .. ---------------------------------------------------------------------------

pandas/conftest.py

@@ -135,12 +135,14 @@ def pytest_collection_modifyitems(items, config) -> None:
     # 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 = [
+        ("api.interchange.from_dataframe", ".*Interchange Protocol is deprecated"),
         ("is_int64_dtype", "is_int64_dtype is deprecated"),
         ("is_interval_dtype", "is_interval_dtype is deprecated"),
         ("is_period_dtype", "is_period_dtype is deprecated"),
         ("is_datetime64tz_dtype", "is_datetime64tz_dtype is deprecated"),
         ("is_categorical_dtype", "is_categorical_dtype is deprecated"),
         ("is_sparse", "is_sparse is deprecated"),
+        ("DataFrame.__dataframe__", "Interchange Protocol is deprecated"),
         ("DataFrameGroupBy.fillna", "DataFrameGroupBy.fillna is deprecated"),
         ("DataFrameGroupBy.corrwith", "DataFrameGroupBy.corrwith is deprecated"),
         ("NDFrame.replace", "Series.replace without 'value'"),

pandas/core/frame.py

@@ -916,6 +916,14 @@ def __dataframe__(
         """
         Return the dataframe interchange object implementing the interchange protocol.
 
+        .. deprecated:: 3.0.0
+
+            The Dataframe Interchange Protocol is deprecated.
+            For dataframe-agnostic code, you may want to look into:
+
+            - `Arrow PyCapsule Interface <https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html>`_
+            - `Narwhals <https://github.com/narwhals-dev/narwhals>`_
+
         .. note::
 
            For new development, we highly recommend using the Arrow C Data Interface
@@ -970,7 +978,14 @@ def __dataframe__(
         These methods (``column_names``, ``select_columns_by_name``) should work
         for any dataframe library which implements the interchange protocol.
         """
-
+        warnings.warn(
+            "The Dataframe Interchange Protocol is deprecated.\n"
+            "For dataframe-agnostic code, you may want to look into:\n"
+            "- Arrow PyCapsule Interface: https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html\n"
+            "- Narwhals: https://github.com/narwhals-dev/narwhals\n",
+            Pandas4Warning,
+            stacklevel=find_stack_level(),
+        )
         from pandas.core.interchange.dataframe import PandasDataFrameXchg
 
         return PandasDataFrameXchg(self, allow_copy=allow_copy)

pandas/core/interchange/from_dataframe.py

@@ -6,13 +6,16 @@
     Any,
     overload,
 )
+import warnings
 
 import numpy as np
 
 from pandas._config import using_string_dtype
 
 from pandas.compat._optional import import_optional_dependency
+from pandas.errors import Pandas4Warning
 from pandas.util._decorators import set_module
+from pandas.util._exceptions import find_stack_level
 
 import pandas as pd
 from pandas.core.interchange.dataframe_protocol import (
@@ -47,6 +50,9 @@ def from_dataframe(df, allow_copy: bool = True) -> pd.DataFrame:
        From pandas 3.0 onwards, `from_dataframe` uses the PyCapsule Interface,
        only falling back to the interchange protocol if that fails.
 
+       From pandas 4.0 onwards, that fallback will no longer be available and only
+       the PyCapsule Interface will be used.
+
     .. warning::
 
         Due to severe implementation issues, we recommend only considering using the
@@ -99,7 +105,14 @@ def from_dataframe(df, allow_copy: bool = True) -> pd.DataFrame:
             pa = import_optional_dependency("pyarrow", min_version="14.0.0")
         except ImportError:
             # fallback to _from_dataframe
-            pass
+            warnings.warn(
+                "Conversion using Arrow PyCapsule Interface failed due to "
+                "missing PyArrow>=14 dependency, falling back to (deprecated) "
+                "interchange protocol. We recommend that you install "
+                "PyArrow>=14.0.0.",
+                UserWarning,
+                stacklevel=find_stack_level(),
+            )
         else:
             try:
                 return pa.table(df).to_pandas(zero_copy_only=not allow_copy)
@@ -109,6 +122,15 @@ def from_dataframe(df, allow_copy: bool = True) -> pd.DataFrame:
     if not hasattr(df, "__dataframe__"):
         raise ValueError("`df` does not support __dataframe__")
 
+    warnings.warn(
+        "The Dataframe Interchange Protocol is deprecated.\n"
+        "For dataframe-agnostic code, you may want to look into:\n"
+        "- Arrow PyCapsule Interface: https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html\n"
+        "- Narwhals: https://github.com/narwhals-dev/narwhals\n",
+        Pandas4Warning,
+        stacklevel=find_stack_level(),
+    )
+
     return _from_dataframe(
         df.__dataframe__(allow_copy=allow_copy), allow_copy=allow_copy
     )