ENH: Implement DataFrame interchange protocol (#46141)

Author: vnlitvinov

doc/source/reference/frame.rst

@@ -391,3 +391,4 @@ Serialization / IO / conversion
    DataFrame.to_clipboard
    DataFrame.to_markdown
    DataFrame.style
+   DataFrame.__dataframe__

doc/source/reference/general_functions.rst

@@ -78,3 +78,10 @@ Hashing
 
    util.hash_array
    util.hash_pandas_object
+
+Importing from other DataFrame libraries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. autosummary::
+   :toctree: api/
+
+   api.exchange.from_dataframe

doc/source/whatsnew/v1.5.0.rst

@@ -14,6 +14,24 @@ including other versions of pandas.
 Enhancements
 ~~~~~~~~~~~~
 
+.. _whatsnew_150.enhancements.dataframe_exchange:
+
+DataFrame exchange protocol implementation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pandas now implement the DataFrame exchange API spec.
+See the full details on the API at https://data-apis.org/dataframe-protocol/latest/index.html
+
+The protocol consists of two parts:
+
+  - New method :meth:`DataFrame.__dataframe__` which produces the exchange object.
+    It effectively "exports" the Pandas dataframe as an exchange object so
+    any other library which has the protocol implemented can "import" that dataframe
+    without knowing anything about the producer except that it makes an exchange object.
+  - New function :func:`pandas.api.exchange.from_dataframe` which can take
+    an arbitrary exchange object from any conformant library and construct a
+    Pandas DataFrame out of it.
+
 .. _whatsnew_150.enhancements.styler:
 
 Styler

pandas/api/__init__.py

@@ -1,5 +1,6 @@
 """ public toolkit API """
 from pandas.api import (  # noqa:F401
+    exchange,
     extensions,
     indexers,
     types,

pandas/api/exchange/__init__.py

@@ -0,0 +1,8 @@
+"""
+Public API for DataFrame exchange protocol.
+"""
+
+from pandas.core.exchange.dataframe_protocol import DataFrame
+from pandas.core.exchange.from_dataframe import from_dataframe
+
+__all__ = ["from_dataframe", "DataFrame"]

pandas/core/exchange/__init__.py

@@ -0,0 +1,80 @@
+from typing import (
+    Optional,
+    Tuple,
+)
+
+import numpy as np
+from packaging import version
+
+from pandas.core.exchange.dataframe_protocol import (
+    Buffer,
+    DlpackDeviceType,
+)
+
+_NUMPY_HAS_DLPACK = version.parse(np.__version__) >= version.parse("1.22.0")
+
+
+class PandasBuffer(Buffer):
+    """
+    Data in the buffer is guaranteed to be contiguous in memory.
+    """
+
+    def __init__(self, x: np.ndarray, allow_copy: bool = True) -> None:
+        """
+        Handle only regular columns (= numpy arrays) for now.
+        """
+        if not x.strides == (x.dtype.itemsize,):
+            # The protocol does not support strided buffers, so a copy is
+            # necessary. If that's not allowed, we need to raise an exception.
+            if allow_copy:
+                x = x.copy()
+            else:
+                raise RuntimeError(
+                    "Exports cannot be zero-copy in the case "
+                    "of a non-contiguous buffer"
+                )
+
+        # Store the numpy array in which the data resides as a private
+        # attribute, so we can use it to retrieve the public attributes
+        self._x = x
+
+    @property
+    def bufsize(self) -> int:
+        """
+        Buffer size in bytes.
+        """
+        return self._x.size * self._x.dtype.itemsize
+
+    @property
+    def ptr(self) -> int:
+        """
+        Pointer to start of the buffer as an integer.
+        """
+        return self._x.__array_interface__["data"][0]
+
+    def __dlpack__(self):
+        """
+        Represent this structure as DLPack interface.
+        """
+        if _NUMPY_HAS_DLPACK:
+            return self._x.__dlpack__()
+        raise NotImplementedError("__dlpack__")
+
+    def __dlpack_device__(self) -> Tuple[DlpackDeviceType, Optional[int]]:
+        """
+        Device type and device ID for where the data in the buffer resides.
+        """
+        return (DlpackDeviceType.CPU, None)
+
+    def __repr__(self) -> str:
+        return (
+            "PandasBuffer("
+            + str(
+                {
+                    "bufsize": self.bufsize,
+                    "ptr": self.ptr,
+                    "device": self.__dlpack_device__()[0].name,
+                }
+            )
+            + ")"
+        )