Remove use of the DataFrame interchange protocol in favor of the Arrow

PyCapsule interface; add top-level objects "DataFrame" and "ArrowArray"
for consistency with the rest of the package.

Author: anthony-tuininga

doc/src/api_manual/async_connection.rst

@@ -147,7 +147,7 @@ AsyncConnection Methods
 
     .. note::
 
-        The data frame support in python-oracledb 3.2 is a pre-release and may
+        The data frame support in python-oracledb 3.3 is a pre-release and may
         change in a future version.
 
     .. versionadded:: 3.0.0
@@ -175,7 +175,7 @@ AsyncConnection Methods
 
     .. note::
 
-        The data frame support in python-oracledb 3.2 is a pre-release and may
+        The data frame support in python-oracledb 3.3 is a pre-release and may
         change in a future version.
 
     .. versionadded:: 3.0.0

doc/src/api_manual/connection.rst

@@ -140,7 +140,7 @@ Connection Methods
 
     .. note::
 
-        The data frame support in python-oracledb 3.2 is a pre-release and may
+        The data frame support in python-oracledb 3.3 is a pre-release and may
         change in a future version.
 
     .. dbapimethodextension::
@@ -172,7 +172,7 @@ Connection Methods
 
     .. note::
 
-        The data frame support in python-oracledb 3.2 is a pre-release and may
+        The data frame support in python-oracledb 3.3 is a pre-release and may
         change in a future version.
 
     .. dbapimethodextension::

doc/src/api_manual/dataframe.rst

@@ -13,7 +13,7 @@ from Oracle Database types to Arrow data types.
 
 .. note::
 
-    The data frame support in python-oracledb 3.2 is a pre-release and may
+    The data frame support in python-oracledb 3.3 is a pre-release and may
     change in a future version.
 
 .. _oracledataframeobj:
@@ -37,45 +37,25 @@ interface, giving access to the underlying Arrow array.
 OracleDataFrame Methods
 -----------------------
 
-The object implements the Python DataFrame Interchange Protocol `DataFrame API
-Interface <https://data-apis.org/dataframe-protocol/latest/API.html>`__
-
 .. method:: OracleDataFrame.column_arrays()
 
     Returns a list of :ref:`OracleArrowArray <oraclearrowarrayobj>` objects,
     each containing a select list column.
 
-    This is an extension to the DataFrame Interchange Protocol.
-
 .. method:: OracleDataFrame.column_names()
 
     Returns a list of the column names in the data frame.
 
-.. method:: OracleDataFrame.get_chunks(n_chunks)
-
-    Returns itself, since python-oracledb only uses one chunk.
-
 .. method:: OracleDataFrame.get_column(i)
 
-    Returns an :ref:`OracleColumn <oraclearrowarrayobj>` object for the column
+    Returns an :ref:`OracleArrowArray <oraclearrowarrayobj>` object for the column
     at the given index ``i``.
 
 .. method:: OracleDataFrame.get_column_by_name(name)
 
-    Returns an :ref:`OracleColumn <oraclearrowarrayobj>` object for the column
+    Returns an :ref:`OracleArrowArray <oraclearrowarrayobj>` object for the column
     with the given name ``name``.
 
-.. method:: OracleDataFrame.get_columns()
-
-    Returns a list of :ref:`OracleColumn <oraclearrowarrayobj>` objects, one
-    object for each column in the data frame.
-
-.. method:: OracleDataFrame.num_chunks()
-
-    Return the number of chunks the data frame consists of.
-
-    This always returns 1.
-
 .. method:: OracleDataFrame.num_columns()
 
    Returns the number of columns in the data frame.
@@ -109,120 +89,3 @@ These are used for conversion to `PyArrow Tables
 :ref:`dataframeformat`.
 
 .. versionadded:: 3.0.0
-
-.. _oraclecolumnobj:
-
-OracleColumn Objects
-====================
-
-OracleColumn objects are returned by :meth:`OracleDataFrame.get_column()`,
-:meth:`OracleDataFrame.get_column_by_name()`, and
-:meth:`OracleDataFrame.get_columns()`.
-
-.. versionadded:: 3.0.0
-
-.. _oraclecolumnmeth:
-
-OracleColumn Methods
---------------------
-
-.. method:: OracleColumn.get_buffers()
-
-    Returns a dictionary containing the underlying buffers.
-
-    The returned dictionary contains the ``data``, ``validity``, and ``offset``
-    keys.
-
-    The ``data`` attribute is a two-element tuple whose first element is a
-    buffer containing the data and whose second element is the data buffer's
-    associated dtype.
-
-    The ``validity`` attribute is a a two-element tuple whose first element
-    is a buffer containing mask values indicating missing data and whose
-    second element is the mask value buffer's associated dtype. The value of
-    this attribute is *None* if the null representation is not a bit or byte
-    mask.
-
-    The ``offset`` attribute is a two-element tuple whose first element is a
-    buffer containing the offset values for variable-size binary data (for
-    example, variable-length strings) and whose second element is the offsets
-    buffer's associated dtype. The value of this attribute is *None* if the
-    data buffer does not have an associated offsets buffer.
-
-.. method:: OracleColumn.get_chunks(n_chunks)
-
-    Returns itself, since python-oracledb only uses one chunk.
-
-.. method:: OracleColumn.num_chunks()
-
-    Returns the number of chunks the column consists of.
-
-    This always returns 1.
-
-.. method:: OracleColumn.size()
-
-    Returns the number of rows in the column.
-
-.. _oraclecolumnattr:
-
-OracleColumn Attributes
------------------------
-
-.. attribute:: OracleColumn.describe_null
-
-    This read-only property returns the description of the null representation
-    that the column uses.
-
-.. attribute:: OracleColumn.dtype
-
-    This read-only attribute returns the Dtype description as a tuple
-    containing the values for the attributes ``kind``, ``bit-width``,
-    ``format string``, and ``endianess``.
-
-    The ``kind`` attribute specifies the type of the data.
-
-    The ``bit-width`` attribute specifies the number of bits as an integer.
-
-    The ``format string`` attribute specifies the data type description format
-    string in Apache Arrow C Data Interface format.
-
-    The ``endianess`` attribute specifies the byte order of the data type.
-    Currently, only native endianess is supported.
-
-.. attribute:: OracleColumn.metadata
-
-    This read-only attribute returns the metadata for the column as a
-    dictionary with string keys.
-
-.. attribute:: OracleColumn.null_count
-
-    This read-only attribute returns the number of null row values, if known.
-
-.. attribute:: OracleColumn.offset
-
-    This read-only attribute specifies the offset of the first row.
-
-.. _oraclecolumnbufferobj:
-
-OracleColumnBuffer Objects
-==========================
-
-A buffer object backed by an ArrowArray consisting of a single chunk.
-
-This is an internal class used for conversion to third party data frames.
-
-.. versionadded:: 3.0.0
-
-.. _oraclecolumnbufferattr:
-
-OracleColumnBuffer Attributes
------------------------------
-
-.. attribute:: OracleColumnBuffer.bufsize
-
-    This read-only property returns the buffer size in bytes.
-
-.. attribute:: OracleColumnBuffer.ptr
-
-    This read-only attribute specifies the pointer to the start of the buffer
-    as an integer.

doc/src/release_notes.rst

@@ -33,6 +33,16 @@ Thick Mode Changes
 Common Changes
 ++++++++++++++
 
+#)  Changes to :ref:`data frame <dataframeformat>` support:
+
+    - Remove use of the DataFrame Interchange Protocol in
+      :ref:`OracleDataFrames <oracledataframeobj>`.
+    - Documentation on methods and attributes on the ``DataFrame`` and
+      ``ArrowArray`` objects are now available in Python plugins such as those
+      found in VS Code
+
+    Note the data frame support in python-oracledb 3.3 is a pre-release, and
+    may change in a future version
 
 oracledb `3.2.0 <https://github.com/oracle/python-oracledb/compare/v3.1.1...v3.2.0>`__ (June 2025)
 --------------------------------------------------------------------------------------------------

doc/src/user_guide/dataframes.rst

@@ -18,7 +18,7 @@ frame objects of other libraries.
 
 .. note::
 
-    The data frame support in python-oracledb 3.2 is a pre-release and may
+    The data frame support in python-oracledb 3.3 is a pre-release and may
     change in a future version.
 
 **Fetching Data Frames**

setup.cfg

@@ -44,7 +44,6 @@ test_suite = tests
 packages =
     oracledb
     oracledb.plugins
-    oracledb.interchange
 package_dir =
     =src
 

setup.py

@@ -31,13 +31,18 @@
 # base source directory
 source_dir = os.path.join("src", "oracledb")
 
-# determine the nanoarrow bridge dependent source files (included)
-base_dir = os.path.join(source_dir, "interchange")
-nanoarrow_bridge_depends = [
-    os.path.join(base_dir, "nanoarrow", "nanoarrow.c"),
-    os.path.join(base_dir, "nanoarrow", "nanoarrow.h"),
+# determine the Arrow dependent source files (included)
+impl_dir = os.path.join(source_dir, "impl", "arrow")
+nanoarrow_include_dir = os.path.join(impl_dir, "nanoarrow")
+arrow_depends = [
+    os.path.join(impl_dir, n)
+    for n in sorted(os.listdir(impl_dir))
+    if n.endswith(".pyx") or n.endswith(".pxi") or n.endswith(".pxd")
 ]
-nanoarrow_bridge_pxd = os.path.join(base_dir, "nanoarrow_bridge.pxd")
+arrow_depends.append(os.path.join(nanoarrow_include_dir, "nanoarrow.c"))
+arrow_depends.append(os.path.join(nanoarrow_include_dir, "nanoarrow.h"))
+arrow_pxd = os.path.join(source_dir, "arrow_impl.pxd")
+arrow_depends.append(arrow_pxd)
 
 # determine the base implementation dependent source files (included)
 impl_dir = os.path.join(source_dir, "impl", "base")
@@ -47,7 +52,7 @@
     if n.endswith(".pyx")
 ]
 base_pxd = os.path.join(source_dir, "base_impl.pxd")
-base_depends.extend([base_pxd, nanoarrow_bridge_pxd])
+base_depends.extend([base_pxd, arrow_pxd])
 
 # determine the thick mode dependent source files (included)
 impl_dir = os.path.join(source_dir, "impl", "thick")
@@ -77,6 +82,7 @@
 ]
 thin_depends.append(base_pxd)
 
+
 # if the platform is macOS:
 #  - target the minimum OS version that current Python packages work with.
 #    (Use 'otool -l /path/to/python' and look for 'version' in the
@@ -99,14 +105,14 @@
         Extension(
             "oracledb.base_impl",
             sources=["src/oracledb/base_impl.pyx"],
-            include_dirs=["src/oracledb/interchange/nanoarrow"],
+            include_dirs=[nanoarrow_include_dir],
             depends=base_depends,
             extra_compile_args=extra_compile_args,
         ),
         Extension(
             "oracledb.thin_impl",
             sources=["src/oracledb/thin_impl.pyx"],
-            include_dirs=["src/oracledb/interchange/nanoarrow"],
+            include_dirs=[nanoarrow_include_dir],
             depends=thin_depends,
             extra_compile_args=extra_compile_args,
         ),
@@ -115,16 +121,16 @@
             sources=["src/oracledb/thick_impl.pyx"],
             include_dirs=[
                 "src/oracledb/impl/thick/odpi/include",
-                "src/oracledb/interchange/nanoarrow",
+                nanoarrow_include_dir,
             ],
             depends=thick_depends,
             extra_compile_args=extra_compile_args,
         ),
         Extension(
-            "oracledb.interchange.nanoarrow_bridge",
-            sources=["src/oracledb/interchange/nanoarrow_bridge.pyx"],
-            include_dirs=["src/oracledb/interchange/nanoarrow"],
-            depends=nanoarrow_bridge_depends,
+            "oracledb.arrow_impl",
+            sources=["src/oracledb/arrow_impl.pyx"],
+            include_dirs=[nanoarrow_include_dir],
+            depends=arrow_depends,
             extra_compile_args=extra_compile_args,
         ),
     ]

src/oracledb/__init__.py

@@ -316,8 +316,12 @@
     SparseVector as SparseVector,
 )
 
-from .interchange.dataframe import (
-    OracleDataFrame as OracleDataFrame,
+from .arrow_array import (
+    ArrowArray as ArrowArray,
+)
+
+from .dataframe import (
+    DataFrame as DataFrame,
 )
 
 from . import builtin_hooks